diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-08-19 12:08:42 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-08-19 12:08:42 +0300 |
| commit | b76ae638462ab0f673e5915986070518dd3f9ad3 (patch) | |
| tree | bdab0533383b52873be0ec0eb4d3c66598ff8b91 /doc/user | |
| parent | 434373eabe7b4be9593d18a585fb763f1e5f1a6f (diff) | |
Add latest changes from gitlab-org/gitlab@14-2-stable-eev14.2.0-rc42
Diffstat (limited to 'doc/user')
298 files changed, 3769 insertions, 2281 deletions
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md deleted file mode 100644 index c84c3541366..00000000000 --- a/doc/user/abuse_reports.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'report_abuse.md' -remove_date: '2021-07-21' ---- - -This file was moved to [another location](report_abuse.md). - -<!-- This redirect file can be deleted after <2021-07-21>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md deleted file mode 100644 index 4bfa277fc9f..00000000000 --- a/doc/user/admin_area/abuse_reports.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'review_abuse_reports.md' -remove_date: '2021-07-21' ---- - -This file was moved to [another location](review_abuse_reports.md). - -<!-- This redirect file can be deleted after <2021-07-21>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md deleted file mode 100644 index e89c42b34ba..00000000000 --- a/doc/user/admin_area/activating_deactivating_users.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'moderate_users.md' -remove_date: '2021-08-12' ---- - -This document was moved to [another location](moderate_users.md). - -<!-- This redirect file can be deleted after <2021-08-12>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index 89d8a5ea054..f07ccc11c60 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -40,12 +40,11 @@ feature is available. ## DevOps Adoption **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). -> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59267) in GitLab 14.0. -> - Enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-or-enable-devops-adoption). **(ULTIMATE SELF)** > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. +> - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. +> - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. +> - Multi-select [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. DevOps Adoption shows you which groups in your organization are using the most essential features of GitLab: @@ -56,36 +55,20 @@ DevOps Adoption shows you which groups in your organization are using the most e - Merge requests - Sec - DAST + - Dependency Scanning + - Fuzz Testing - SAST - Ops - Deployments - Pipelines - Runners -To add your groups, in the top right-hand section the page, select **Add group to table**. +To add or remove your groups, in the top right-hand section the page, select **Add or remove groups**. DevOps Adoption allows you to: - Verify whether you are getting the return on investment that you expected from GitLab. -- Identify specific groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. -- Find the groups that have adopted certain features and can provide guidance to other groups on how to use those features. +- Identify specific groups that are lagging in their adoption of GitLab, so you can help them along in their DevOps journey. +- Find the groups that have adopted certain features, and can provide guidance to other groups on how to use those features. - - -### Disable or enable DevOps Adoption - -DevOps Adoption is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To disable it: - -```ruby -Feature.disable(:devops_adoption_feature) -``` - -To reenable it: - -```ruby -Feature.enable(:devops_adoption_feature) -``` + diff --git a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_1.png b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_1.png Binary files differdeleted file mode 100644 index 79481e43e8e..00000000000 --- a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_1.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png Binary files differnew file mode 100644 index 00000000000..d4b3436f3ee --- /dev/null +++ b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 2852f73ffc8..fdf0c7edfc7 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -1,58 +1,9 @@ --- -stage: Manage -group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto +redirect_to: 'moderate_users.md' +remove_date: '2021-10-20' --- -# Users pending approval +This document was moved to [another location](moderate_users.md). -A user in _pending approval_ state requires action by an administrator. A user sign up can be in a -pending approval state because an administrator has enabled either, or both, of the following -options: - -- [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. -- [User cap](settings/sign_up_restrictions.md#user-cap). - -When a user registers for an account while this setting is enabled: - -- The user is placed in a **Pending approval** state. -- The user sees a message telling them their account is awaiting approval by an administrator. - -A user pending approval: - -- Is functionally identical to a [blocked](moderate_users.md#blocking-a-user) user. -- Cannot sign in. -- Cannot access Git repositories or the GitLab API. -- Does not receive any notifications from GitLab. -- Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). - -An administrator must [approve their sign up](#approve-or-reject-a-user-sign-up) to allow them to -sign in. - -## View user sign ups pending approval - -To view user sign ups pending approval: - -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. On the left sidebar, select **Overview > Users**. -1. Select the **Pending approval** tab. - -## Approve or reject a user sign up - -A user sign up pending approval can be approved or rejected from the Admin Area. - -To approve or reject a user sign up: - -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. On the left sidebar, select **Overview > Users**. -1. Select the **Pending approval** tab. -1. (Optional) Select a user. -1. Select the **{settings}** **User administration** dropdown. -1. Select **Approve** or **Reject**. - -Approving a user: - -- Activates their account. -- Changes the user's state to active. -- Consumes a subscription [seat](../../subscriptions/self_managed/index.md#billable-users). +<!-- This redirect file can be deleted after <2021-10-20>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md deleted file mode 100644 index e89c42b34ba..00000000000 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'moderate_users.md' -remove_date: '2021-08-12' ---- - -This document was moved to [another location](moderate_users.md). - -<!-- This redirect file can be deleted after <2021-08-12>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 12d143b3a13..8c0586e5851 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -18,9 +18,13 @@ is created, based on the user's access permissions: - Public projects can be selected by any signed-in user as a template for a new project, if all enabled [project features](../project/settings/index.md#sharing-and-permissions) - except for GitLab Pages are set to **Everyone With Access**. + except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. + The same applies to internal projects. - Private projects can be selected only by users who are members of the projects. +The **Metrics Dashboard** is set to **Only Project Members** when you create a new project. Make +sure you change it to **Everyone With Access** before making it a project template. + Repository and database information that are copied over to each new project are identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index 19a76d0938b..861d3644ab3 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -5,61 +5,60 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo nodes Admin Area **(PREMIUM SELF)** +# Geo sites Admin Area **(PREMIUM SELF)** -You can configure various settings for GitLab Geo nodes. For more information, see +You can configure various settings for GitLab Geo sites. For more information, see [Geo documentation](../../administration/geo/index.md). -On either the primary or secondary node: +On either the primary or secondary site: 1. On the top bar, select **Menu >** **{admin}** **Admin**. 1. On the left sidebar, select **Geo > Nodes**. ## Common settings -All Geo nodes have the following settings: +All Geo sites have the following settings: | Setting | Description | | --------| ----------- | -| Primary | This marks a Geo Node as **primary** node. There can be only one **primary** node; make sure that you first add the **primary** node and then all the others. | -| Name | The unique identifier for the Geo node. Must match the setting `gitlab_rails['geo_node_name']` in `/etc/gitlab/gitlab.rb`. The setting defaults to `external_url` with a trailing slash. | +| Primary | This marks a Geo site as **primary** site. There can be only one **primary** site. | +| Name | The unique identifier for the Geo site. It's highly recommended to use a physical location as a name. Good examples are "London Office" or "us-east-1". Avoid words like "primary", "secondary", "Geo", or "DR". This makes the failover process easier because the physical location does not change, but the Geo site role can. All nodes in a single Geo site use the same site name. Nodes use the `gitlab_rails['geo_node_name']` setting in `/etc/gitlab/gitlab.rb` to lookup their Geo site record in the PostgreSQL database. If `gitlab_rails['geo_node_name']` is not set, then the node's `external_url` with trailing slash is used as fallback. The value of `Name` is case-sensitive, and most characters are allowed. | | URL | The instance's user-facing URL. | -The node you're reading from is indicated with a green `Current node` label, and -the **primary** node is given a blue `Primary` label. Remember that you can only make -changes on the **primary** node! +The site you're currently browsing is indicated with a blue `Current` label, and +the **primary** node is listed first as `Primary site`. -## **Secondary** node settings +## **Secondary** site settings -**Secondary** nodes have a number of additional settings available: +**Secondary** sites have a number of additional settings available: | Setting | Description | |---------------------------|-------------| -| Selective synchronization | Enable Geo [selective sync](../../administration/geo/replication/configuration.md#selective-synchronization) for this **secondary** node. | -| Repository sync capacity | Number of concurrent requests this **secondary** node will make to the **primary** node when backfilling repositories. | -| File sync capacity | Number of concurrent requests this **secondary** node will make to the **primary** node when backfilling files. | +| Selective synchronization | Enable Geo [selective sync](../../administration/geo/replication/configuration.md#selective-synchronization) for this **secondary** site. | +| Repository sync capacity | Number of concurrent requests this **secondary** site will make to the **primary** site when backfilling repositories. | +| File sync capacity | Number of concurrent requests this **secondary** site will make to the **primary** site when backfilling files. | ## Geo backfill -**Secondary** nodes are notified of changes to repositories and files by the **primary** node, +**Secondary** sites are notified of changes to repositories and files by the **primary** site, and will always attempt to synchronize those changes as quickly as possible. -Backfill is the act of populating the **secondary** node with repositories and files that -existed *before* the **secondary** node was added to the database. Since there may be +Backfill is the act of populating the **secondary** site with repositories and files that +existed *before* the **secondary** site was added to the database. Since there may be extremely large numbers of repositories and files, it's infeasible to attempt to download them all at once, so GitLab places an upper limit on the concurrency of these operations. How long the backfill takes is a function of the maximum concurrency, but higher -values place more strain on the **primary** node. From [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3107), -the limits are configurable. If your **primary** node has lots of surplus capacity, +values place more strain on the **primary** site. From [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3107), +the limits are configurable. If your **primary** site has lots of surplus capacity, you can increase the values to complete backfill in a shorter time. If it's under heavy load and backfill is reducing its availability for normal requests, you can decrease them. ## Using a different URL for synchronization -The **primary** node's Internal URL is used by **secondary** nodes to contact it +The **primary** site's Internal URL is used by **secondary** sites to contact it (to sync repositories, for example). The name Internal URL distinguishes it from [External URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab) which is used by users. Internal URL does not need to be a private address. @@ -68,13 +67,13 @@ Internal URL defaults to external URL, but you can also customize it: 1. On the top bar, select **Menu >** **{admin}** **Admin**. 1. On the left sidebar, select **Geo > Nodes**. -1. Select **Edit** on the node you want to customize. +1. Select **Edit** on the site you want to customize. 1. Edit the internal URL. 1. Select **Save changes**. WARNING: -We recommend using an HTTPS connection while configuring the Geo nodes. To avoid -breaking communication between **primary** and **secondary** nodes when using +We recommend using an HTTPS connection while configuring the Geo sites. To avoid +breaking communication between **primary** and **secondary** sites when using HTTPS, customize your Internal URL to point to a load balancer with TLS terminated at the load balancer. @@ -84,14 +83,14 @@ using an internal URL that is not accessible to the users will result in the OAuth authorization flow not working properly, as the users will get redirected to the internal URL instead of the external one. -## Multiple secondary nodes behind a load balancer +## Multiple secondary sites behind a load balancer -In GitLab 11.11, **secondary** nodes can use identical external URLs as long as -a unique `name` is set for each Geo node. The `gitlab.rb` setting +In GitLab 11.11, **secondary** sites can use identical external URLs as long as +a unique `name` is set for each Geo site. The `gitlab.rb` setting `gitlab_rails['geo_node_name']` must: - Be set for each GitLab instance that runs `puma`, `sidekiq`, or `geo_logcursor`. -- Match a Geo node name. +- Match a Geo site name. The load balancer must use sticky sessions in order to avoid authentication failures and cross site request errors. diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 31fd1a3a0a1..35afb9f376b 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -121,8 +121,8 @@ To list users matching a specific criteria, click on one of the following tabs o - **2FA Enabled** - **2FA Disabled** - **External** -- **[Blocked](moderate_users.md#blocking-a-user)** -- **[Deactivated](moderate_users.md#deactivating-a-user)** +- **[Blocked](moderate_users.md#block-a-user)** +- **[Deactivated](moderate_users.md#deactivate-a-user)** - **Without projects** For each user, the following are listed: @@ -164,6 +164,8 @@ You can impersonate a user in the following ways: All impersonation activities are [captured with audit events](../../administration/audit_events.md#impersonation-data). +By default, impersonation is enabled. GitLab can be configured to [disable impersonation](../../api/index.md#disable-impersonation). +  #### User Permission Export **(PREMIUM SELF)** diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index db2db4a0e68..0431b0d1628 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -17,7 +17,7 @@ is locked. ## Activate GitLab EE with an Activation Code **(PREMIUM SELF)** -As of GitLab Enterprise Edition 14.0, you need an activation code to activate your instance. You can obtain an activation code by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). This activation code is a 24-character alphanumeric string you receive in a confirmation email. You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) to copy the activation code to your clipboard. +As of GitLab Enterprise Edition 14.1, you need an activation code to activate your instance. You can obtain an activation code by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). This activation code is a 24-character alphanumeric string you receive in a confirmation email. You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) to copy the activation code to your clipboard. To begin the activation process with your activation code: @@ -30,7 +30,7 @@ To begin the activation process with your activation code: ## Activate GitLab EE with a License File **(PREMIUM SELF)** -If you receive a license file from GitLab (for example a new trial), you can upload it by signing into your GitLab instance as an admin or adding it during installation. The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. +If you receive a license file from GitLab (for example a new trial), you can upload it by signing into your GitLab instance as an admin or adding it during installation. The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. ## Uploading your license @@ -153,6 +153,20 @@ additional users. More information on how to determine the required number of us and how to add additional seats can be found in the [licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). +In GitLab 14.2 and later, for instances that use a license file, you can exceed the number of purchased users and still activate your license. + +- If the users over license are less than or equal to 10% of the users in the subscription, + the license is applied and the overage is paid in the next true-up. +- If the users over license are more than 10% of the users in the subscription, + you cannot apply the license without purchasing more users. + +For example, if you purchased a license for 100 users, you can have 110 users when you activate +your license. However, if you have 111, you must purchase more users before you can activate. + ### There is a connectivity issue -In GitLab 14.0 and later, to activate your subscription, your GitLab instance must be connected to the internet. If you have questions or need assistance activating your instance please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). +In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. + +If you have an offline or airgapped environment, you can [upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. + +If you have questions or need assistance activating your instance, please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index b221b1d51a7..4f6419cdeb7 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -24,12 +24,12 @@ To enable merge request approval rules for an instance: Merge request approval rules that can be set at an instance level are: -- **Prevent approval of merge requests by merge request author**. Prevents project +- **Prevent approval by author**. Prevents project maintainers from allowing request authors to merge their own merge requests. -- **Prevent approval of merge requests by merge request committers**. Prevents project +- **Prevent approvals by users who add commits**. Prevents project maintainers from allowing users to approve merge requests if they have submitted any commits to the source branch. -- **Prevent users from modifying merge request approvers list**. Prevents users from +- **Prevent editing approval rules in projects and merge requests**. Prevents users from modifying the approvers list in project settings or in individual merge requests. Also read the [project level merge request approval rules](../project/merge_requests/approvals/index.md), which are affected by instance level rules. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 3889dd93d59..8211167895c 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -7,13 +7,66 @@ type: howto # Moderate users -GitLab administrators can moderate user access by blocking, banning, or deactivating users. +GitLab administrators can moderate user access by approving, blocking, banning, or deactivating +users. -## Blocking and unblocking users +## Users pending approval + +A user in _pending approval_ state requires action by an administrator. A user sign up can be in a +pending approval state because an administrator has enabled either, or both, of the following +options: + +- [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. +- [User cap](settings/sign_up_restrictions.md#user-cap). + +When a user registers for an account while this setting is enabled: + +- The user is placed in a **Pending approval** state. +- The user sees a message telling them their account is awaiting approval by an administrator. + +A user pending approval: + +- Is functionally identical to a [blocked](#block-a-user) user. +- Cannot sign in. +- Cannot access Git repositories or the GitLab API. +- Does not receive any notifications from GitLab. +- Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). + +An administrator must [approve their sign up](#approve-or-reject-a-user-sign-up) to allow them to +sign in. + +### View user sign ups pending approval + +To view user sign ups pending approval: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Pending approval** tab. + +### Approve or reject a user sign up + +A user sign up pending approval can be approved or rejected from the Admin Area. + +To approve or reject a user sign up: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Pending approval** tab. +1. (Optional) Select a user. +1. Select the **{settings}** **User administration** dropdown. +1. Select **Approve** or **Reject**. + +Approving a user: + +- Activates their account. +- Changes the user's state to active. +- Consumes a subscription [seat](../../subscriptions/self_managed/index.md#billable-users). + +## Block and unblock users GitLab administrators can block and unblock users. -### Blocking a user +### Block a user In order to completely prevent access of a user to the GitLab instance, administrators can choose to block the user. @@ -33,15 +86,14 @@ A blocked user: - Cannot access Git repositories or the API. - Does not receive any notifications from GitLab. - Cannot use [slash commands](../../integration/slash_commands.md). +- Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). Personal projects, and group and user history of the blocked user are left intact. -Users can also be blocked using the [GitLab API](../../api/users.md#block-user). - NOTE: -A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). +Users can also be blocked using the [GitLab API](../../api/users.md#block-user). -### Unblocking a user +### Unblock a user A blocked user can be unblocked from the Admin Area. To do this: @@ -52,24 +104,24 @@ A blocked user can be unblocked from the Admin Area. To do this: 1. Select the **{settings}** **User administration** dropdown. 1. Select **Unblock**. -Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). +The user's state is set to active and they consume a +[seat](../../subscriptions/self_managed/index.md#billable-users). NOTE: -Unblocking a user changes the user's state to active and consumes a -[seat](../../subscriptions/self_managed/index.md#billable-users). +Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). -## Activating and deactivating users +## Activate and deactivate users GitLab administrators can deactivate and activate users. -### Deactivating a user +### Deactivate a user > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. In order to temporarily prevent access by a GitLab user that has no recent activity, administrators can choose to deactivate the user. -Deactivating a user is functionally identical to [blocking a user](#blocking-and-unblocking-users), +Deactivating a user is functionally identical to [blocking a user](#block-and-unblock-users), with the following differences: - It does not prohibit the user from logging back in via the UI. @@ -80,6 +132,7 @@ A deactivated user: - Cannot access Git repositories or the API. - Does not receive any notifications from GitLab. - Does not be able to use [slash commands](../../integration/slash_commands.md). +- Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). Personal projects, and group and user history of the deactivated user are left intact. @@ -91,15 +144,13 @@ A user can be deactivated from the Admin Area. To do this: 1. Select the **{settings}** **User administration** dropdown. 1. Select **Deactivate**. -Please note that for the deactivation option to be visible to an admin, the user: +For the deactivation option to be visible to an admin, the user: - Must be currently active. - Must not have signed in, or have any activity, in the last 90 days. -Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). - NOTE: -A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). +Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). ### Automatically deactivate dormant users @@ -118,7 +169,7 @@ When this feature is enabled, GitLab runs a job once a day to deactivate the dor A maximum of 100,000 users can be deactivated per day. -### Activating a user +### Activate a user > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. @@ -133,29 +184,23 @@ To do this: 1. Select the **{settings}** **User administration** dropdown. 1. Select **Activate**. -Users can also be activated using the [GitLab API](../../api/users.md#activate-user). - -NOTE: -Activating a user changes the user's state to active and consumes a +The user's state is set to active and they consume a [seat](../../subscriptions/self_managed/index.md#billable-users). NOTE: A deactivated user can also activate their account themselves by logging back in via the UI. +Users can also be activated using the [GitLab API](../../api/users.md#activate-user). ## Ban and unban users -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 13.12. - -GitLab administrators can ban users. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2. -NOTE: -This feature is behind a feature flag that is disabled by default. GitLab administrators -with access to the GitLab Rails console can [enable](../../administration/feature_flags.md) -this feature for your GitLab instance. +GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. +The banned user's comments are still displayed. Hiding a banned user's comments is [tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327356). ### Ban a user -To completely block a user, administrators can choose to ban the user. +To block a user and hide their contributions, administrators can ban the user. Users can be banned using the Admin Area. To do this: @@ -165,10 +210,7 @@ Users can be banned using the Admin Area. To do this: 1. Select the **{settings}** **User administration** dropdown. 1. Select **Ban user**. -NOTE: -This feature is a work in progress. Currently, banning a user -only blocks them and does not hide their comments or issues. -This functionality is planned to be implemented in follow up issues. +The banned user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ### Unban a user @@ -181,6 +223,5 @@ A banned user can be unbanned using the Admin Area. To do this: 1. Select the **{settings}** **User administration** dropdown. 1. Select **Unban user**. -NOTE: -Unbanning a user changes the user's state to active and consumes a +The user's state is set to active and they consume a [seat](../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index cbaa4b30cb7..5765a530baf 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batched-background-migrations). **(FREE SELF)** -There can be [risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). +There can be [risks when disabling released features](../../../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. To update database tables in batches, GitLab can use batched background migrations. These migrations @@ -23,13 +23,8 @@ prevent integer overflow for some tables. ## Check the status of background migrations **(FREE SELF)** -All migrations must have a `Finished` status before updating GitLab. To check the status of the existing -migrations: - -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. On the left sidebar, select **Monitoring > Background Migrations**. - -  +All migrations must have a `Finished` status before you [upgrade GitLab](../../../update/index.md). +You can [check the status of existing migrations](../../../update/index.md#checking-for-background-migrations-before-upgrading). ## Enable or disable batched background migrations **(FREE SELF)** @@ -59,7 +54,7 @@ Feature.disable(:execute_batched_migrations_on_schedule) > - Recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-automatic-batch-size-optimization). **(FREE SELF)** -There can be [risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). +There can be [risks when disabling released features](../../../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. To maximize throughput of batched background migrations (in terms of the number of tuples updated per time unit), batch sizes are automatically adjusted based on how long the previous batches took to complete. diff --git a/doc/user/admin_area/monitoring/img/batched_background_migrations_queued_v14_0.png b/doc/user/admin_area/monitoring/img/batched_background_migrations_queued_v14_0.png Binary files differdeleted file mode 100644 index 0b0792b5e7a..00000000000 --- a/doc/user/admin_area/monitoring/img/batched_background_migrations_queued_v14_0.png +++ /dev/null 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 2b60ed5345b..71e05f44ef0 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -154,7 +154,12 @@ nginx['client_max_body_size'] = "200m" > - 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-two-factor-authentication-2fa-for-git-operations) +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-two-factor-authentication-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-two-factor-authentication-2fa-for-git-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 69d86259409..3b56318e711 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -18,7 +18,7 @@ for all projects: 1. On the top bar, select **Menu >** **{admin}** **Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. -1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/index.md#auto-devops-base-domain) +1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/requirements.md#auto-devops-base-domain) which is used for Auto Deploy and Auto Review Apps. 1. Hit **Save changes** for the changes to take effect. @@ -262,10 +262,20 @@ To disable it: 1. On the top bar, select **Menu >** **{admin}** **Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. -1. Uncheck **Enable forwarding of npm package requests to npmjs.org**. -1. Click **Save changes**. +1. Clear the checkbox **Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry**. +1. Select **Save changes**. + +### PyPI Forwarding **(PREMIUM SELF)** + +GitLab administrators can disable the forwarding of PyPI requests to [pypi.org](https://pypi.org/). + +To disable it: - +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand the **Package Registry** section. +1. Clear the checkbox **Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry**. +1. Select **Save changes**. ### Package file size limits diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index e637408328d..236b75797a2 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -13,27 +13,40 @@ You can customize some of the content in emails sent from your GitLab instance. The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#navigation-bar). -## Custom additional text **(PREMIUM SELF)** +## Include author name in email notification email body **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5031) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. +By default, GitLab overrides the email address in notification emails with the email address +of the issue, merge request, or comment author. Enable this setting to include the author's email +address in the body of the email instead. -The additional text appears at the bottom of any email and can be used for -legal/auditing/compliance reasons. +To include the author's email address in the email body: 1. On the top bar, select **Menu >** **{admin}** **Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. -1. Enter your text in the **Additional text** field. -1. Click **Save**. +1. Select the **Include author name in email notification email body** checkbox. +1. Select **Save changes**. + +## Enable multipart email **(PREMIUM SELF)** + +GitLab can send email in multipart format (HTML and plain text) or plain text only. + +To enable multipart email: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand **Email**. +1. Select **Enable multipart email**. +1. Select **Save changes**. -## Custom hostname for private commit emails +## Custom hostname for private commit emails **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22560) in GitLab 11.5. This configuration option sets the email hostname for [private commit emails](../../profile/index.md#use-an-automatically-generated-private-commit-email). By default it is set to `users.noreply.YOUR_CONFIGURED_HOSTNAME`. -In order to change this option: +To change the hostname used in private commit emails: 1. On the top bar, select **Menu >** **{admin}** **Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). @@ -42,10 +55,23 @@ In order to change this option: 1. Select **Save changes**. NOTE: -After the hostname gets configured, every private commit email using the previous hostname is not +After the hostname is configured, every private commit email using the previous hostname is not recognized by GitLab. This can directly conflict with certain [Push rules](../../../push_rules/push_rules.md) such as `Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. +## Custom additional text **(PREMIUM SELF)** + +You can add additional text at the bottom of any email that GitLab sends. This additional text +can be used for legal, auditing, or compliance reasons, for example. + +To add additional text to emails: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand **Email**. +1. Enter your text in the **Additional text** field. +1. Select **Save changes**. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index 31a626478ed..0e9d4e5d0c1 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -8,8 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60933) in GitLab Free 13.12. -Federated Learning of Conhorts (FLoC) is a feature that the Chrome browser has -rolled out, where users are categorized into different cohorts, so that +Federated Learning of Cohorts (FLoC) is a new feature of the Chrome browser. +It works by categorizing users into different cohorts, so that advertisers can use this data to uniquely target and track users. For more information, visit the [FLoC repository](https://github.com/WICG/floc). diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index d2f99a51ec3..01516430f4f 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Customize the Help and sign-in page messages +# Customize the Help and sign-in page messages **(FREE SELF)** In large organizations, it is useful to have information about who to contact or where -to go for help. You can customize and display this information on the GitLab `/help` page and on +to go for help. You can customize and display this information on the GitLab `/help` page and on the GitLab sign-in page. ## Add a help message to the Help page @@ -17,32 +17,39 @@ You can add a help message, which is shown at the top of the GitLab `/help` page <https://gitlab.com/help>): 1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**, then expand **Help page**. -1. Under **Additional text to show on the Help page**, fill in the information you wish to display on `/help`. -1. Select **Save changes**. You can now see the message on `/help`. +1. On the left sidebar, select **Settings > Preferences**. +1. Expand **Sign-in and Help page**. +1. In **Additional text to show on the Help page**, enter the information you want to display on `/help`. +1. Select **Save changes**. + +You can now see the message on `/help`. NOTE: By default, `/help` is visible to unauthenticated users. However, if the -[**Public** visibility level](visibility_and_access_controls.md#restricted-visibility-levels) +[**Public** visibility level](visibility_and_access_controls.md#restrict-visibility-levels) is restricted, `/help` is visible only to signed-in users. -## Add a help message to the sign-in page **(STARTER)** +## Add a help message to the sign-in page You can add a help message, which is shown on the GitLab sign-in page. The message appears in a new section titled **Need Help?**, located below the sign-in page message: 1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**, then expand **Help page**. -1. Under **Additional text to show on the sign-in page**, fill in the information you wish to +1. On the left sidebar, select **Settings > Preferences**. +1. Expand **Sign-in and Help page**. +1. In **Additional text to show on the sign-in page**, enter the information you want to display on the sign-in page. -1. Select **Save changes**. You can now see the message on the sign-in page. +1. Select **Save changes**. + +You can now see the message on the sign-in page. ## Hide marketing-related entries from the Help page GitLab marketing-related entries are occasionally shown on the Help page. To hide these entries: 1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**, then expand **Help page**. +1. On the left sidebar, select **Settings > Preferences**. +1. Expand **Sign-in and Help page**. 1. Select the **Hide marketing-related entries from the Help page** checkbox. 1. Select **Save changes**. @@ -54,10 +61,48 @@ You can specify a custom URL to which users are directed when they: - Select **See our website for help** on the Help page. 1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**, then expand **Help page**. -1. Enter the URL in the **Support page URL** field. +1. On the left sidebar, select **Settings > Preferences**. +1. Expand **Sign-in and Help page**. +1. In the **Support page URL** field, enter the URL. 1. Select **Save changes**. +## Redirect `/help` pages + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. +> - Enabled on GitLab.com and is ready for production use. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to +[enable the `:help_page_documentation_redirect` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. + +The `/help` URL of a GitLab instance displays a basic version of the documentation sourced from the +[`doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) of GitLab. `/help` links +are often used for contextual help. + +You can redirect these `/help` links to either: + +- The more navigable and searchable version published at [`docs.gitlab.com`](https://docs.gitlab.com). +- A destination that meets [necessary requirements](#destination-requirements). + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Preferences**. +1. Expand **Sign-in and Help page**. +1. In the **Documentation pages URL** field, enter the URL. +1. Select **Save changes**. + +### Destination requirements + +When redirecting `/help`, GitLab: + +- Redirects requests to the specified URL. +- Appends `ee` and the documentation path to the URL. +- Appends `.html` to the URL, and removes `.md` if necessary. + +For example, if the URL is set to `https://docs.gitlab.com`, requests for +`/help/user/admin_area/settings/help_page.md` redirect to: +`https://docs.gitlab.com/ee/user/admin_area/settings/help_page.html`. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/img/admin_package_registry_npm_package_requests_forward.png b/doc/user/admin_area/settings/img/admin_package_registry_npm_package_requests_forward.png Binary files differdeleted file mode 100644 index b6068f5d19b..00000000000 --- a/doc/user/admin_area/settings/img/admin_package_registry_npm_package_requests_forward.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/clone_panel_v12_4.png b/doc/user/admin_area/settings/img/clone_panel_v12_4.png Binary files differdeleted file mode 100644 index 427224f5b78..00000000000 --- a/doc/user/admin_area/settings/img/clone_panel_v12_4.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/domain_denylist.png b/doc/user/admin_area/settings/img/domain_denylist.png Binary files differdeleted file mode 100644 index a7e972b7c0a..00000000000 --- a/doc/user/admin_area/settings/img/domain_denylist.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/domain_denylist_v14_1.png b/doc/user/admin_area/settings/img/domain_denylist_v14_1.png Binary files differnew file mode 100644 index 00000000000..c988afd75f6 --- /dev/null +++ b/doc/user/admin_area/settings/img/domain_denylist_v14_1.png diff --git a/doc/user/admin_area/settings/img/enforce_terms.png b/doc/user/admin_area/settings/img/enforce_terms.png Binary files differdeleted file mode 100644 index de1a82275ab..00000000000 --- a/doc/user/admin_area/settings/img/enforce_terms.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v13_1.png b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v13_1.png Binary files differdeleted file mode 100644 index 9edc916c7fb..00000000000 --- a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v13_1.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png Binary files differnew file mode 100644 index 00000000000..63f4d5a4a1a --- /dev/null +++ b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png diff --git a/doc/user/admin_area/settings/img/respond_to_terms.png b/doc/user/admin_area/settings/img/respond_to_terms.png Binary files differdeleted file mode 100644 index f91480d1ce7..00000000000 --- a/doc/user/admin_area/settings/img/respond_to_terms.png +++ /dev/null diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index d21b6c36224..21ca1c573fe 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -51,10 +51,10 @@ To access the default page for Admin Area settings: | Option | Description | | ------ | ----------- | | [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 mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. | +| [Repository mirror](visibility_and_access_controls.md#enable-project-mirroring) | Configure repository mirroring. | | [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. | | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. | -| [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives, blobs, ...) from an external storage (for example, a CDN). | +| [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives and blobs) from an external storage (for example, a CDN). | ## Templates **(PREMIUM SELF)** @@ -84,8 +84,8 @@ To access the default page for Admin Area settings: | ------ | ----------- | | [Metrics - Prometheus](../../../administration/monitoring/prometheus/gitlab_metrics.md) | Enable and configure Prometheus metrics. | | [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integration-with-gitlab-ui) | Enable and configure Grafana. | -| [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-via-the-admin-area) | Enable access to the Performance Bar for a given group. | -| [Self monitoring](../../../administration/monitoring/gitlab_self_monitoring_project/index.md#creating-the-self-monitoring-project) | Enable or disable instance self monitoring. | +| [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-for-non-administrators) | Enable access to the Performance Bar for non-administrator users in a given group. | +| [Self monitoring](../../../administration/monitoring/gitlab_self_monitoring_project/index.md#create-the-self-monitoring-project) | Enable or disable instance self monitoring. | | [Usage statistics](usage_statistics.md) | Enable or disable version check and Service Ping. | | [Pseudonymizer data collection](../../../administration/pseudonymizer.md) **(ULTIMATE)** | Enable or disable the Pseudonymizer data collection. | @@ -115,7 +115,7 @@ To access the default page for Admin Area settings: | [What's new](../../../administration/whats-new.md) | Configure What's new drawer and content. | | [Help page](help_page.md) | Help page text and support page URL. | | [Pages](../../../administration/pages/index.md#custom-domain-verification) | Size and domain settings for static websites | -| [Real-time features](../../../administration/polling.md) | Change this value to influence how frequently the GitLab UI polls for updates. | +| [Polling interval multiplier](../../../administration/polling.md) | Configure how frequently the GitLab UI polls for updates. | | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | | Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 3140eecfa53..3b949b638d8 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- @@ -61,6 +61,18 @@ integration on all non-configured groups and projects by default. Resetting an instance-level default setting removes the integration from all projects that have the integration set to use default settings. +### View projects that override the default settings + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218252) in GitLab 14.2. + +You can view which projects in your instance use custom settings that [override the instance-level default settings](#use-custom-settings-for-a-group-or-project-integration) +for an integration. + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Integrations**. +1. Select an integration. +1. Select the **Projects using custom settings** tab. + ## Manage group-level default settings for a project integration > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6. diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index ef2b8ad80cd..bba61a7b913 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28129) in GitLab 12.10. -This setting allows you to rate limit the requests to the issue creation endpoint. +This setting allows you to rate limit the requests to the issue and epic creation endpoints. To can change its value: 1. On the top bar, select **Menu >** **{admin}** **Admin**. @@ -22,7 +22,9 @@ For example, if you set a limit of 300, requests using the [Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/raw/master/app/controllers/projects/issues_controller.rb) action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. - +When using [epics](../../group/epics/index.md), epic creation will share this rate limit with issues. + + This limit is: diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md index 193f39542cf..7615ad6f81d 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -17,7 +17,7 @@ To change the note creation rate limit: 1. On the left sidebar, select **Settings > Network**. 1. Expand **Notes Rate Limits**. 1. Under **Max requests per minute per user**, enter the new value. -1. Optional. Under **List of users to be excluded from the limit**, list users to be excluded fromt the limit. +1. Optional. Under **List of users to be excluded from the limit**, list users to be excluded from the limit. 1. Select **Save changes**. This limit is: diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 1098c7060f8..c774ae2eecc 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -31,7 +31,10 @@ To disable sign ups: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267568) in GitLab 13.6. -When this setting is enabled, any user visiting your GitLab domain and signing up for a new account must be explicitly [approved](../approving_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using their account. In GitLab 13.6 and later, this setting is enabled by default for new GitLab instances. It is only applicable if sign ups are enabled. +When this setting is enabled, any user visiting your GitLab domain and signing up for a new account +must be explicitly [approved](../moderate_users.md#approve-or-reject-a-user-sign-up) by an +administrator before they can start using their account. In GitLab 13.6 and later, this setting is +enabled by default for new GitLab instances. It is only applicable if sign ups are enabled. To require administrator approval for new sign ups: @@ -59,7 +62,7 @@ To enforce confirmation of the email address used for new sign ups: > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9. When the number of billable users reaches the user cap, any user who is added or requests access must be -[approved](../approving_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using +[approved](../moderate_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using their account. If an administrator [increases](#set-the-user-cap-number) or [removes](#remove-the-user-cap) the @@ -145,7 +148,7 @@ To create an email domain allowlist or denylist: domains ending in `.io`. Domains must be separated by a whitespace, semicolon, comma, or a new line. -  +  ### Enable or disable soft email confirmation diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 46e85ffc9c0..21805ef771f 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -5,59 +5,35 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Enforce accepting Terms of Service **(FREE SELF)** +# Terms of Service and Privacy Policy **(FREE SELF)** -An administrator can enforce acceptance of a terms of service and privacy policy. When this option is enabled, new and existing users must accept the terms. +An administrator can enforce acceptance of a terms of service and privacy policy. +When this option is enabled, new and existing users must accept the terms. -If configured, the Terms of Service page can be viewed via `https://your-instance.com/-/users/terms` at anytime. +When enabled, you can view the Terms of Service at the `-/users/terms` page on the instance, +for example `https://gitlab.example.com/-/users/terms`. -## Configuration +## Enforce a Terms of Service and Privacy Policy To enforce acceptance of a Terms of Service and Privacy Policy: -1. Log in to the GitLab instance as an admin user. 1. On the top bar, select **Menu >** **{admin}** **Admin**. 1. In the left sidebar, select **Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. -1. Check the **Require all users to accept Terms of Service and Privacy Policy when they access - GitLab.** checkbox. -1. Input the text of the **Terms of Service and Privacy Policy**. Markdown formatting can be used in this input box. +1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. +1. Input the text of the **Terms of Service and Privacy Policy**. You can use [Markdown](../../markdown.md) + in this text box. 1. Click **Save changes**. -1. When you are presented with the **Terms of Service** statement, click **Accept terms**. - - For each update to the terms, a new version is stored. When a user accepts or declines the terms, GitLab records which version they accepted or declined. -## New users - -When this feature is enabled, a checkbox is added to the sign-up form. +When enabled, it adds a mandatory checkbox to the sign up page for new users:  -This checkbox is required during sign up. - -Users can review the terms entered in the admin panel before -accepting. The page is opened in a new window so they can -continue their registration afterwards. - -## Accepting terms - -When this feature is enabled, the users that have not accepted the -terms of service are presented with a screen where they can either -accept or decline the terms. - - - -If the user accepts the terms, they are directed to where they -were going. After a sign-in or sign-up this is most likely the -dashboard. - -If the user was already logged in when the feature was turned on, -they are asked to accept the terms on their next interaction. - -If a user declines the terms, they are signed out. +Existing users must accept the terms on their next GitLab interaction. +If a logged-in user declines the terms, they are signed out. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index c12b720edd2..89c6be9608b 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -10,25 +10,24 @@ type: reference GitLab Inc. periodically collects information about your instance in order to perform various actions. -All statistics are opt-out. To enable or disable them: +All usage statistics are [opt-out](#enable-or-disable-usage-statistics). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Metrics and profiling**, and expand **Usage statistics**. -1. Enable or disable **Version check** and **Service ping**. -1. Select **Save changes**. +## Service Ping **(FREE SELF)** -## Network configuration +Service Ping is a process that collects and sends a weekly payload to GitLab Inc. +For more information, see the [Service Ping guide](../../../development/service_ping/index.md). -Allow network traffic from your GitLab instance to IP address `104.196.17.203:443`, to send -usage statistics to GitLab Inc. +### Instance-level analytics availability -If your GitLab instance is behind a proxy, set the appropriate [proxy configuration variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html). +When Service Ping is enabled, GitLab gathers data from other instances and +enables certain [instance-level analytics features](../analytics/index.md) +that are dependent on Service Ping. -## Version Check **(FREE SELF)** +## Version check **(FREE SELF)** If enabled, version check informs you if a new version is available and the -importance of it through a status. This is shown on the help page (i.e. `/help`) -for all signed in users, and on the admin pages. The statuses are: +importance of it through a status. The status displays on the help pages (`/help`) +for all signed-in users, and on the Admin Area pages. The statuses are: - Green: You are running the latest version of GitLab. - Orange: An updated version of GitLab is available. @@ -44,17 +43,12 @@ This information is used, among other things, to identify to which versions patches must be backported, making sure active GitLab instances remain secure. -If you disable version check, this information isn't collected. To enable or disable it: - -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Metrics and profiling**, and expand **Usage statistics**. -1. Enable or disable **Version check**. -1. Select **Save changes**. +If you [disable version check](#enable-or-disable-usage-statistics), this information isn't collected. ### Request flow example -The following example shows a basic request/response flow between the self-managed GitLab instance -and the GitLab Version Application: +The following example shows a basic request/response flow between a +self-managed GitLab instance and the GitLab Version Application: ```mermaid sequenceDiagram @@ -67,14 +61,22 @@ sequenceDiagram Version Application->>GitLab instance: Response (PNG/SVG) ``` -## Service Ping **(FREE SELF)** +## Configure your network + +To send usage statistics to GitLab Inc., you must allow network traffic from your +GitLab instance to the IP address `104.196.17.203:443`. + +If your GitLab instance is behind a proxy, set the appropriate +[proxy configuration variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html). -See [Service Ping guide](../../../development/service_ping/index.md). +## Enable or disable usage statistics -## Instance-level analytics availability +To enable or disable Service Ping and version check: -After Service Ping is enabled, GitLab gathers data from other instances and -enables certain [instance-level analytics features](../analytics/index.md) that are dependent on Service Ping. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Metrics and profiling**, and expand **Usage statistics**. +1. Select or clear the **Version check** and **Service ping** checkboxes. +1. Select **Save changes**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 4af33c133a4..c46aec76e57 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -5,9 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Visibility and access controls **(FREE SELF)** +# Control access and visibility **(FREE SELF)** -GitLab allows administrators to enforce specific controls. +GitLab enables users with the [Administrator role](../../permissions.md) to enforce +specific controls on branches, projects, snippets, groups, and more. To access the visibility and access control options: @@ -16,59 +17,95 @@ To access the visibility and access control options: 1. In the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. -## Default branch protection +## Protect default branches -This global option defines the branch protection that applies to every repository's -[default branch](../../project/repository/branches/default.md). -[Branch protection](../../project/protected_branches.md) specifies which roles can push -to branches and which roles can delete branches. In this case _Default_ refers to a -repository's [default branch](../../project/repository/branches/default.md). +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: -This setting applies only to each repositories' default branch. To protect other branches, you must configure branch protection in repository. For details, see [protected branches](../../project/protected_branches.md). +- Push to branches. +- Delete branches. -To change the default branch protection: +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). -1. Select the desired option. -1. Click **Save changes**. - -For more details, see [Protected branches](../../project/protected_branches.md). +To change the default branch protection for the entire instance: -To change this setting for a specific group, see [Default branch protection for groups](../../group/index.md#change-the-default-branch-protection-of-a-group) +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In 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, + force push, or delete the branch. + - **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 or delete the branch. + - **Fully protected** - Developers cannot push new commits, but maintainers can. + No one can force push or delete the branch. +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**. -### Disable group owners from updating default branch protection **(PREMIUM SELF)** +### Prevent overrides of default branch protection **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211944) in GitLab 13.0. -By default, group owners are allowed to override the branch protection set at the global level. - -In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege of group owners. - -To do this: +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. Uncheck the **Allow owners to manage default branch protection per group** checkbox. +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In 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. -## Default project creation protection +## Define which roles can create projects -Project creation protection specifies which roles can create projects. +Instance-level protections for project creation define which roles can +[add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group)] +on the instance. To alter which roles have permission to create projects: -To change the default project creation protection: +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. For **Default project creation protection**, select the desired roles: + - No one. + - Maintainers. + - Developers and Maintainers. +1. Select **Save changes**. -1. Select the desired option. -1. Click **Save changes**. +## Restrict project deletion to Administrators **(PREMIUM SELF)** + +Anyone with the **Owner** role, either at the project or group level, can +delete a project. To allow only users with the Administrator role to delete projects: -For more details, see [Specify who can add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group). +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Scroll to **Default project deletion protection**, and select **Only admins can delete project**. +1. Select **Save changes**. -## Default project deletion protection **(PREMIUM SELF)** +## Default delayed project deletion **(PREMIUM SELF)** -By default, a project can be deleted by anyone with the **Owner** role, either at the project or -group level. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. -To ensure only Administrator users can delete projects: +Projects in a group (but not a personal namespace) can be deleted after a delayed period, by +[configuring in Group Settings](../../group/index.md#enable-delayed-project-removal). -1. Check the **Default project deletion protection** checkbox. +To enable delayed project deletion by default in new groups: + +1. Check the **Default delayed project deletion** checkbox. 1. Click **Save changes**. ## Default deletion delay **(PREMIUM SELF)** @@ -92,7 +129,7 @@ To change this period: 1. Select the desired option. 1. Click **Save changes**. -### Override default deletion delayed period +### Override defaults and delete immediately Alternatively, projects that are marked for removal can be deleted immediately. To do so: @@ -100,107 +137,132 @@ Alternatively, projects that are marked for removal can be deleted immediately. 1. Delete the project as described in the [Administering Projects page](../../admin_area/#administering-projects). -## Default project visibility - -To set the default visibility levels for new projects: +## Configure project visibility defaults -1. Select the desired default project visibility. -1. Click **Save changes**. +To set the default [visibility levels for new projects](../../../public_access/public_access.md): -For more details on project visibility, see -[Project visibility](../../../public_access/public_access.md). +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Select the desired default project visibility: + - **Private** - Project access must be granted explicitly to each user. If this + project is part of a group, access will be granted to members of the group. + - **Internal** - The project can be accessed by any logged in user except external users. + - **Public** - The project can be accessed without any authentication. +1. Select **Save changes**. -## Default snippet visibility +## Configure snippet visibility defaults -To set the default visibility levels for new snippets: +To set the default visibility levels for new [snippets](../../snippets.md): +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. 1. Select the desired default snippet visibility. -1. Click **Save changes**. +1. Select **Save changes**. -For more details on snippet visibility, see +For more details on snippet visibility, read [Project visibility](../../../public_access/public_access.md). -## Default group visibility +## Configure group visibility defaults To set the default visibility levels for new groups: -1. Select the desired default group visibility. -1. Click **Save changes**. +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Select the desired default group visibility: + - **Private** - The group and its projects can only be viewed by members. + - **Internal** - The group and any internal projects can be viewed by any logged in user except external users. + - **Public** - The group and any public projects can be viewed without any authentication. +1. Select **Save changes**. For more details on group visibility, see [Group visibility](../../group/index.md#group-visibility). -## Restricted visibility levels +## Restrict visibility levels -To set the restricted visibility levels for projects, snippets, and selected pages: +To restrict visibility levels for projects, snippets, and selected pages: -1. Select the desired visibility levels to restrict. +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. 1. Select **Save changes**. For more details on project visibility, see [Project visibility](../../../public_access/public_access.md). -## Import sources - -To specify from which hosting sites users can [import their projects](../../project/import/index.md): - -1. Check the checkbox beside the name of each hosting site. -1. Click **Save changes**. +## Configure allowed import sources -## Project export +You can specify from which hosting sites users can [import their projects](../../project/import/index.md): -To enable project export: +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Select each of **Import sources** to allow. +1. Select **Save changes**. -1. Check the **Project export enabled** checkbox. -1. Click **Save changes**. +## Enable project export -For more details, see [Exporting a project and its data](../../../user/project/settings/import_export.md#exporting-a-project-and-its-data). +To enable the export of +[projects and their data](../../../user/project/settings/import_export.md#export-a-project-and-its-data): -## Enabled Git access protocols +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Select **Project export enabled**. +1. Select **Save changes**. -With GitLab access restrictions, you can select with which protocols users can communicate with -GitLab. +## Configure enabled Git access protocols -Disabling an access protocol does not block access to the server itself by using those ports. The ports -used for the protocol, SSH or HTTP(S), are still accessible. The GitLab restrictions apply at the -application level. +With GitLab access restrictions, you can select the protocols users can use to +communicate with GitLab. Disabling an access protocol does not block port access to the +server itself. The ports used for the protocol, SSH or HTTP(S), are still accessible. +The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: -1. Select the desired Git access protocols from the dropdown: +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Select the desired Git access protocols: - Both SSH and HTTP(S) - Only SSH - Only HTTP(S) -1. Click **Save changes**. +1. Select **Save changes**. When both SSH and HTTP(S) are enabled, users can choose either protocol. - -When only one protocol is enabled: +If only one protocol is enabled: - The project page shows only the allowed protocol's URL, with no option to change it. -- A tooltip is shown when you hover over the URL's protocol, if an action - on the user's part is required. For example, adding an SSH key or setting a password. +- GitLab shows a tooltip when you hover over the URL's protocol, if user action + (such as adding a SSH key or setting a password) is required: - +  -On top of these UI restrictions, GitLab denies all Git actions on the protocol -not selected. +GitLab only allows Git actions for the protocols you select. WARNING: GitLab versions [10.7 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021), allow the HTTP(S) protocol for Git clone or fetch requests done by GitLab Runner -from CI/CD jobs, even if **Only SSH** was selected. +from CI/CD jobs, even if you select **Only SSH**. -## Custom Git clone URL for HTTP(S) +## Customize Git clone URL for HTTP(S) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18422) in GitLab 12.4. You can customize project Git clone URLs for HTTP(S), which affects the clone panel: - - For example, if: - Your GitLab instance is at `https://example.com`, then project clone URLs are like @@ -219,7 +281,7 @@ NOTE: SSH clone URLs can be customized in `gitlab.rb` by setting `gitlab_rails['gitlab_ssh_host']` and other related settings. -## RSA, DSA, ECDSA, ED25519 SSH keys +## Configure defaults for RSA, DSA, ECDSA, ED25519 SSH keys These options specify the permitted types and lengths for SSH keys. @@ -230,7 +292,7 @@ To specify a restriction for each key type: For more details, see [SSH key restrictions](../../../security/ssh_keys_restrictions.md). -## Allow mirrors to be set up for projects +## Enable project mirroring This option is enabled by default. By disabling it, both [pull and push mirroring](../../project/repository/repository_mirroring.md) no longer diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 8c67163c4b0..7cb5db4379a 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -11,25 +11,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w When we describe GitLab analytics, we use the following terms: - **Cycle time:** The duration of only the execution work alone. Often displayed in combination with "lead time," which is longer. GitLab measures cycle time from issue first merge request creation to issue close. This approach underestimates lead time because merge request creation is always later than commit time. GitLab displays cycle time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). -- **Deploys:** The total number of successful deployments to production in the given time frame (across all applicable projects). GitLab displays deploys in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). +- **Deploys:** The total number of successful deployments to production in the given time frame (across all applicable projects). GitLab displays deploys in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). - **DORA (DevOps Research and Assessment)** ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): - **Speed/Velocity** - - **Deployment frequency:** The average number of successful deployments to production per period. + - **Deployment frequency:** The relative frequency of successful deployments to production + (hourly, daily, weekly, monthly, or yearly). This effectively measures how often you are delivering value to end users. A higher deployment frequency means you are able to get feedback and iterate more quickly in delivering improvements and features faster. GitLab measures this as the number of deployments to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in the given time period. - GitLab displays deployment frequency in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). + GitLab displays deployment frequency in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). - **Lead Time for Changes:** The time it takes for a commit to get into production. (1) GitLab measures this as the median duration between merge request merge and deployment to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments) for all MRs deployed in the given time period. This measure under-estimates lead time because merge time is always later than commit time. The - [standard definition](https://github.com/GoogleCloudPlatform/fourkeys/blob/main/METRICS.md#lead-time-for-changes) uses median commit time. We plan to start - [measuring from "issue first commit"](https://gitlab.com/gitlab-org/gitlab/-/issues/328459) - as a better proxy, although still imperfect. + [standard definition](https://github.com/GoogleCloudPlatform/fourkeys/blob/main/METRICS.md#lead-time-for-changes) uses median commit time. + [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/328459) to start + measuring from "issue first commit" as a better proxy, although still imperfect. - **Stability** - **Change Failure Rate:** The percentage of deployments causing a failure in production. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 4ad3a03a5b0..9a1aed9c39f 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -124,9 +124,9 @@ 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) -- **Test**: 5 mins +- **Test**: 5 minutes - **Review**: 5 hrs (14:00 to 19:00) -- **Staging**: 30 mins (19:00 to 19:30) +- **Staging**: 30 minutes (19:00 to 19:30) More information: diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_configuration_snippet_v13.10.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_configuration_snippet_v13.10.png Binary files differdeleted file mode 100644 index 80c550a3ae7..00000000000 --- a/doc/user/application_security/api_fuzzing/img/api_fuzzing_configuration_snippet_v13.10.png +++ /dev/null diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index e35415003c7..7ed36572be4 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -38,7 +38,7 @@ or other scanners) during a scan could cause inaccurate results. You can run a Web API fuzzing scan using the following methods: -- [OpenAPI Specification](#openapi-specification) - version 2.0 or 3.0 +- [OpenAPI Specification](#openapi-specification) - version 2, and 3. - [HTTP Archive](#http-archive-har) (HAR) - [Postman Collection](#postman-collection) - version 2.0 or 2.1 @@ -112,6 +112,8 @@ To generate an API Fuzzing configuration snippet: ### OpenAPI Specification +> Support for OpenAPI Specification v3.1 was +> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.2. > Support for OpenAPI Specification using YAML format was > [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. > Support for OpenAPI Specification v3.0 was diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 3cc88a40b6f..664fcd9b72f 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -11,9 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. **(ULTIMATE)** > - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. **(ULTIMATE)** > - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.2. The Security Configuration page displays what security scans are available, links to documentation and also simple enablement tools for the current project. @@ -22,35 +20,37 @@ then in the left sidebar go to **Security & Compliance > Configuration**. For each security control the page displays: -- **Security Control:** Name, description, and a documentation link. -- **Manage:** A management option or a documentation link. - -## UI redesign - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.0 for GitLab Free and Premium, behind a feature flag, disabled by default. -> - Enabled on GitLab.com for Free & Premium. -> - Recommended for production use. -> - It can be enabled or disabled for a single project. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ui-redesign). **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333109) in 14.1 for GitLab Ultimate, behind a feature flag, disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - It can be enabled or disabled for a single project. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ui-redesign-for-ultimate). **(ULTIMATE SELF)** +- Its name, description and a documentation link. +- Whether or not it is available. +- A configuration button or a link to its configuration guide. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +## Security testing -The Security Configuration page has been redesigned in GitLab Free and Premium. -The same functionality exists as before, but presented in a more extensible -way. +You can configure the following security controls: -For each security control the page displays: +- Auto DevOps + - Click **Enable Auto DevOps** on the alert to enable it for the current project. For more details, see [Auto DevOps](../../../topics/autodevops/index.md). +- SAST + - Click **Enable SAST** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +- DAST **(ULTIMATE)** + - Click **Enable DAST** to use DAST for the current Project. To manage the available DAST profiles used for on-demand scans Click **Manage Scans**. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). +- Dependency Scanning **(ULTIMATE)** + - Select **Configure via 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). -- Its name, description and a documentation link. -- Whether or not it is available. -- A configuration button or a link to its configuration guide. +- Container Scanning **(ULTIMATE)** + - Can be configured via `.gitlab-ci.yml`. For more details, see [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). +- Cluster Image Scanning **(ULTIMATE)** + - Can be configured via `.gitlab-ci.yml`. For more details, see [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). +- Secret Detection + - Select **Configure via Merge Request** to create a merge request with the changes required to + enable Secret Detection. For more details, see [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). +- API Fuzzing **(ULTIMATE)** + - Click **Enable API Fuzzing** to use API Fuzzing for the current Project. For more details, see [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). +- Coverage Fuzzing **(ULTIMATE)** + - Can be configured via `.gitlab-ci.yml`. For more details, see [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). + ## Status **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. @@ -63,71 +63,11 @@ _enabled_. If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), all security features are configured by default. -For SAST, click **View history** to see the `.gitlab-ci.yml` file's history. +Click **View history** to see the `.gitlab-ci.yml` file's history. -## Manage **(ULTIMATE)** +## Compliance **(ULTIMATE)** You can configure the following security controls: -- Auto DevOps - - Click **Enable Auto DevOps** to enable it for the current project. For more details, see [Auto DevOps](../../../topics/autodevops/index.md). -- SAST - - Click either **Enable** or **Configure** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). -- DAST Profiles - - Click **Manage** to manage the available DAST profiles used for on-demand scans. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). -- Secret Detection - - Select **Configure via Merge Request** to create a merge request with the changes required to - enable Secret Detection. For more details, see [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). -- Dependency Scanning - - Select **Configure via 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). - -## Enable or disable UI redesign **(FREE SELF)** - -The Security Configuration redesign is under development, but 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 -# For the instance -Feature.enable(:security_configuration_redesign) -# For a single project -Feature.enable(:security_configuration_redesign, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:security_configuration_redesign) -# For a single project -Feature.disable(:security_configuration_redesign, Project.find(<project id>)) -``` - -## Enable or disable UI redesign for Ultimate **(ULTIMATE SELF)** - -The Security Configuration redesign is under development, and is not ready for -production use. It is deployed behind a feature flag that is **disabled by -default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it. - -To enable it: - -```ruby -# For the instance -Feature.enable(:security_configuration_redesign_ee) -# For a single project -Feature.enable(:security_configuration_redesign_ee, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:security_configuration_redesign_ee) -# For a single project -Feature.disable(:security_configuration_redesign_ee, Project.find(<project id>)) -``` +- License Compliance **(ULTIMATE)** + - Can be configured via `.gitlab-ci.yml`. For more details, see [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 90e1e4b025c..5791351a067 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -160,8 +160,8 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Trivy. The registry must listen on port `80/tcp`. | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | | `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | -| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | All | -| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | All | +| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$DOCKER_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). | All | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$DOCKER_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). | All | | `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | All | @@ -170,7 +170,7 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u Support depends on the scanner: - [Grype](https://github.com/anchore/grype#grype) -- [Trivy](https://aquasecurity.github.io/trivy/latest/vuln-detection/os/) (Default). +- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/os/) (Default). #### UBI-based images diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index aaf701c91dc..1489b250e4b 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -1,11 +1,11 @@ --- type: tutorial stage: Secure -group: Vulnerability Research +group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CVE ID Requests **(ULTIMATE SAAS)** +# CVE ID Requests **(FREE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. @@ -28,7 +28,7 @@ If the following conditions are met, a **Request CVE ID** button appears in your - The project is hosted in GitLab.com. - The project is public. - You are a maintainer of the project. -- The issue is confidential. +- The issue is [confidential](../project/issues/confidential_issues.md). ## Submitting a CVE ID Request @@ -37,7 +37,7 @@ the [GitLab CVE project](https://gitlab.com/gitlab-org/cves).  -Creating the confidential issue starts the CVE request process. +Creating the [confidential issue](../project/issues/confidential_issues.md) starts the CVE request process.  diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 1288db21880..e8fbc17327c 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -48,18 +48,26 @@ dast: The browser-based crawler can be configured using CI/CD variables. -| CI/CD variable | Type | Example | Description | -|--------------------------------------| ----------------| --------------------------------- | ------------| -| `DAST_WEBSITE` | URL | `http://www.site.com` | The URL of the website to scan. | -| `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | -| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | -| `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | -| `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | -| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | -| `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | -| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | -| `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | -| `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | +| CI/CD variable | Type | Example | Description | +|----------------------------------------------| ----------------| --------------------------------- | ------------| +| `DAST_WEBSITE` | URL | `http://www.site.com` | The URL of the website to scan. | +| `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | +| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | +| `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | +| `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | +| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | +| `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | +| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | +| `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | +| `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | +| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another | +| `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action | +| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis | +| `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes | +| `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action | +| `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or navigations | +| `DAST_BROWSER_EXTRACT_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `5s` | The maximum amount of time to allow the browser to extract newly found elements or navigations | +| `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis | The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, `DAST_AUTH_URL`, `DAST_USERNAME`, `DAST_PASSWORD`, `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, `DAST_SUBMIT_FIELD`, `DAST_EXCLUDE_URLS`, `DAST_AUTH_VERIFICATION_URL`, `DAST_BROWSER_AUTH_VERIFICATION_SELECTOR`, `DAST_BROWSER_AUTH_VERIFICATION_LOGIN_FORM`, `DAST_BROWSER_AUTH_REPORT`, @@ -86,6 +94,46 @@ You can manage the trade-off between coverage and scan time with the following m - Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. - Vertically scaling the runner and using a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. +## Timeouts + +Due to poor network conditions or heavy application load, the default timeouts may not be applicable to your application. + +Browser-based scans offer the ability to adjust various timeouts to ensure it continues smoothly as it transitions from one page to the next. These values are configured using a [Duration string](https://golang.org/pkg/time/#ParseDuration) which allow you to configure durations with a prefix: `m` for minutes, `s` for seconds, and `ms` for milliseconds. + +Navigations, or the act of loading a new page, usually require the most amount of time as they are +loading multiple new resources such as JavaScript or CSS files. Depending on the size of these resources, or the speed at which they are returned, the default `DAST_BROWSER_NAVIGATION_TIMEOUT` may not be sufficient. + +Stability timeouts, such as those configurable with `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT`, and `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` can also be configured. Stability timeouts determine when browser-based scans consider +a page fully loaded. Browser-based scans consider a page loaded when: + +1. The [DOMContentLoaded](https://developer.mozilla.org/en-US/docs/Web/API/Window/DOMContentLoaded_event) event has fired. +1. There are no open or outstanding requests that are deemed important, such as JavaScript and CSS. Media files are usually deemed unimportant. +1. Depending on whether the browser executed a navigation, was forcibly transitioned, or action: + + - There are no new Document Object Model (DOM) modification events after the `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT` or `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` durations + +After these events have occurred, browser-based scans consider the page loaded and ready and attempt the next action. + +If your application experiences latency or returns many navigation failures, consider adjusting the timeout values such in this example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://my.site.com" + DAST_BROWSER_NAVIGATION_TIMEOUT: "25s" + DAST_BROWSER_ACTION_TIMEOUT: "10s" + DAST_BROWSER_STABILITY_TIMEOUT: "15s" + DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT: "15s" + DAST_BROWSER_ACTION_TIMEOUT: "10s" + DAST_BROWSER_ACTION_STABILITY_TIMEOUT: "3s" +``` + +NOTE: +Adjusting these values may impact scan time as they adjust how long each browser waits for various activities to complete. + ## Debugging scans using logging Logging can be used to help you troubleshoot a scan. diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 48b48392e65..725fab85789 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -11,6 +11,32 @@ The following troubleshooting scenarios have been collected from customer suppor experience a problem not addressed here, or the information here does not fix your problem, create a support ticket. For more details, see the [GitLab Support](https://about.gitlab.com/support/) page. +## Debugging DAST jobs + +A DAST job has two executing processes: + +- The ZAP server. +- A series of scripts that start, control and stop the ZAP server. + +Enable the `DAST_DEBUG` CI/CD variable to debug scripts. This can help when troubleshooting the job, +and outputs statements indicating what percentage of the scan is complete. +For details on using variables, see [Overriding the DAST template](index.md#customizing-the-dast-settings). + +Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` variable. +The following table outlines examples of values that can be set and the effect that they have on the output that is logged. +Multiple values can be specified, separated by semicolons. + +For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG`. + +| Log configuration value | Effect | +|-------------------------------------------------- | ----------------------------------------------------------------- | +| `log4j.rootLogger=DEBUG` | Enable all debug logging statements. | +| `log4j.logger.org.apache.commons.httpclient=DEBUG` | Log every HTTP request and response made by the ZAP server. | +| `log4j.logger.org.zaproxy.zap.spider.SpiderController=DEBUG` | Log URLs found during the spider scan of the target. | +| `log4j.logger.com.crawljax=DEBUG` | Enable Ajax Crawler debug logging statements. | +| `log4j.logger.org.parosproxy.paros=DEBUG` | Enable ZAP server proxy debug logging statements. | +| `log4j.logger.org.zaproxy.zap=DEBUG` | Enable debug logging statements of the general ZAP server code. | + ## Running out of memory By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25% diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 4b10f03fec3..7455915761c 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -121,6 +121,34 @@ services: # use services to link the container to the dast job alias: yourapp ``` +### DAST job order + +When using the `DAST.gitlab-ci.yml` template, the `dast` stage is run last as shown in +the example below. To ensure DAST scans the latest code, deploy your application +in a stage before the `dast` stage. + +```yaml + stages: + - build + - test + - deploy + - dast +``` + +Take care if your pipeline is configured to deploy to the same web server in each run. Running a +pipeline while another is still running could result in one pipeline overwriting the code from +another pipeline. The site to be scanned should be excluded from changes for the duration of a DAST +scan. The only changes to the site should be from the DAST scanner. + +Changes to the site during a scan from any of the following could lead to inaccurate results: + +- Users. +- Scheduled tasks. +- Database changes. +- Code changes. +- Other pipelines. +- Other scanners. + ## DAST run options You can use DAST to examine your web application: @@ -147,28 +175,6 @@ To enable DAST to run automatically, either: `.gitlab-ci.yml` file. - [Configure DAST using the UI](#configure-dast-using-the-ui). -### DAST job order - -When using the `DAST.gitlab-ci.yml` template, the `dast` stage is run last as shown in -the example below. To ensure DAST scans the latest code, deploy your application -in a stage before the `dast` stage. - -```yaml - stages: - - build - - test - - deploy - - dast -``` - -Be aware that if your pipeline is configured to deploy to the same webserver in -each run, running a pipeline while another is still running could cause a race condition -where one pipeline overwrites the code from another pipeline. The site to be scanned -should be excluded from changes for the duration of a DAST scan. -The only changes to the site should be from the DAST scanner. Be aware that any -changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to -the site during a scan could lead to inaccurate results. - #### Include the DAST template > This template was [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62597) to DAST_VERSION: 2 in GitLab 14.0. @@ -298,7 +304,7 @@ For more details, including setup instructions, see [DAST browser-based crawler] ### Full scan -DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which +DAST can be configured to perform [ZAP Full Scan](https://www.zaproxy.org/docs/docker/full-scan/), which includes both passive and active scanning against the same target website: ```yaml @@ -583,30 +589,6 @@ by the application as correctly authenticated. Authentication supports single form logins, multi-step login forms, and authenticating to URLs outside of the configured target URL. -Variables that are related to authenticated scans are: - -```yaml -include: - - template: DAST.gitlab-ci.yml - -dast: - variables: - DAST_WEBSITE: "https://example.com" - DAST_AUTH_URL: "https://login.example.com/" - DAST_BROWSER_PATH_TO_LOGIN_FORM: "css:.navigation-menu,css:.login-menu-item" # optional list of selectors that should be clicked on prior to attempting to input username/password into the sign-in HTML form - DAST_USERNAME: "admin" - DAST_PASSWORD: "P@55w0rd!" - DAST_USERNAME_FIELD: "name:username" # a selector describing the element containing the username field at the sign-in HTML form - DAST_PASSWORD_FIELD: "id:password" # a selector describing the element containing the password field at the sign-in HTML form - DAST_FIRST_SUBMIT_FIELD: "css:button[type='user-submit']" # optional, the selector of the element that when clicked will submit the username form of a multi-page login process - DAST_SUBMIT_FIELD: "css:button[type='submit']" # the selector of the element that when clicked will submit the login form or the password form of a multi-page login process - DAST_EXCLUDE_URLS: "http://example.com/sign-out" # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between - DAST_AUTH_VERIFICATION_URL: "http://example.com/loggedin_page" # optional, used to verify authentication is successful by expecting this URL once the login form has been submitted - DAST_AUTH_VERIFICATION_SELECTOR: "css:.user-profile" # optional, used to verify authentication is successful by expecting a selector to be present on the page once the login form has been submitted - DAST_AUTH_VERIFICATION_LOGIN_FORM: "true" # optional, used to verify authentication is successful by ensuring there are no login forms on the page once the login form has been submitted - DAST_AUTH_REPORT: "true" # optionally output an authentication debug report -``` - WARNING: **NEVER** run an authenticated scan against a production server. When an authenticated scan is run, it may perform *any* function that the authenticated user can. This @@ -762,55 +744,56 @@ dast: ### Available CI/CD variables -You can use CI/CD variables to customize DAST. - -| CI/CD variable | Type | Description | -|:------------------------------------------------|:--------------|:-------------------------------| -| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. | -| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | -| `DAST_AUTH_URL` <sup>1</sup> | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | -| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1</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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | -| `DAST_USERNAME` <sup>1</sup> | string | The username to authenticate to in the website. | -| `DAST_PASSWORD` <sup>1</sup> | string | The password to authenticate to in the website. | -| `DAST_USERNAME_FIELD` <sup>1</sup> | string | The name of username field at the sign-in HTML form. | -| `DAST_PASSWORD_FIELD` <sup>1</sup> | string | The name of password field at the sign-in HTML form. | -| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_EXCLUDE_URLS` <sup>1</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. | -| `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | -| `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_API_HOST_OVERRIDE` <sup>1</sup> | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://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_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | -| `DAST_REQUEST_HEADERS` <sup>1</sup> | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_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_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | -| `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | -| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | -| `DAST_AUTH_EXCLUDE_URLS` | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_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. | -| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | -| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | -| `DAST_AUTH_REPORT` | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | -| `DAST_AUTH_VERIFICATION_URL` <sup>1</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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | -| `DAST_AUTH_VERIFICATION_SELECTOR` | 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_LOGIN_FORM` | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | -| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | +These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. + +| CI/CD variable | Type | Description | +|:-------------------------------------------------|:--------------|:------------------------------| +| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | +| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | +| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_AUTH_REPORT` <sup>2</sup> | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | +| `DAST_AUTH_EXCLUDE_URLS` <sup>2</sup> | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_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. | +| `DAST_AUTH_URL` <sup>1,2</sup> | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. Example: `https://login.example.com`. | +| `DAST_AUTH_VERIFICATION_LOGIN_FORM` <sup>2</sup> | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | +| `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_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`. | +| `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | +| `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | +| `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_REQUEST_HEADERS` <sup>1</sup> | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | +| `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | +| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_USERNAME` <sup>1,2</sup> | string | The username to authenticate to in the website. Example: `admin` | +| `DAST_USERNAME_FIELD` <sup>1,2</sup> | string | The selector of username field at the sign-in HTML form. Example: `name:username` | +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | +| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | 1. Available to an on-demand DAST scan. +1. Used for authentication. #### Selectors @@ -838,8 +821,8 @@ Chrome DevTools element selector tool is an effective way to find a selector.  1. Once highlighted, you can see the element's details, including attributes that would make a good candidate for a selector. -In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting -`DAST_USERNAME_FIELD: "id:user_login"`. +In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting +`DAST_USERNAME_FIELD: "id:user_login"`. ##### Choose the right selector @@ -926,89 +909,6 @@ variables: The DAST job does not require the project's repository to be present when running, so by default [`GIT_STRATEGY`](../../../ci/runners/configure_runners.md#git-strategy) is set to `none`. -### Debugging DAST jobs - -A DAST job has two executing processes: - -- The ZAP server. -- A series of scripts that start, control and stop the ZAP server. - -Debug mode of the scripts can be enabled by using the `DAST_DEBUG` CI/CD variable. This can help when troubleshooting the job, -and outputs statements indicating what percentage of the scan is complete. -For details on using variables, see [Overriding the DAST template](#customizing-the-dast-settings). - -Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` variable. -The following table outlines examples of values that can be set and the effect that they have on the output that is logged. -Multiple values can be specified, separated by semicolons. - -For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG`. - -| Log configuration value | Effect | -|-------------------------------------------------- | ----------------------------------------------------------------- | -| `log4j.rootLogger=DEBUG` | Enable all debug logging statements. | -| `log4j.logger.org.apache.commons.httpclient=DEBUG` | Log every HTTP request and response made by the ZAP server. | -| `log4j.logger.org.zaproxy.zap.spider.SpiderController=DEBUG` | Log URLs found during the spider scan of the target. | -| `log4j.logger.com.crawljax=DEBUG` | Enable Ajax Crawler debug logging statements. | -| `log4j.logger.org.parosproxy.paros=DEBUG` | Enable ZAP server proxy debug logging statements. | -| `log4j.logger.org.zaproxy.zap=DEBUG` | Enable debug logging statements of the general ZAP server code. | - -## Running DAST in an offline environment - -For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for the DAST job to -successfully run. For more information, see [Offline environments](../offline_deployments/index.md). - -### Requirements for offline DAST support - -To use DAST in an offline environment, you need: - -- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites). -- Docker Container Registry with a locally available copy of the DAST - [container image](https://gitlab.com/security-products/dast), found in the - [DAST container registry](https://gitlab.com/security-products/dast/container_registry). - -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) -in an offline environment if you prefer using only locally available Docker images. However, we -recommend keeping the pull policy setting to `always` if not in an offline environment, as this -enables the use of updated scanners in your CI/CD pipelines. - -### Make GitLab DAST analyzer images available inside your Docker registry - -For DAST, import the following default DAST analyzer image from `registry.gitlab.com` to your [local Docker container registry](../../packages/container_registry/index.md): - -- `registry.gitlab.com/security-products/dast:latest` - -The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Please consult your IT staff to find an accepted and approved -process by which external resources can be imported or temporarily accessed. -These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) -with new definitions, and you may be able to make occasional updates on your own. - -For details on saving and transporting Docker images as a file, see Docker's documentation on -[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), -[`docker load`](https://docs.docker.com/engine/reference/commandline/load/), -[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and -[`docker import`](https://docs.docker.com/engine/reference/commandline/import/). - -### Set DAST CI/CD job variables to use local DAST analyzers - -Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to -the DAST Docker image hosted on your local Docker container registry: - -```yaml -include: - - template: DAST.gitlab-ci.yml -dast: - image: registry.example.com/namespace/dast:latest -``` - -The DAST job should now use local copies of the DAST analyzers to scan your code and generate -security reports without requiring internet access. - -Alternatively, you can use the CI/CD variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. - ## On-demand scans > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. @@ -1148,7 +1048,12 @@ When an API site type is selected, a [host override](#host-override) is used to #### Site profile validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. +> - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. +> - Meta tag validation [enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2 and is ready for production use. +> - Meta tag validation [enabled with `dast_meta_tag_validation flag` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/337711) for self-managed GitLab in GitLab 14.2 and is ready for production use. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the `dast_meta_tag_validation` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. Site profile validation reduces the risk of running an active scan against the wrong website. A site must be validated before an active scan can run against it. The site validation methods are as @@ -1160,8 +1065,14 @@ follows: - _Header validation_ requires the header `Gitlab-On-Demand-DAST` be added to the target site, with a value unique to the project. The validation process checks that the header is present, and checks its value. +- _Meta tag validation_ requires the meta tag named `gitlab-dast-validation` be added to the target site, + with a value unique to the project. Make sure it's added to the `<head>` section of the page. The validation process checks that the meta tag is present, and + checks its value. + +All these methods are equivalent in functionality. Use whichever is feasible. -Both methods are equivalent in functionality. Use whichever is feasible. +In [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/324990), site profile +validation happens in a CI job using the [GitLab Runner](../../../ci/runners/index.md). #### Create a site profile @@ -1210,8 +1121,9 @@ Prerequisites: To validate a site profile: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. In the **DAST Profiles** row select **Manage**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage scans**. 1. Select the **Site Profiles** tab. 1. In the profile's row select **Validate** or **Retry validation**. 1. Select the validation method. @@ -1225,6 +1137,11 @@ To validate a site profile: 1. Edit the header of the site to validate, and paste the clipboard content. 1. Select the input field in **Step 3** and enter the location of the header. 1. Select **Validate**. + 1. For **Meta tag validation**: + 1. Select the clipboard icon in **Step 2**. + 1. Edit the content of the site to validate, and paste the clipboard content. + 1. Select the input field in **Step 3** and enter the location of the meta tag. + 1. Select **Validate**. The site is validated and an active scan can run against it. diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md new file mode 100644 index 00000000000..39747a5cbe5 --- /dev/null +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -0,0 +1,63 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, howto +--- + +# Run DAST in an offline environment + +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access +to external resources through the internet, some adjustments are required for the DAST job to +successfully run. For more information, see [Offline environments](../offline_deployments/index.md). + +## Requirements for offline DAST support + +To use DAST in an offline environment, you need: + +- GitLab Runner with the [`docker` or `kubernetes` executor](index.md#prerequisites). +- Docker Container Registry with a locally available copy of the DAST + [container image](https://gitlab.com/security-products/dast), found in the + [DAST container registry](https://gitlab.com/security-products/dast/container_registry). + +Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +in an offline environment if you prefer using only locally available Docker images. However, we +recommend keeping the pull policy setting to `always` if not in an offline environment, as this +enables the use of updated scanners in your CI/CD pipelines. + +## Make GitLab DAST analyzer images available inside your Docker registry + +For DAST, import the following default DAST analyzer image from `registry.gitlab.com` to your [local Docker container registry](../../packages/container_registry/index.md): + +- `registry.gitlab.com/security-products/dast:latest` + +The process for importing Docker images into a local offline Docker registry depends on +**your network security policy**. Please consult your IT staff to find an accepted and approved +process by which external resources can be imported or temporarily accessed. +These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +with new definitions, and you may be able to make occasional updates on your own. + +For details on saving and transporting Docker images as a file, see Docker's documentation on +[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), +[`docker load`](https://docs.docker.com/engine/reference/commandline/load/), +[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and +[`docker import`](https://docs.docker.com/engine/reference/commandline/import/). + +## Set DAST CI/CD job variables to use local DAST analyzers + +Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to +the DAST Docker image hosted on your local Docker container registry: + +```yaml +include: + - template: DAST.gitlab-ci.yml +dast: + image: registry.example.com/namespace/dast:latest +``` + +The DAST job should now use local copies of the DAST analyzers to scan your code and generate +security reports without requiring internet access. + +Alternatively, you can use the CI/CD variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 9fc90c427c5..1cb21d34853 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -10,7 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab Ultimate 12.0. Use the dependency list to review your project's dependencies and key -details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. +details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. + +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. 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. @@ -71,4 +74,12 @@ If the [License Compliance](../../compliance/license_compliance/index.md) CI job ## Downloading the dependency list You can download your project's full list of dependencies and their details in -`JSON` format by selecting the download button. +`JSON` format. + +### In the UI + +You can download your project’s list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. + +### Using the API + +You can download your project’s list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 76a14aae715..565b9c29934 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -7,8 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. - The Dependency Scanning feature can automatically find security vulnerabilities in your dependencies while you're developing and testing your applications. For example, dependency scanning lets you know if your application uses an external (open source) library that is known to be @@ -29,19 +27,11 @@ either: GitLab checks the dependency scanning report, compares the found vulnerabilities between the source and target branches, and shows the information on the -merge request. +merge request. The results are sorted by the [severity](../vulnerabilities/severities.md) of the +vulnerability.  -The results are sorted by the severity of the vulnerability: - -1. Critical -1. High -1. Medium -1. Low -1. Unknown -1. Everything else - ## Requirements To run dependency scanning jobs, by default, you need GitLab Runner with the @@ -53,29 +43,283 @@ WARNING: If you use your own runners, make sure your installed version of Docker is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +WARNING: +Dependency Scanning does not support run-time installation of compilers and interpreters. +If you have need of this, please explain why by filling out the survey [here](https://docs.google.com/forms/d/e/1FAIpQLScKo7xEYA65rOjPTGIufAyfjPGnCALSJZoTxBlvskfFMEOZMw/viewform). + ## Supported languages and package managers -GitLab relies on [`rules`](../../../ci/yaml/index.md#rules) to start relevant analyzers depending on the languages detected in the repository. -The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. +Dependency Scanning automatically detects the languages used in the repository. All analyzers +matching the detected languages are run. There is usually no need to customize the selection of +analyzers. We recommend not specifying the analyzers so you automatically use the full selection +for best coverage, avoiding the need to make adjustments when there are deprecations or removals. +However, you can override the selection using the variable `DS_EXCLUDED_ANALYZERS`. + +The language detection relies on CI job [`rules`](../../../ci/yaml/index.md#rules) and searches a +maximum of two directory levels from the repository's root. For example, the +`gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or +`api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. The following languages and dependency managers are supported: -| Package Managers | Languages | Supported files | Scan tools | -| ------------------- | --------- | --------------- | ------------ | -| [Bundler](https://bundler.io/) | Ruby | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | -| [Composer](https://getcomposer.org/) | PHP | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | -| [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | -| [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | -| [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | -| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | -| [npm](https://www.npmjs.com/) (7 and earlier), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package.json` | [Retire.js](https://retirejs.github.io/retire.js/) | -| [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | -| [`setuptools`](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | -| [sbt](https://www.scala-sbt.org/) (*2*) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | - -1. [Pipenv](https://pipenv.pypa.io/en/latest/) projects are scanned when a `Pipfile` is present. +<style> +table.supported-languages tr:nth-child(even) { + background-color: transparent; +} + +table.supported-languages td { + border-left: 1px solid #dbdbdb; + border-right: 1px solid #dbdbdb; + border-bottom: 1px solid #dbdbdb; +} + +table.supported-languages tr td:first-child { + border-left: 0; +} + +table.supported-languages tr td:last-child { + border-right: 0; +} + +table.supported-languages ul { + list-style-type: none; + padding-left: 0px; + margin-bottom: 0px; +} +</style> + +<table class="supported-languages"> + <thead> + <tr> + <th>Language</th> + <th>Package Manager</th> + <th>Package Manager Versions</th> + <th>Supported files</th> + <th>Analyzer</th> + <th><a href="#how-multiple-files-are-processed">Processes multiple files?</a></th> + </tr> + </thead> + <tbody> + <tr> + <td rowspan="2">Ruby</td> + <td rowspan="2"><a href="https://bundler.io/">Bundler</a></td> + <td rowspan="2">Any</td> + <td> + <ul> + <li><code>Gemfile.lock</code></li> + <li><code>gems.locked</code></li> + </ul> + </td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>Y</td> + </tr> + <tr> + <td><code>Gemfile.lock</code></td> + <td><a href="https://github.com/rubysec/bundler-audit">bundler-audit</a></td> + <td>N</td> + </tr> + <tr> + <td>PHP</td> + <td><a href="https://getcomposer.org/">Composer</a></td> + <td>Any</td> + <td><code>composer.lock</code></td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>Y</td> + </tr> + <tr> + <td>C</td> + <td rowspan="2"><a href="https://conan.io/">Conan</a></td> + <td rowspan="2">Any</td> + <td rowspan="2"><a href="https://docs.conan.io/en/latest/versioning/lockfiles.html"><code>conan.lock</code></a></td> + <td rowspan="2"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td rowspan="2">Y</td> + </tr> + <tr> + <td>C++</td> + </tr> + <tr> + <td>Go</td> + <td><a href="https://golang.org/">Golang</a></td> + <td>Any</td> + <td><code>go.sum</code></td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>Y</td> + </tr> + <tr> + <td rowspan="2">Java</td> + <td><a href="https://gradle.org/">Gradle</a></td> + <td>Any</td> + <td> + <ul> + <li><code>build.gradle</code></li> + <li><code>build.gradle.kts</code></li> + </ul> + </td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>N</td> + </tr> + <tr> + <td><a href="https://maven.apache.org/">Maven</a></td> + <td>Any</td> + <td><code>pom.xml</code></td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>N</td> + </tr> + <tr> + <td rowspan="3">JavaScript</td> + <td rowspan="2"><a href="https://www.npmjs.com/">npm</a></td> + <td rowspan="2">Any</td> + <td> + <ul> + <li><code>package-lock.json</code></li> + <li><code>npm-shrinkwrap.json</code></li> + </ul> + </td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>Y</td> + </tr> + <tr> + <td><code>package.json</code></td> + <td><a href="https://retirejs.github.io/retire.js/">Retire.js</a></td> + <td>N</td> + </tr> + <tr> + <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> + <td>1.x</td> + <td><code>yarn.lock</code></td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>Y</td> + </tr> + <tr> + <td>.NET</td> + <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> + <td rowspan="2">>= 4.9</td> + <td rowspan="2"><a href="https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> + <td rowspan="2"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td rowspan="2">Y</td> + </tr> + <tr> + <td>C#</td> + </tr> + <tr> + <td rowspan="3">Python</td> + <td><a href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></td> + <td>Any</td> + <td><code>setup.py</code></td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>N</td> + </tr> + <tr> + <td><a href="https://pip.pypa.io/en/stable/">pip</a></td> + <td>Any</td> + <td> + <ul> + <li><code>requirements.txt</code></li> + <li><code>requirements.pip</code></li> + <li><code>requires.txt</code></li> + </ul> + </td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>N</td> + </tr> + <tr> + <td><a href="https://pipenv.pypa.io/en/latest/">Pipenv</a></td> + <td>Any</td> + <td> + <ul> + <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> + <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></li> + </ul> + </td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>N</td> + </tr> + <tr> + <td>Scala</td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></td> + <td>Any</td> + <td><code>build.sbt</code></td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> + <td>N</td> + </tr> + </tbody> +</table> + +### Notes regarding supported languages and package managers + +1. The presence of a `Pipfile.lock` file alone will _not_ trigger the analyzer; the presence of a `Pipfile` is still required in order +for the analyzer to be executed. However, if a `Pipfile.lock` file is found, it will be used by `Gemnasium` to scan the exact package +versions listed in this file. + + Support for `Pipfile.lock` files without requiring the presence of a `Pipfile` will be implemented in the following upcoming issue: + [Dependency Scanning of Pipfile.lock without installing project dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/299294). + 1. Support for [sbt](https://www.scala-sbt.org/) 1.3 and above was added in GitLab 13.9. +### How analyzers are triggered + +GitLab relies on [`rules:exists`](../../../ci/yaml/index.md#rulesexists) to start the relevant analyzers for the languages detected by the presence of the +`Supported files` in the repository as shown in the [table above](#supported-languages-and-package-managers). + +The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if +a repository contains either a `Gemfile.lock` or `api/Gemfile.lock` file, but not if the only supported dependency file is `api/client/Gemfile.lock`. + +### How multiple files are processed + +NOTE: +If you've run into problems while scanning multiple files, please contribute a comment to +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337056). + +#### Ruby + +The following analyzers are executed, each of which have different behavior when processing multiple files: + +- [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) + + Supports multiple lockfiles. + +- [bundler-audit](https://github.com/rubysec/bundler-audit) + + Does not support multiple lockfiles. When multiple lockfiles exist, `bundler-audit` + analyzes the first lockfile discovered while traversing the directory tree in alphabetical order. + +We execute both analyzers because they use different sources of vulnerability data. The result is more comprehensive analysis than if only one was executed. + +#### Python + +We only execute one build in the directory where a requirements file has been detected, such as `requirements.txt` or any +variation of this file (for example, `requirements.pip` or `requires.txt`). + +#### Java and Scala + +We only execute one build in the directory where a build file has been detected, such as `build.sbt` or `build.gradle`. +Please note, we support the following types of Java project stuctures: + +- [multi-project sbt builds](https://www.scala-sbt.org/1.x/docs/Multi-Project.html) +- [multi-project gradle builds](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) +- [multi-module maven projects](https://maven.apache.org/pom.html#Aggregation) + +#### JavaScript + +The following analyzers are executed, each of which have different behavior when processing multiple files: + +- [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) + + Supports multiple lockfiles + +- [Retire.js](https://retirejs.github.io/retire.js/) + + Does not support multiple lockfiles. When multiple lockfiles exist, `Retire.js` + analyzes the first lockfile discovered while traversing the directory tree in alphabetical order. + +We execute both analyzers because they use different sources of vulnerability data. The result is more comprehensive analysis than if only one was executed. + +#### PHP, Go, C, C++, .NET, C# + +The analyzer for these languages supports multiple lockfiles. + +### Future support for additional languages + Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. For workarounds, see the [Troubleshooting section](#troubleshooting) @@ -113,17 +357,8 @@ always take the latest dependency scanning artifact available. ### Enable Dependency Scanning via an automatic merge request > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4908) in GitLab 14.1. -> - [Deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-configure-dependency-scanning-via-a-merge-request). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -There can be -[risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. +> - [Enabled with `sec_dependency_scanning_ui_enable` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/282533) for self-managed GitLab in GitLab 14.1 and is ready for production use. +> - [Feature flag sec_dependency_scanning_ui_enable removed](https://gitlab.com/gitlab-org/gitlab/-/issues/326005) in GitLab 14.2. To enable Dependency Scanning in a project, you can create a merge request from the Security Configuration page. @@ -624,7 +859,7 @@ Generally, the approach is the following: 1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/index.md#dependencies) to your `dependency_scanning` job to make use of the converted definitions files. -For example, the currently unsupported `poetry.lock` file can be +For example, the unsupported `poetry.lock` file can be [converted](https://python-poetry.org/docs/cli/#export) to the supported `requirements.txt` as follows. @@ -633,25 +868,17 @@ include: - template: Dependency-Scanning.gitlab-ci.yml stages: - - .pre - test variables: PIP_REQUIREMENTS_FILE: "requirements-converted.txt" -convert-poetry: - stage: .pre - image: python:3-slim - script: +gemnasium-python-dependency_scanning: + # Work around https://gitlab.com/gitlab-org/gitlab/-/issues/7006 + before_script: - pip install poetry # Or via another method: https://python-poetry.org/docs/#installation - - poetry export --output "$PIP_REQUIREMENTS_FILE" - artifacts: - paths: - - "$PIP_REQUIREMENTS_FILE" - -dependency_scanning: - stage: test - dependencies: ["convert-poetry"] + - poetry export --output="$PIP_REQUIREMENTS_FILE" + - rm poetry.lock pyproject.toml ``` ### `Error response from daemon: error processing tar file: docker-tar: relocation error` @@ -681,22 +908,3 @@ with a dependency on this version of Python should use `retire.js` version 2.10. ### Error: `dependency_scanning is used for configuration only, and its script should not be executed` For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). - -### Enable or disable Configure Dependency Scanning via a Merge Request - -Configure Dependency Scanning via a Merge Request 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 disable it: - -```ruby -Feature.disable(:sec_dependency_scanning_ui_enable) -``` - -To enable it: - -```ruby -Feature.enable(:sec_dependency_scanning_ui_enable) -``` diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differdeleted file mode 100644 index 05ca74c3d5c..00000000000 --- a/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 616d2f8c790..3b0725021ef 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -114,7 +114,7 @@ rules: If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#security-scanning-tools) behave as described below. -For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch. Please note that one tool may use many analyzers. +For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch. One tool might use many analyzers. Our language and package manager specific jobs attempt to assess which analyzer(s) they should run for your project so that you can do less configuration. diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index d87da15b4b0..3bf9d85cd0b 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -61,7 +61,7 @@ mirroring the packages inside your own offline network. Once a vulnerability is found, you can interact with it. Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). -Please note that in some cases the reported vulnerabilities provide metadata that can contain +In some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. ### Resolving vulnerabilities @@ -87,7 +87,7 @@ above. You can find more information at each of the pages below: - [Container scanning offline directions](../container_scanning/index.md#running-container-scanning-in-an-offline-environment) - [SAST offline directions](../sast/index.md#running-sast-in-an-offline-environment) -- [DAST offline directions](../dast/index.md#running-dast-in-an-offline-environment) +- [DAST offline directions](../dast/run_dast_offline.md#run-dast-in-an-offline-environment) - [License Compliance offline directions](../../compliance/license_compliance/index.md#running-license-compliance-in-an-offline-environment) - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment) diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 076872c9864..3d0135678b7 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -129,9 +129,9 @@ rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `dast` | The action's type. | -| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. | -| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. | +| `scan` | `string` | `dast`, `secret_detection` | The action's type. | +| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | +| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| Note the following: @@ -144,6 +144,11 @@ Note the following: - When configuring policies with a scheduled DAST scan, the author of the commit in the security policy project's repository must have access to the scanner and site profiles. Otherwise, the scan is not scheduled successfully. +- For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) + are not supported. +- A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in + [`historic`](../secret_detection/index.md#full-history-secret-scan) + mode when executed as part of a scheduled scan. Here's an example: @@ -161,8 +166,8 @@ scan_execution_policy: - scan: dast scanner_profile: Scanner Profile A site_profile: Site Profile B -- name: Enforce DAST scan every 10 minutes - description: This policy enforces a DAST scan to run every 10 minutes +- name: Enforce DAST and secret detection scans every 10 minutes + description: This policy enforces DAST and secret detection scans to run every 10 minutes enabled: true rules: - type: schedule @@ -173,12 +178,25 @@ scan_execution_policy: - scan: dast scanner_profile: Scanner Profile C site_profile: Site Profile D + - scan: secret_detection +- name: Enforce Secret Detection in every default branch pipeline + description: This policy enforces pipeline configuration to have a job with Secret Detection scan for the default branch + enabled: true + rules: + - type: pipeline + branches: + - main + actions: + - scan: secret_detection ``` -In this example, the DAST scan runs with the scanner profile `Scanner Profile A` and the site -profile `Site Profile B` for every pipeline executed on branches that match the -`release/*` wildcard (for example, branch name `release/v1.2.1`); and the DAST scan runs with -the scanner profile `Scanner Profile C` and the site profile `Site Profile D` every 10 minutes. +In this example: + +- For every pipeline executed on branches that match the `release/*` wildcard (for example, branch + `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. +- DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` + and `Site Profile D`. +- Secret detection scans run for every pipeline executed on the `main` branch. ## Security Policy project selection diff --git a/doc/user/application_security/sast/img/sast_v13_2.png b/doc/user/application_security/sast/img/sast_v13_2.png Binary files differdeleted file mode 100644 index 5697ed9beb0..00000000000 --- a/doc/user/application_security/sast/img/sast_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index c64df616925..6e88f38d900 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -31,8 +31,8 @@ The results are sorted by the priority of the vulnerability: 1. High 1. Medium 1. Low +1. Info 1. Unknown -1. Everything else A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard does not show SAST scanner output. For example, if the SAST @@ -71,6 +71,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | | .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | | Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | +| C | [Semgrep](https://semgrep.dev) | 14.2 | | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | @@ -146,6 +147,7 @@ as shown in the following table: | [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | | [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | | [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | +| [False Positive Detection](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -355,6 +357,12 @@ To create a custom ruleset: value = "gosec-config.json" ``` +### False Positive Detection **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292686) in GitLab 14.2. + +Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. + ### Using CI/CD variables to pass credentials for private repositories Some analyzers require downloading the project's dependencies in order to diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 938bd3b41d5..b6ff68c861b 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -35,7 +35,7 @@ GitLab displays identified secrets visibly in a few places: Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). -The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks/gitleaks.toml) includes the following key types: +The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: - Cloud services: - Amazon Web Services (AWS) diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png Binary files differdeleted file mode 100644 index 72b24a3fd28..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png Binary files differnew file mode 100644 index 00000000000..3a195a5ce8d --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 806bc03e30e..b799177ec5a 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -51,7 +51,7 @@ The security dashboard and vulnerability report displays information about vulne At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline ran against. - + Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 6437f2325e8..a727dc88ffc 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -75,7 +75,7 @@ The issue is then opened so you can take further action. Prerequisites: -- [Enable Jira integration](../../project/integrations/jira.md). +- [Enable Jira integration](../../../integration/jira/index.md). The **Enable Jira issues 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. diff --git a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png Binary files differdeleted file mode 100644 index 72443180e09..00000000000 --- a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png Binary files differnew file mode 100644 index 00000000000..193efe9c386 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_10.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_10.png Binary files differdeleted file mode 100644 index f9f60810f20..00000000000 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_10.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png Binary files differnew file mode 100644 index 00000000000..056e051363d --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index da59c0fbe79..c2c2e7459ba 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -16,7 +16,7 @@ At all levels, the Vulnerability Report contains: - Filters for common vulnerability attributes. - Details of each vulnerability, presented in tabular layout. - + ## Project-level Vulnerability Report @@ -49,7 +49,7 @@ You can filter the vulnerabilities table by: |:---------|:------------------| | Status | Detected, Confirmed, Dismissed, Resolved. | | Severity | Critical, High, Medium, Low, Info, Unknown. | -| Scanner | For more details, see [Scanner filter](#scanner-filter). | +| Tool | For more details, see [Tool filter](#tool-filter). | | Project | For more details, see [Project filter](#project-filter). | | Activity | For more details, see [Activity filter](#activity-filter). | @@ -70,17 +70,17 @@ The filters' criteria are combined to show only vulnerabilities matching all cri An exception to this behavior is the Activity filter. For more details about how it works, see [Activity filter](#activity-filter). -## Scanner filter +## Tool filter -The scanner filter allows you to focus on vulnerabilities detected by selected scanners. +The tool filter allows you to focus on vulnerabilities detected by selected tools. -When using the scanner filter, you can choose: +When using the tool filter, you can choose: -- **All scanners** (default). -- Individual GitLab-provided scanners. -- Any integrated 3rd-party scanner. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229661) in GitLab 13.12. +- **All tools** (default). +- Individual GitLab-provided tools. +- Any integrated 3rd-party tool. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229661) in GitLab 13.12. -For details of each of the available scanners, see [Security scanning tools](../index.md#security-scanning-tools). +For details of each of the available tools, see [Security scanning tools](../index.md#security-scanning-tools). ### Project filter @@ -143,7 +143,7 @@ To change the status of vulnerabilities in the table: 1. Select the checkbox for each vulnerability you want to update the status of. 1. In the dropdown that appears select the desired status, then select **Change status**. - + ## Export vulnerability details diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 1f794bac37f..09123fdd472 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CI/CD Tunnel -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. +> - Pre-configured `KUBECONFIG` [added](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. @@ -21,47 +22,22 @@ Prerequisites: - An [Agent record](index.md#create-an-agent-record-in-gitlab). - The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster). -To access your cluster from a CI/CD job through the tunnel: +If your project has one or more Agent records, a `KUBECONFIG` variable that is compatible with `kubectl` is provided to your CI/CD jobs. A separate context (`kubecontext`) is available for each configured Agent. By default, no context is selected. -1. In your `.gitlab-ci.yml` add a section that creates a `kubectl` compatible configuration file (`kubecontext`) and use it in one - or more jobs: +Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. - ```yaml - variables: - AGENT_ID: 4 # agent id that you got when you created the agent record - KUBE_CFG_FILE: "$CI_PROJECT_DIR/.kubeconfig.agent.yaml" +To access your cluster from a CI/CD job through the tunnel: - .kubectl_config: &kubectl_config - - | - cat << EOF > "$KUBE_CFG_FILE" - apiVersion: v1 - kind: Config - clusters: - - name: agent - cluster: - server: https://kas.gitlab.com/k8s-proxy/ - users: - - name: agent - user: - token: "ci:$AGENT_ID:$CI_JOB_TOKEN" - contexts: - - name: agent - context: - cluster: agent - user: agent - current-context: agent - EOF +1. In your `.gitlab-ci.yml` select the context for the agent you wish to use: + ```yaml deploy: image: name: bitnami/kubectl:latest entrypoint: [""] script: - - *kubectl_config - - kubectl --kubeconfig="$KUBE_CFG_FILE" get pods + - kubectl config use-context path/to/agent-configuration-project:your-agent-name + - kubectl get pods ``` 1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created. - -We are working on [creating the configuration file automatically](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) -to simplify the process. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 83933524fd4..c59d2a1f61c 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -140,46 +140,25 @@ All the options for the [Kubernetes Agent configuration repository](repository.m ### Create an Agent record in GitLab +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI. + Next, create a GitLab Rails Agent record to associate it with the configuration repository project. Creating this record also creates a Secret needed to configure -the Agent in subsequent steps. You can create an Agent record with GraphQL: - - ```graphql - mutation createAgent { - # agent-name should be the same as specified above in the config.yaml - createClusterAgent(input: { projectPath: "path-to/your-configuration-project", name: "<agent-name>" }) { - clusterAgent { - id - name - } - errors - } - } - - mutation createToken { - clusterAgentTokenCreate( - input: { - clusterAgentId: "<cluster-agent-id-taken-from-the-previous-mutation>" - description: "<optional-description-of-token>" - name: "<required-name-given-to-token>" - } - ) { - secret # This is the value you need to use on the next step - token { - createdAt - id - } - errors - } - } - ``` +the Agent in subsequent steps. -WARNING: -GraphQL only displays the token and ids **one time** after creating it. Make sure to write down the `secret`, `clusterAgentId`, and `clusterAgentTokenId`; you'll need them later. +In GitLab: + +1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select the **GitLab Agent managed clusters** tab. +1. Select **Integrate with the GitLab Agent**. +1. From the **Select an Agent** dropdown menu, select the Agent you want to connect and select **Next** to access the installation form. +1. The form reveals your registration token. Securely store this secret token as you cannot view it again. +1. Copy the command under **Recommended installation method**. + +In your computer: - If you are new to using the GitLab GraphQL API, refer to the - [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), - or the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). +1. Open your local terminal and connect to your cluster. +1. Run the command you copied from the installation form. ### Install the Agent into the cluster @@ -192,7 +171,7 @@ kubectl create namespace gitlab-kubernetes-agent To perform a one-liner installation, run the command below. Make sure to replace: -- `your-agent-token` with the token received from the previous step. +- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). - `gitlab-kubernetes-agent` with the namespace you defined in the previous step. - `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. diff --git a/doc/user/clusters/img/jupyter-git-extension.gif b/doc/user/clusters/img/jupyter-git-extension.gif Binary files differdeleted file mode 100644 index 14dc567af2a..00000000000 --- a/doc/user/clusters/img/jupyter-git-extension.gif +++ /dev/null diff --git a/doc/user/clusters/img/jupyter-gitclone.png b/doc/user/clusters/img/jupyter-gitclone.png Binary files differdeleted file mode 100644 index aff194dea43..00000000000 --- a/doc/user/clusters/img/jupyter-gitclone.png +++ /dev/null diff --git a/doc/user/clusters/img/threat_monitoring_v12_9.png b/doc/user/clusters/img/threat_monitoring_v12_9.png Binary files differdeleted file mode 100644 index 9097f9334a8..00000000000 --- a/doc/user/clusters/img/threat_monitoring_v12_9.png +++ /dev/null diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index d2861ce2946..5e6843144fc 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -22,8 +22,8 @@ Although, the [Cluster management project template](management_project_template. requires that you manually do the last steps of these sections, [Enable Prometheus integration for your cluster](#enable-prometheus-integration-for-your-cluster) or [Enable Elastic Stack integration for your cluster](#enable-elastic-stack-integration-for-your-cluster) -depending on which application you are installing. We plan to also automate this step in the future, -see the [opened issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326565). +depending on which application you are installing. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/326565) +to automate this step. ## Prometheus cluster integration diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index eb86c1702cc..1de17396bf4 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -53,13 +53,13 @@ project. This image consists of a set of Bash utility scripts to support [Helm v 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 manage. -By default, each `helmfile.yaml` in these sub-paths will have the attribute `installed: true`, which signifies that everytime -the pipeline runs, Helmfile will try to either install or update your apps according to the current state of your -cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile will try to uninstall this app +By default, each `helmfile.yaml` in these sub-paths have the attribute `installed: true`. This signifies that every time +the pipeline runs, Helmfile tries to either install or update your apps according to the current state of your +cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile tries try to uninstall this app from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works. Furthermore, each app has an `applications/{app}/values.yaml` file. This is the -place where you can define some default values for your app's Helm chart. Some apps will already have defaults +place where you can define some default values for your app's Helm chart. Some apps already have defaults pre-defined by GitLab. #### Built-in applications @@ -68,19 +68,19 @@ The built-in applications are intended to provide an easy way to get started wit The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: -- Apparmor -- Cert-manager -- Cilium -- Elastic Stack -- Falco -- Fluentd -- GitLab Runner -- Ingress -- Prometheus -- Sentry -- Vault - -### Migrating from GitLab Managed Apps +- [Apparmor](../infrastructure/clusters/manage/management_project_applications/apparmor.md) +- [Cert-manager](../infrastructure/clusters/manage/management_project_applications/certmanager.md) +- [Cilium](../infrastructure/clusters/manage/management_project_applications/cilium.md) +- [Elastic Stack](../infrastructure/clusters/manage/management_project_applications/elasticstack.md) +- [Falco](../infrastructure/clusters/manage/management_project_applications/falco.md) +- [Fluentd](../infrastructure/clusters/manage/management_project_applications/fluentd.md) +- [GitLab Runner](../infrastructure/clusters/manage/management_project_applications/runner.md) +- [Ingress](../infrastructure/clusters/manage/management_project_applications/ingress.md) +- [Prometheus](../infrastructure/clusters/manage/management_project_applications/prometheus.md) +- [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md) +- [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) + +### Migrate from GitLab Managed Apps If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to [migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md) diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png Binary files differdeleted file mode 100644 index 73a5c92670a..00000000000 --- a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png +++ /dev/null diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index fb6b3fe2cf6..e7f6f908860 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -1,102 +1,9 @@ --- -type: reference, howto -stage: Manage -group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../compliance_report/index.md' +remove_date: '2021-10-23' --- -# Compliance Dashboard **(ULTIMATE)** +This file was moved to [another location](../compliance_report/index.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. - -The Compliance Dashboard gives you the ability to see a group's merge request activity -by providing a high-level view for all projects in the group. For example, code approved -for merging into production. - -## Overview - -To access the Compliance Dashboard for a group, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu. - - - -NOTE: -The Compliance Dashboard shows only the latest MR on each project. - -## Merge request drawer - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. - -When you click on a row, a drawer is shown that provides further details about the merge -request: - -- Project name and [compliance framework label](../../project/settings/index.md#compliance-frameworks), - if the project has one assigned. -- Link to the merge request. -- The merge request's branch path in the format `[source] into [target]`. -- A list of users that committed changes to the merge request. -- A list of users that commented on the merge request. -- A list of users that approved the merge request. -- The user that merged the merge request. - -## Use cases - -This feature is for people who care about the compliance status of projects within their group. - -You can use the dashboard to: - -- Get an overview of the latest merge request for each project. -- See if merge requests were approved and by whom. -- See merge request authors. -- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each merge request. - -## Permissions - -- On [GitLab Ultimate](https://about.gitlab.com/pricing/) tier. -- By **Administrators** and **Group Owners**. - -## Approval status and separation of duties - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. - -We support a separation of duties policy between users who create and approve merge requests. -The approval status column can help you identify violations of this policy. -Our criteria for the separation of duties is as follows: - -- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-authors-from-approving-their-own-work) -- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-committers-from-approving-their-own-work) -- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md) - -The "Approval status" column shows you, at a glance, whether a merge request is complying with the above. -This column has four states: - -| State | Description | -|:------|:------------| -| Empty | The merge request approval status is unknown | -|  | The merge request **does not** comply with any of the above criteria | -|  | The merge request complies with **some** of the above criteria | -|  | The merge request complies with **all** of the above criteria | - -If you do not see the success icon in your Compliance dashboard; please review the above criteria for the merge requests -project to make sure it complies with the separation of duties described above. - -## Chain of Custody report **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. - -The Chain of Custody report allows customers to export a list of merge commits within the group. -The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, -merge request author, merge request ID, merge user, pipeline ID, group name, project name, and merge request approvers. -Depending on the merge strategy, the merge commit SHA can either be a merge commit, squash commit or a diff head commit. - -To download the Chain of Custody report, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu and click **List of all merge commits** - -### Commit-specific Chain of Custody Report **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. - -You can generate a commit-specific Chain of Custody report for a given commit SHA. To do so, select -the dropdown next to the **List of all merge commits** button at the top of the Compliance Dashboard. - -NOTE: -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. +<!-- This redirect file can be deleted after <2021-10-23>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/compliance/compliance_dashboard/img/failed_icon_v13_3.png b/doc/user/compliance/compliance_report/img/failed_icon_v13_3.png Binary files differindex c3f386c9dee..c3f386c9dee 100644 --- a/doc/user/compliance/compliance_dashboard/img/failed_icon_v13_3.png +++ b/doc/user/compliance/compliance_report/img/failed_icon_v13_3.png diff --git a/doc/user/compliance/compliance_dashboard/img/success_icon_v13_3.png b/doc/user/compliance/compliance_report/img/success_icon_v13_3.png Binary files differindex ea6ca924f81..ea6ca924f81 100644 --- a/doc/user/compliance/compliance_dashboard/img/success_icon_v13_3.png +++ b/doc/user/compliance/compliance_report/img/success_icon_v13_3.png diff --git a/doc/user/compliance/compliance_dashboard/img/warning_icon_v13_3.png b/doc/user/compliance/compliance_report/img/warning_icon_v13_3.png Binary files differindex 168a7021948..168a7021948 100644 --- a/doc/user/compliance/compliance_dashboard/img/warning_icon_v13_3.png +++ b/doc/user/compliance/compliance_report/img/warning_icon_v13_3.png diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md new file mode 100644 index 00000000000..c51636e33f5 --- /dev/null +++ b/doc/user/compliance/compliance_report/index.md @@ -0,0 +1,99 @@ +--- +type: reference, howto +stage: Manage +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Compliance report **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8 as Compliance Dashboard. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/299360) to compliance report in GitLab 14.2. + +Compliance report gives you the ability to see a group's merge request activity. It provides a +high-level view for all projects in the group. For example, code approved for merging into +production. + +To access compliance report for a group, go to **{shield}** **Security & Compliance > Compliance** +on the group's menu. + +NOTE: +Compliance report shows only the latest merge request on each project. + +## Merge request drawer + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. + +When you click on a row, a drawer is shown that provides further details about the merge +request: + +- Project name and [compliance framework label](../../project/settings/index.md#compliance-frameworks), + if the project has one assigned. +- Link to the merge request. +- The merge request's branch path in the format `[source] into [target]`. +- A list of users that committed changes to the merge request. +- A list of users that commented on the merge request. +- A list of users that approved the merge request. +- The user that merged the merge request. + +## Use cases + +This feature is for people who care about the compliance status of projects within their group. + +You can use the report to: + +- Get an overview of the latest merge request for each project. +- See if merge requests were approved and by whom. +- See merge request authors. +- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each merge request. + +## Permissions + +- On [GitLab Ultimate](https://about.gitlab.com/pricing/) tier. +- By **Administrators** and **Group Owners**. + +## Approval status and separation of duties + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. + +We support a separation of duties policy between users who create and approve merge requests. +The approval status column can help you identify violations of this policy. +Our criteria for the separation of duties is as follows: + +- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author) +- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits) +- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md) + +The **Approval status** column shows you at a glance whether a merge request is complying with the above. +This column has four states: + +| State | Description | +|:------|:------------| +| Empty | The merge request approval status is unknown | +|  | The merge request **does not** comply with any of the above criteria | +|  | The merge request complies with **some** of the above criteria | +|  | The merge request complies with **all** of the above criteria | + +If you see a non-success state, review the criteria for the merge request's project to ensure it complies with the separation of duties. + +## Chain of Custody report **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. + +The Chain of Custody report allows customers to export a list of merge commits within the group. +The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, +merge request author, merge request ID, merge user, pipeline ID, group name, project name, and merge request approvers. +Depending on the merge strategy, the merge commit SHA can be a merge commit, squash commit, or a diff head commit. + +To download the Chain of Custody report, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu and click **List of all merge commits** + +### Commit-specific Chain of Custody Report **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. + +You can generate a commit-specific Chain of Custody report for a given commit SHA. To do so, select +the dropdown next to the **List of all merge commits** button at the top of the compliance report. + +NOTE: +The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. +The remaining records are truncated when this limit is reached. diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index 69deefd08a7..61b65bf254f 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The compliance tools provided by GitLab let you keep an eye on various aspects of your project. The following compliance tools are available: -- [Compliance Dashboard](compliance_dashboard/index.md): View recent merge request activity across +- [Compliance report](compliance_report/index.md): View recent merge request activity across all projects in a group. This lets you see if merge requests were approved, and by whom. - [License Compliance](license_compliance/index.md): Search your project's dependencies for their licenses. This lets you determine if the licenses of your project's dependencies are compatible diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png Binary files differindex c188c6cd834..2ad08919f86 100644 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png +++ b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 1a43c5ae96f..e39a3f7111b 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -83,6 +83,9 @@ The reported licenses might be incomplete or inaccurate. ## Requirements +WARNING: +License Compliance Scanning does not support run-time installation of compilers and interpreters. + To run a License Compliance scanning job, you need GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). diff --git a/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png Binary files differdeleted file mode 100644 index bd0aaca79b2..00000000000 --- a/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png +++ /dev/null diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 825f9be6ba6..a1d8863710c 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -138,6 +138,8 @@ who have at least the Reporter role.  +You can also make an [entire issue confidential](../project/issues/confidential_issues.md). + ## Show only comments > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index e05fc582dc0..e288be87474 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -20,21 +20,13 @@ may be unavailable to you. In this case, you'll see a warning like this in the feature documentation: This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](#risks-when-enabling-features-still-in-development). +[risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development). Refer to this feature's version history for more details. In the version history note, you'll find information on the state of the feature flag, including whether the feature is on ("enabled by default") or off ("disabled by default") for self-managed GitLab instances and for users of -GitLab.com. To see the full notes: - -1. Click the three-dots icon (ellipsis) to expand version history notes: - -  - -1. Read the version history information: - -  +GitLab.com. If you're a user of a GitLab self-managed instance and you want to try to use a disabled feature, you can ask a [GitLab administrator to enable it](../administration/feature_flags.md), @@ -42,17 +34,3 @@ although changing a feature's default state isn't recommended. If you're a GitLab.com user and the feature is disabled, be aware that GitLab may be working on the feature for potential release in the future. - -## Risks when enabling features still in development - -Features that are disabled by default may change or be removed without notice in a future version of GitLab. - -Data corruption, stability degradation, or performance degradation might occur if -you enable a feature that's disabled by default. Problems caused by using a default -disabled feature aren't covered by GitLab support, unless you were directed by GitLab -to enable the feature. - -## Risks when disabling released features - -In most cases, the feature flag code is removed in a future version of GitLab. -If and when that occurs, from that point onward you can't keep the feature in a disabled state. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index ef458db67f0..024ab86a1b7 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -67,6 +67,13 @@ Similarly, you can clone a project's wiki to back it up. All files [uploaded after August 22, 2020](../project/wiki/index.md#create-a-new-wiki-page) are included when cloning. +## Delayed project deletion **(PREMIUM SAAS)** + +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-removal). + ## Alternative SSH port GitLab.com can be reached by using a [different SSH port](https://about.gitlab.com/blog/2016/02/18/gitlab-dot-com-now-supports-an-alternate-git-plus-ssh-port/) for `git+ssh`. @@ -148,7 +155,7 @@ 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)). For outgoing connections from CI/CD runners, we are not providing static IP -addresses. All GitLab runners are deployed into Google Cloud Platform (GCP). Any +addresses. All GitLab.com shared runners are deployed into Google Cloud Platform (GCP). Any IP-based firewall can be configured by looking up all [IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#find_ip_range). @@ -177,11 +184,11 @@ The following limits apply for [Webhooks](../project/integrations/webhooks.md): | [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks) | `100` per project, `50` per group | `100` per project, `50` per group | | Maximum payload size | 25 MB | 25 MB | -## Shared runners +## Shared Build Cloud runners GitLab has shared runners on GitLab.com that you can use to run your CI jobs. -For more information, see [choosing a runner](../../ci/runners/index.md). +For more information, see [GitLab Build Cloud runners](../../ci/runners/index.md). ## Sidekiq diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md deleted file mode 100644 index feceafd0991..00000000000 --- a/doc/user/group/bulk_editing/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../../user/group/index.md' -remove_date: '2021-08-13' ---- - -This document was moved to [another location](../../../user/group/index.md). - -<!-- This redirect file can be deleted after <2021-08-13>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 670ecc48370..a2d7f358cd9 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -55,6 +55,7 @@ Contributions per group member are also presented in tabular format. Click a col - Number of closed issues - Number of opened MRs - Number of merged MRs +- Number of closed MRs - Number of total contributions  diff --git a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_1.png b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_1.png Binary files differdeleted file mode 100644 index a790a560a9b..00000000000 --- a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_1.png +++ /dev/null diff --git a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png Binary files differnew file mode 100644 index 00000000000..073e747153f --- /dev/null +++ b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 4332f261481..5c84a343da9 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -10,6 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333556) in GitLab 14.1. > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. +> - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. +> - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. +> - Multiselect [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. Prerequisites: @@ -17,7 +20,7 @@ Prerequisites: To access Group DevOps Adoption, go to your group and select **Analytics > DevOps Adoption**. -Group DevOps Adoption shows you how individual groups and sub-groups within your organization use the following features: +Group DevOps Adoption shows you how individual groups and subgroups within your organization use the following features: - Dev - Approvals @@ -26,22 +29,27 @@ Group DevOps Adoption shows you how individual groups and sub-groups within your - Merge requests - Sec - DAST + - Dependency Scanning + - Fuzz Testing - SAST - Ops - Deployments - Pipelines - Runners -When managing groups in the UI, you can add your sub-groups with the **Add sub-group to table** +When managing groups in the UI, you can add or remove your subgroups with the **Add or remove subgroups** button, in the top right hand section of your Groups pages. With DevOps Adoption you can: - Verify whether you are getting the return on investment that you expected from GitLab. -- Identify specific sub-groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. -- Find the sub-groups that have adopted certain features and can provide guidance to other sub-groups on how to use those features. +- Identify specific subgroups that are lagging in their adoption of GitLab, so you can help them along in their DevOps journey. +- Find the subgroups that have adopted certain features, and can provide guidance to other subgroups on how to use those features. - + + +Feature adoption is based on usage in the previous calendar month. Data is updated on the first day +of each month. If the monthly update fails, it tries again daily until successful. ## Enable data processing @@ -55,10 +63,10 @@ GitLab requires around a minute to process it. ## What is displayed DevOps Adoption displays feature adoption data for the given group -and any added sub-groups for the current calendar month. +and any added subgroups for the current calendar month. Each group appears as a separate row in the table. For each row, a feature is considered "adopted" if it has been used in a project in the given group -during the time period (including projects in any sub-groups of the given group). +during the time period (including projects in any subgroups of the given group). ## When is a feature considered adopted @@ -79,14 +87,14 @@ Following this guideline, GitLab doesn't penalize for: over time, so we should not consider adoption to have decreased if GitLab adds features. This means we should not measure adoption by percentages, only total counts. -## Add a sub-group +## Add a subgroup -DevOps Adoption can also display data for sub-groups within the given group, +DevOps Adoption can also display data for subgroups within the given group, to show you differences in adoption across the group. -To add a sub-group to your Group DevOps Adoption report: +To add subgroups to your Group DevOps Adoption report: -1. Select **Add/remove sub-groups**. -1. Select the sub-group you want to add and select **Save changes**. +1. Select **Add or remove subgroups**. +1. Select the subgroups you want to add and select **Save changes**. -The sub-group data might not appear immediately, because GitLab requires around a minute to collect +The subgroup data might not appear immediately, because GitLab requires around a minute to collect the data. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index f6c3ea6c090..1b36d6f03df 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -40,9 +40,11 @@ The newly created epic opens. If you select **Inherited**: - For the **start date**: GitLab scans all child epics and issues assigned to the epic, - and sets the start date to match the earliest found start date or milestone. -- For the **due date**: GitLab sets the due date to match the latest due date or - milestone found among its child epics and issues. + and sets the start date to match the earliest start date found in the child epics or the milestone + assigned to the issues. +- For the **due date**: GitLab scans all child epics and issues assigned to the epic, + and sets the due date to match the latest due date found in the child epics or the milestone + assigned to the issues. These are dynamic dates and recalculated if any of the following occur: @@ -191,7 +193,10 @@ or newest items to be shown first. If you're working on items that contain private information, you can make an epic confidential. NOTE: -A confidential epic can only contain confidential issues and confidential child epics. +A confidential epic can only contain [confidential issues](../../project/issues/confidential_issues.md) +and confidential child epics. However, merge requests are public, if created in a public project. +Read [Merge requests for confidential issues](../../project/merge_requests/confidential.md) +to learn how to create a confidential merge request. To make an epic confidential: diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index d76685f992b..721afa219d0 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -11,8 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. > - Enabled on GitLab.com. -WARNING: -This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771), and migrates only some of the group data. Refer to the following information for the list of what's included in the migration. +NOTE: +The importer migrates **only** the group data listed on this page. To leave feedback on this +feature, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a subgroup of any existing top-level group. @@ -34,7 +35,6 @@ The following resources are migrated to the target instance: - The user already exists in the target GitLab instance and - The user has a public email in the source GitLab instance that matches a confirmed email in the target GitLab instance - confirmed email in the target GitLab instance - Epics ([Introduced in 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/250281)) - title - description @@ -77,8 +77,7 @@ Any other items are **not** migrated. ## Enable or disable GitLab Group Migration -Support for GitLab Group Migration is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +GitLab Migration 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: diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 787461f9d96..948f9cab659 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -37,7 +37,7 @@ Like projects, a group can be configured to limit the visibility of it to: - All signed-in users. - Only explicit group members. -The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels) +The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) on the application setting level also applies to groups. If set to internal, the explore page is empty for anonymous users. The group page has a visibility level icon. @@ -220,10 +220,10 @@ To change this setting for a specific group: 1. Select the desired option in the **Default branch protection** dropdown list. 1. Click **Save changes**. -To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). +To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches). NOTE: -In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#disable-group-owners-from-updating-default-branch-protection). +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). ## Add projects to a group @@ -248,7 +248,7 @@ To change this setting for a specific group: 1. Select the desired option in the **Allowed to create projects** dropdown list. 1. Click **Save changes**. -To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection). +To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). ## Group activity analytics **(PREMIUM)** @@ -430,6 +430,28 @@ Specifically: - In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. +## Remove a group immediately **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336985) in GitLab 14.2. + +If you don't want to wait, you can remove a group immediately. + +Prerequisites: + +- You must have at least the Owner role for a group. +- You have [marked the group for deletion](#remove-a-group). + +To immediately remove a group marked for deletion: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the "Permanently remove group" section, select **Remove group**. +1. Confirm the action when asked to. + +Your group, its subgroups, projects, and all related resources, including issues and merge requests, +are deleted. + ## Restore a group **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. @@ -494,6 +516,19 @@ To prevent members from being added to a group: All users who previously had permissions can no longer add members to a group. API requests to add a new user to a project are not possible. +## Export members as CSV **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the :ff_group_membership_export flag](../../administration/feature_flags.md). On GitLab.com, this feature is available. + +You can export a list of members in a group as a CSV. + +1. Go to your project and select **Project 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. + ## Restrict group access by IP address **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. @@ -623,15 +658,24 @@ To disable group mentions: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. > - [Inheritance and enforcement added](https://gitlab.com/gitlab-org/gitlab/-/issues/321724) in GitLab 13.11. +> - [Instance setting to enable by default added](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. -By default, projects in a group are deleted immediately. -Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, -you can configure the projects in a group to be deleted after a delayed interval. +Projects can be configured to be deleted either: + +- Immediately. +- After a delayed interval. During this interval period, the projects are in a read-only state + and can be restored, if required. The default interval period is seven days but + [is configurable](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). -During this interval period, the projects are in a read-only state and can be restored, if required. -The interval period defaults to 7 days, and can be modified by an administrator in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +On: -To enable delayed deletion of projects: +- GitLab self-managed instances, projects are deleted immediately by default. In GitLab + 14.2 and later, an administrator can + [change the default setting](../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion) for projects in newly-created groups. +- GitLab.com, see [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for + the default setting. + +To enable delayed deletion of projects in a group: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. @@ -650,17 +694,21 @@ By default, projects in a group can be forked. Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, you can prevent the projects in a group from being forked outside of the current top-level group. -Previously this setting was available only for groups enforcing group managed account. This setting will be -removed from SAML setting page and migrated to group settings. In the interim period, both of these settings are taken into consideration. -If even one is set to `true` then it will be assumed the group does not allow forking projects outside. +Previously, this setting was available only for groups enforcing a +[Group Managed Account](saml_sso/group_managed_accounts.md) in SAML. +This setting will be removed from the SAML setting page, and migrated to the +group settings page. In the interim period, both of these settings are taken into consideration. +If even one is set to `true`, then the group does not allow outside forks. -To enable prevent project forking: +To prevent projects from being forked outside the group: 1. Go to the top-level group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. 1. Check **Prevent project forking outside current group**. 1. Select **Save changes**. +Existing forks are not removed. + ## Group push rules **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in GitLab 12.8. @@ -704,6 +752,7 @@ The group's new subgroups have push rules set for them based on either: - [Lock the sharing with group feature](#prevent-a-project-from-being-shared-with-groups). - [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. +- Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/features.md).. ## Troubleshooting diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 20b8e4b0583..9240828db0a 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,7 +1,7 @@ --- type: reference -stage: Manage -group: Optimize +stage: Plan +group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 5a435f32569..5c4e66a4539 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -41,7 +41,7 @@ In GitLab, iterations are similar to milestones, with a few differences: > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-iteration-cadences). **(PREMIUM SELF)** This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). Refer to this feature's version history for more details. Iteration cadences automate some common iteration tasks. They can be used to diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 88d43715c58..811297c6eda 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -69,7 +69,7 @@ You can also filter epics in the Roadmap view by the epics': - Author - Label - Milestone -- Confidentiality +- [Confidentiality](../epics/manage_epics.md#make-an-epic-confidential) - Epic - Your Reaction diff --git a/doc/user/group/saml_sso/img/saml_group_links_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png Binary files differdeleted file mode 100644 index c78b77b8fcf..00000000000 --- a/doc/user/group/saml_sso/img/saml_group_links_v13_6.png +++ /dev/null diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index c3b57018154..a627f04fa46 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -91,7 +91,7 @@ After you set up your identity provider to work with GitLab, you must configure  NOTE: -Please note that the certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. +The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. ### SSO enforcement @@ -117,6 +117,7 @@ SSO has the following effects when enabled: even if the project is forked. - For a Git activity, users must be signed-in through SSO before they can push to or pull from a GitLab repository. +- Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> ## Providers @@ -128,15 +129,15 @@ When [configuring your identity provider](#configuring-your-identity-provider), For providers not listed below, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#notes-on-configuring-your-identity-provider) for additional guidance on information your identity provider may require. -Please note that GitLab provides the following for guidance only. +GitLab provides the following information for guidance only. If you have any questions on configuring the SAML app, please contact your provider's support. ### Azure setup notes -Please follow the Azure documentation on [configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) with the notes below for consideration. +Follow the Azure documentation on [configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) with the notes below for consideration. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regard to +For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). The video is outdated in regard to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). | GitLab Setting | Azure Field | diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index fd75c49fa6c..a0c281971fc 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -121,7 +121,7 @@ configuration. Otherwise, the Okta SCIM app may not work properly. 1. In the **Application** tab, click **Add Application**. 1. Search for **GitLab**, find and click on the 'GitLab' application. 1. On the GitLab application overview page, click **Add**. -1. Under **Application Visibility** select both check boxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users. +1. Under **Application Visibility** select both checkboxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users. 1. Click **Done** to finish adding the application. 1. In the **Provisioning** tab, click **Configure API integration**. 1. Select **Enable API integration**. diff --git a/doc/user/group/settings/img/export_panel_v13_0.png b/doc/user/group/settings/img/export_panel_v13_0.png Binary files differdeleted file mode 100644 index 36549e1f3f5..00000000000 --- a/doc/user/group/settings/img/export_panel_v13_0.png +++ /dev/null diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 5f732bee03f..a0930867b2a 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -19,9 +19,11 @@ See also: - [Project Import/Export](../../project/settings/import_export.md) - [Project Import/Export API](../../../api/project_import_export.md) -To enable GitLab import/export: +Users with the [Owner role](../../permissions.md) for a group can enable +import and export for that group: -1. On the top bar, go to **Menu > Admin > Settings > General > Visibility and access controls**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > General > Visibility and access controls**. 1. Scroll to **Import sources**. 1. Enable the desired **Import sources**. @@ -48,7 +50,8 @@ The following items are exported: - Subgroups (including all the aforementioned data) - Epics - Events -- Wikis **(PREMIUM SELF)** (Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247)) +- [Wikis](../../project/wiki/index.md#group-wikis) **(PREMIUM SELF)** + (Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247)) The following items are **not** exported: @@ -60,21 +63,21 @@ NOTE: For more details on the specific data persisted in a group export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) file. -## Exporting a Group +## Export a group -1. Navigate to your group's homepage. - -1. Click **Settings** in the sidebar. - -1. In the **Advanced** section, click the **Export Group** button. - -  +Users with the [Owner role](../../permissions.md) for a group can export the +contents of that group: +1. On the top bar, select **Menu >** **Groups** and find your group. +1. In the left sidebar, select **Settings**. +1. Scroll to the **Advanced** section, and select **Export Group**. 1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in NDJSON format. +1. Alternatively, you can download the export from the UI: -1. Alternatively, you can come back to the project settings and download the - file from there by clicking **Download export**, or generate a new file by clicking **Regenerate export**. + 1. Return to your group's **Settings > General** page. + 1. Scroll to the **Advanced** section, and select **Download export**. + You can also generate a new file by clicking **Regenerate export**. NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). @@ -103,7 +106,7 @@ on an existing group's page. 1. Click **Choose file** -1. Select the file that you exported in the [exporting a group](#exporting-a-group) section. +1. Select the file that you exported in the [Export a group](#export-a-group) section. 1. Click **Import group** to begin importing. Your newly imported group page appears after the operation completes. @@ -138,4 +141,4 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 groups per minute | -Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. +GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 773d41947e2..4d254279a3d 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -20,7 +20,12 @@ to uncover, triage, and identify the root cause of slowdowns in the software dev For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). -Group-level Value Stream Analytics is available via **Group > Analytics > Value Stream**. +To view group-level Value Stream Analytics: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. + +Value Stream Analytics at the group level includes data for the selected group and its subgroups. [Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available. diff --git a/doc/user/img/feature_flags_history_note_info_v13_2.png b/doc/user/img/feature_flags_history_note_info_v13_2.png Binary files differdeleted file mode 100644 index 07d096b6dde..00000000000 --- a/doc/user/img/feature_flags_history_note_info_v13_2.png +++ /dev/null diff --git a/doc/user/img/todos_index_v13_11.png b/doc/user/img/todos_index_v13_11.png Binary files differdeleted file mode 100644 index eedb3045d39..00000000000 --- a/doc/user/img/todos_index_v13_11.png +++ /dev/null diff --git a/doc/user/img/todos_todo_list_item.png b/doc/user/img/todos_todo_list_item.png Binary files differdeleted file mode 100644 index 91bbf9e5373..00000000000 --- a/doc/user/img/todos_todo_list_item.png +++ /dev/null diff --git a/doc/user/img/version_history_notes_collapsed_v13_2.png b/doc/user/img/version_history_notes_collapsed_v13_2.png Binary files differdeleted file mode 100644 index b85c9cb36dd..00000000000 --- a/doc/user/img/version_history_notes_collapsed_v13_2.png +++ /dev/null diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/apparmor.md b/doc/user/infrastructure/clusters/manage/management_project_applications/apparmor.md new file mode 100644 index 00000000000..7fbbbac866c --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/apparmor.md @@ -0,0 +1,30 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install AppArmor with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install AppArmor you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/apparmor/helmfile.yaml +``` + +You can define one or more AppArmor profiles by adding them into +`applications/apparmor/values.yaml` as the following: + +```yaml +profiles: + profile-one: |- + profile profile-one { + file, + } +``` + +Refer to the [AppArmor chart](https://gitlab.com/gitlab-org/charts/apparmor) for more information on this chart. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md new file mode 100644 index 00000000000..3bf79ea90c7 --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -0,0 +1,56 @@ +--- +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 +--- + +# Install cert-manager with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install cert-manager you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/cert-manager/helmfile.yaml +``` + +cert-manager: + +- Is installed by default into the `gitlab-managed-apps` namespace of your cluster. +- Can be installed with or without a default + [Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/), which requires an + email address to be specified. The email address is used by Let's Encrypt to + contact you about expiring certificates and issues related to your account. + +The following configuration in your `applications/cert-manager/helmfile.yaml` is required to install cert-manager: + +```yaml +certManager: + installed: true + letsEncryptClusterIssuer: + installed: true + email: "user@example.com" +``` + +Or without the default `ClusterIssuer`: + +```yaml +certManager: + installed: true + letsEncryptClusterIssuer: + installed: false +``` + +You can customize the installation of cert-manager by defining a +`.gitlab/managed-apps/cert-manager/values.yaml` file in your cluster +management project. Refer to the +[chart](https://github.com/jetstack/cert-manager) for the +available configuration options. + +Support for installing the Cert Manager managed application is provided by the +GitLab Configure group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md new file mode 100644 index 00000000000..4e84f2c5ef4 --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md @@ -0,0 +1,128 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install Cilium with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +[Cilium](https://cilium.io/) is a networking plugin for Kubernetes that you can use to implement +support for [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) +resources. For more information, see [Network Policies](../../../../../topics/autodevops/stages.md#network-policy). + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see the +[Container Network Security Demo for GitLab 12.8](https://www.youtube.com/watch?v=pgUEdhdhoUI). + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install cilium you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/cilium/helmfile.yaml +``` + +and update the `applications/cilium/values.yaml` to set the `clusterType`: + +```yaml +# possible values are gke or eks +clusterType: gke +``` + +The `clusterType` variable enables the recommended Helm variables for a corresponding cluster type. +You can check the recommended variables for each cluster type in the official documentation: + +- [Google GKE](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-gke/#deploy-cilium) +- [AWS EKS](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-eks/#deploy-cilium) + +Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). + +You can customize Cilium's Helm variables by defining the +`applications/cilium/values.yaml` file in your cluster +management project. Refer to the +[Cilium chart](https://github.com/cilium/cilium/tree/master/install/kubernetes/cilium) +for the available configuration options. + +You can check Cilium's installation status on the cluster management page: + +- [Project-level cluster](../../../../project/clusters/index.md): Navigate to your project's + **Infrastructure > Kubernetes clusters** page. +- [Group-level cluster](../../../../group/clusters/index.md): Navigate to your group's + **Kubernetes** page. + +WARNING: +Installation and removal of the Cilium requires a **manual** +[restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-helm/#restart-unmanaged-pods) +of all affected pods in all namespaces to ensure that they are +[managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) +by the correct networking plugin. Whenever Hubble is enabled, its related pod might require a +restart depending on whether it started prior to Cilium. For more information, see +[Failed Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#failed-deployment) +in the Kubernetes docs. + +NOTE: +Major upgrades might require additional setup steps. For more information, see +the official [upgrade guide](https://docs.cilium.io/en/v1.8/operations/upgrade/). + +By default, Cilium's +[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/#enable-policy-audit-mode) +is enabled. In audit mode, Cilium doesn't drop disallowed packets. You +can use `policy-verdict` log to observe policy-related decisions. You +can disable audit mode by adding the following to +`applications/cilium/values.yaml`: + +```yaml +config: + policyAuditMode: false + +agent: + monitor: + eventTypes: ["drop"] +``` + +The Cilium monitor log for traffic is logged out by the +`cilium-monitor` sidecar container. You can check these logs with the following command: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor +``` + +You can disable the monitor log in `.gitlab/managed-apps/cilium/values.yaml`: + +```yaml +agent: + monitor: + enabled: false +``` + +The [Hubble](https://github.com/cilium/hubble) monitoring daemon is enabled by default +and it's set to collect per namespace flow metrics. This metrics are accessible on the +[Threat Monitoring](../../../../application_security/threat_monitoring/index.md) +dashboard. You can disable Hubble by adding the following to +`applications/cilium/values.yaml`: + +```yaml +global: + hubble: + enabled: false +``` + +You can also adjust Helm values for Hubble by using +`applications/cilium/values.yaml`: + +```yaml +global: + hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' +``` + +Support for installing the Cilium managed application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md new file mode 100644 index 00000000000..3d2b3caf0af --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md @@ -0,0 +1,34 @@ +--- +stage: Monitor +group: Monitor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install Elastic Stack with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install Elastic Stack you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/elastic-stack/helmfile.yaml +``` + +Elastic Stack is installed by default into the `gitlab-managed-apps` namespace of your cluster. + +You can check the default +[`values.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/applications/elastic-stack/values.yaml) +we set for this chart. + +You can customize the installation of Elastic Stack by updating the +`applications/elastic-stack/values.yaml` file in your cluster +management project. Refer to the +[chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all +available configuration options. + +Support for installing the Elastic Stack managed application is provided by the +GitLab APM group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md new file mode 100644 index 00000000000..dff0c3bd7bc --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md @@ -0,0 +1,101 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install Falco with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +GitLab Container Host Security Monitoring uses [Falco](https://falco.org/) +as a runtime security tool that listens to the Linux kernel using eBPF. Falco parses system calls +and asserts the stream against a configurable rules engine in real-time. For more information, see +[Falco's Documentation](https://falco.org/docs/). + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install Falco you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/falco/helmfile.yaml +``` + +You can customize Falco's Helm variables by defining the +`applications/falco/values.yaml` file in your cluster +management project. Refer to the +[Falco chart](https://github.com/falcosecurity/charts/tree/master/falco) +for the available configuration options. + +WARNING: +By default eBPF support is enabled and Falco uses an +[eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe) +to pass system calls to user space. If your cluster doesn't support this, you can +configure it to use Falco kernel module instead by adding the following to +`applications/falco/values.yaml`: + +```yaml +ebpf: + enabled: false +``` + +In rare cases where probe installation on your cluster isn't possible and the kernel/probe +isn't pre-compiled, you may need to manually prepare the kernel module or eBPF probe with +[`driverkit`](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster) +and install it on each cluster node. + +By default, Falco is deployed with a limited set of rules. To add more rules, add +the following to `applications/falco/values.yaml` (you can get examples from +[Cloud Native Security Hub](https://securityhub.dev/)): + +```yaml +customRules: + file-integrity.yaml: |- + - rule: Detect New File + desc: detect new file created + condition: > + evt.type = chmod or evt.type = fchmod + output: > + File below a known directory opened for writing (user=%user.name + command=%proc.cmdline file=%fd.name parent=%proc.pname pcmdline=%proc.pcmdline gparent=%proc.aname[2]) + priority: ERROR + tags: [filesystem] + - rule: Detect New Directory + desc: detect new directory created + condition: > + mkdir + output: > + File below a known directory opened for writing (user=%user.name + command=%proc.cmdline file=%fd.name parent=%proc.pname pcmdline=%proc.pcmdline gparent=%proc.aname[2]) + priority: ERROR + tags: [filesystem] +``` + +By default, Falco only outputs security events to logs as JSON objects. To set it to output to an +[external API](https://falco.org/docs/alerts/#https-output-send-alerts-to-an-https-end-point) +or [application](https://falco.org/docs/alerts/#program-output), +add the following to `applications/falco/values.yaml`: + +```yaml +falco: + programOutput: + enabled: true + keepAlive: false + program: mail -s "Falco Notification" someone@example.com + + httpOutput: + enabled: true + url: http://some.url +``` + +You can check these logs with the following command: + +```shell +kubectl -n gitlab-managed-apps logs -l app=falco +``` + +Support for installing the Falco managed application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md new file mode 100644 index 00000000000..bf05f8f87d8 --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md @@ -0,0 +1,36 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install Fluentd with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install Fluentd you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/fluentd/helmfile.yaml +``` + +You can also review the default values set for this chart in the +[`values.yaml`](https://github.com/helm/charts/blob/master/stable/fluentd/values.yaml) file. + +You can customize the installation of Fluentd by defining +`applications/fluentd/values.yaml` file in your cluster management +project. Refer to the +[configuration chart](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) +for the current development release of Fluentd for all available configuration options. + +The configuration chart link points to the current development release, which +may differ from the version you have installed. To ensure compatibility, switch +to the specific branch or tag you are using. + +Support for installing the Fluentd managed application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md new file mode 100644 index 00000000000..4f17dbab11b --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -0,0 +1,31 @@ +--- +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 +--- + +# Install Ingress with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install Ingress you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/ingress/helmfile.yaml +``` + +Ingress is installed by default into the `gitlab-managed-apps` namespace +of your cluster. + +You can customize the installation of Ingress by updating the +`applications/ingress/values.yaml` file in your cluster +management project. Refer to the +[chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress) +for the available configuration options. + +Support for installing the Ingress managed application is provided by the GitLab Configure group. +If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), +and ping at least 2 people from the +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md new file mode 100644 index 00000000000..19e6c76d133 --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md @@ -0,0 +1,32 @@ +--- +stage: Monitor +group: Monitor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install Prometheus with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +[Prometheus](https://prometheus.io/docs/introduction/overview/) is an +open-source monitoring and alerting system for supervising your +deployed applications. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install Prometheus you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/prometheus/helmfile.yaml +``` + +You can customize the installation of Prometheus by updating the +`applications/prometheus/values.yaml` file in your cluster +management project. Refer to the +[Configuration section](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) +of the Prometheus chart's README for the available configuration options. + +Support for installing the Prometheus managed application is provided by the +GitLab APM group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md new file mode 100644 index 00000000000..56e01be68cb --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -0,0 +1,48 @@ +--- +stage: Verify +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 + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install GitLab Runner you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/gitlab-runner/helmfile.yaml +``` + +GitLab Runner is installed by default into the `gitlab-managed-apps` namespace of your cluster. + +For GitLab Runner to function, you _must_ specify the following in your +`applications/gitlab-runner/values.yaml.gotmpl` file: + +- `gitlabUrl`: The GitLab server full URL (for example, `https://gitlab.example.com`) + to register the Runner against. +- `runnerRegistrationToken`: The registration token for adding new runners to GitLab. + This must be [retrieved from your GitLab instance](../../../../../ci/runners/index.md). + +These values can be specified using [CI/CD variables](../../../../../ci/variables/index.md): + +- `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. +- `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` + +The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `GITLAB_RUNNER_TOKEN` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `runnerToken:` in `applications/gitlab-runner/values.yaml.gotmpl`. + +The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../../../../ci/variables/index.md#protect-a-cicd-variable) and [masked variable](../../../../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml.gotmpl` file. + +You can customize the installation of GitLab Runner by defining +`applications/gitlab-runner/values.yaml.gotmpl` file in your cluster +management project. Refer to the +[chart](https://gitlab.com/gitlab-org/charts/gitlab-runner) for the +available configuration options. + +Support for installing the GitLab Runner managed application is provided by the +GitLab Runner group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Runner group](https://about.gitlab.com/handbook/product/categories/#runner-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md new file mode 100644 index 00000000000..4d82fe389d2 --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md @@ -0,0 +1,76 @@ +--- +stage: Monitor +group: Monitor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install Sentry with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +The Sentry Helm chart [recommends](https://github.com/helm/charts/blob/f6e5784f265dd459c5a77430185d0302ed372665/stable/sentry/values.yaml#L284-L285) +at least 3 GB of available RAM for database migrations. + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install Sentry you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/sentry/helmfile.yaml +``` + +Sentry is installed by default into the `gitlab-managed-apps` namespace +of your cluster. + +You can customize the installation of Sentry by defining +`applications/sentry/values.yaml` file in your cluster +management project. Refer to the +[chart](https://github.com/helm/charts/tree/master/stable/sentry) +for the available configuration options. + +We recommend you pay close attention to the following configuration options: + +- `email`. Needed to invite users to your Sentry instance and to send error emails. +- `user`. Where you can set the login credentials for the default administrator user. +- `postgresql`. For a PostgreSQL password that can be used when running future updates. + +When upgrading, it's important to provide the existing PostgreSQL password (given +using the `postgresql.postgresqlPassword` key) to avoid authentication errors. +Read the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) +for more information. + +Here is an example configuration for Sentry: + +```yaml +# Admin user to create +user: + # Indicated to create the admin user or not, + # Default is true as the initial installation. + create: true + email: "<your email>" + password: "<your password>" + +email: + from_address: "<your from email>" + host: smtp + port: 25 + use_tls: false + user: "<your email username>" + password: "<your email password>" + enable_replies: false + +ingress: + enabled: true + hostname: "<sentry.example.com>" + +# Needs to be here between runs. +# See https://github.com/helm/charts/tree/master/stable/postgresql#upgrade for more info +postgresql: + postgresqlPassword: example-postgresql-password +``` + +Support for installing the Sentry managed application is provided by the +GitLab Health group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md new file mode 100644 index 00000000000..291321963d0 --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -0,0 +1,108 @@ +--- +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 +--- + +# Install Vault with a cluster management project + +> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. + +[HashiCorp Vault](https://www.vaultproject.io/) is a secrets management solution which +can be used to safely manage and store passwords, credentials, certificates, and more. A Vault +installation could be leveraged to provide a single secure data store for credentials +used in your applications, GitLab CI/CD jobs, and more. It could also serve as a way of +providing SSL/TLS certificates to systems and deployments in your infrastructure. Leveraging +Vault as a single source for all these credentials allows greater security by having +a single source of access, control, and auditability around all your sensitive +credentials and certificates. This feature requires giving GitLab the highest level of access and +control. Therefore, if GitLab is compromised, the security of this Vault instance is as well. To +avoid this security risk, GitLab recommends using your own HashiCorp Vault to leverage +[external secrets with CI](../../../../../ci/secrets/index.md). + +Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a +[management project template](../../../../../user/clusters/management_project_template.md), to install Vault you should +uncomment this line from your `helmfile.yaml`: + +```yaml + - path: applications/vault/helmfile.yaml +``` + +By default you receive a basic Vault setup with no scalable storage backend. This +is enough for simple testing and small-scale deployments, though has limits +to how much it can scale, and as it's a single instance deployment, upgrading the +Vault application causes downtime. + +To optimally use Vault in a production environment, it's ideal to have a good understanding +of the internals of Vault and how to configure it. This can be done by reading +the [Vault Configuration guide](../../../../../ci/secrets/#configure-your-vault-server), +the [Vault documentation](https://www.vaultproject.io/docs/internals) and +the Vault Helm chart [`values.yaml` file](https://github.com/hashicorp/vault-helm/blob/v0.3.3/values.yaml). + +At a minimum, most users set up: + +- A [seal](https://www.vaultproject.io/docs/configuration/seal) for extra encryption + of the main key. +- A [storage backend](https://www.vaultproject.io/docs/configuration/storage) that's + suitable for environment and storage security requirements. +- [HA Mode](https://www.vaultproject.io/docs/concepts/ha). +- The [Vault UI](https://www.vaultproject.io/docs/configuration/ui). + +The following is an example values file (`applications/vault/values.yaml`) +that configures Google Key Management Service for auto-unseal, using a Google Cloud Storage backend, enabling +the Vault UI, and enabling HA with 3 pod replicas. The `storage` and `seal` stanzas +below are examples and should be replaced with settings specific to your environment. + +```yaml +# Enable the Vault WebUI +ui: + enabled: true +server: + # Disable the built in data storage volume as it's not safe for High Availability mode + dataStorage: + enabled: false + # Enable High Availability Mode + ha: + enabled: true + # Configure Vault to listen on port 8200 for normal traffic and port 8201 for inter-cluster traffic + config: | + listener "tcp" { + tls_disable = 1 + address = "[::]:8200" + cluster_address = "[::]:8201" + } + # Configure Vault to store its data in a GCS Bucket backend + storage "gcs" { + path = "gcs://my-vault-storage/vault-bucket" + ha_enabled = "true" + } + # Configure Vault to unseal storage using a GKMS key + seal "gcpckms" { + project = "vault-helm-dev-246514" + region = "global" + key_ring = "vault-helm-unseal-kr" + crypto_key = "vault-helm-unseal-key" + } +``` + +After you have successfully installed Vault, you must +[initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) +and obtain the initial root token. You need access to your Kubernetes cluster that +Vault has been deployed into in order to do this. To initialize the Vault, get a +shell to one of the Vault pods running inside Kubernetes (typically this is done +by using the `kubectl` command line tool). After you have a shell into the pod, +run the `vault operator init` command: + +```shell +kubectl -n gitlab-managed-apps exec -it vault-0 sh +/ $ vault operator init +``` + +This should give you your unseal keys and initial root token. Make sure to note these down +and keep these safe, as they're required to unseal the Vault throughout its lifecycle. + +Support for installing the Vault managed application is provided by the +GitLab Release Management group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Release Management group](https://about.gitlab.com/handbook/product/categories/#release-management-group). diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md new file mode 100644 index 00000000000..5b44490f78d --- /dev/null +++ b/doc/user/infrastructure/iac/index.md @@ -0,0 +1,162 @@ +--- +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 +--- + +# Infrastructure as Code with Terraform and GitLab **(FREE)** + +## Motivation + +The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC) +workflows to tie into GitLab authentication and authorization. These features focus on +lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in +GitLab, and support Terraform best practices. + +## Quick Start + +Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration +for GitLab versions 14.0 and later: + +```yaml +include: + - template: Terraform.gitlab-ci.yml + +variables: + # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables + TF_STATE_NAME: default + TF_CACHE_KEY: default + # If your terraform files are in a subdirectory, set TF_ROOT accordingly + # TF_ROOT: terraform/production +``` + +This template includes some opinionated decisions, which you can override: + +- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). +- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as + the Terraform state storage backend. +- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml): + `init`, `validate`, `build`, and `deploy`. These stages + [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) + `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. + +This video from January 2021 walks you through all the GitLab Terraform integration features: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +## GitLab Managed Terraform state + +[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) +enable you to store the state file in a remote, shared store. GitLab uses the +[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) +to securely store the state files in local storage (the default) or +[the remote store of your choice](../../../administration/terraform_state.md). + +The GitLab managed Terraform state backend can store your Terraform state easily and +securely. It spares you from setting up additional remote resources like +Amazon S3 or Google Cloud Storage. Its features include: + +- Supporting encryption of the state file both in transit and at rest. +- Locking and unlocking state. +- Remote Terraform plan and apply execution. + +Read more on setting up and [using GitLab Managed Terraform states](../terraform_state.md) + +## Terraform module registry + +GitLab can be used as a [Terraform module registry](../../packages/terraform_module_registry/index.md) +to create and publish Terraform modules to a private registry specific to your +top-level namespace. + +## Terraform integration in Merge Requests + +Collaborating around Infrastructure as Code (IaC) changes requires both code changes +and expected infrastructure changes to be checked and approved. GitLab provides a +solution to help collaboration around Terraform code changes and their expected +effects using the Merge Request pages. This way users don't have to build custom +tools or rely on 3rd party solutions to streamline their IaC workflows. + +Read more on setting up and [using the merge request integrations](../mr_integration.md). + +## The GitLab Terraform provider + +WARNING: +The GitLab Terraform provider is released separately from GitLab. +We are working on migrating the GitLab Terraform provider for GitLab.com. + +You can use the [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) +to manage various aspects of GitLab using Terraform. The provider is an open source project, +owned by GitLab, where everyone can contribute. + +The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) +is available as part of the official Terraform provider documentations. + +## Create a new cluster through IaC + +Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). + +## Troubleshooting + +### `gitlab_group_share_group` resources not detected when subgroup state is refreshed + +The GitLab Terraform provider can fail to detect existing `gitlab_group_share_group` resources +due to the issue ["User with permissions cannot retrieve `share_with_groups` from the API"](https://gitlab.com/gitlab-org/gitlab/-/issues/328428). +This results in an error when running `terraform apply` because Terraform attempts to recreate an +existing resource. + +For example, consider the following group/subgroup configuration: + +```plaintext +parent-group +├── subgroup-A +└── subgroup-B +``` + +Where: + +- User `user-1` creates `parent-group`, `subgroup-A`, and `subgroup-B`. +- `subgroup-A` is shared with `subgroup-B`. +- User `terraform-user` is member of `parent-group` with inherited `owner` access to both subgroups. + +When the Terraform state is refreshed, the API query `GET /groups/:subgroup-A_id` issued by the provider does not return the +details of `subgroup-B` in the `shared_with_groups` array. This leads to the error. + +To workaround this issue, make sure to apply one of the following conditions: + +1. The `terraform-user` creates all subgroup resources. +1. Grant Maintainer or Owner role to the `terraform-user` user on `subgroup-B`. +1. The `terraform-user` inherited access to `subgroup-B` and `subgroup-B` contains at least one project. + +### Invalid CI/CD syntax error when using the "latest" base template + +On GitLab 14.2 and later, you might get a CI/CD syntax error when using the +`latest` Base Terraform template: + +```yaml +include: + - template: Terraform/Base.latest.gitlab-ci.yml + +my-Terraform-job: + extends: .init +``` + +The base template's [jobs were renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67719/) +with better Terraform-specific names. To resolve the syntax error, you can: + +- Use the stable `Terraform/Base.gitlab-ci.yml` template, which has not changed. +- Update your pipeline configuration to use the new job names in + `https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml`. + For example: + + ```yaml + include: + - template: Terraform/Base.latest.gitlab-ci.yml + + my-Terraform-job: + extends: .terraform:init # The updated name. + ``` diff --git a/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png b/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png Binary files differdeleted file mode 100644 index 7d619b6ad7e..00000000000 --- a/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png +++ /dev/null diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index bdaae4b8225..b2d75a22615 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -4,136 +4,11 @@ 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 --- -# Infrastructure as code with Terraform and GitLab **(FREE)** +# Infrastructure management **(FREE)** -## Motivation +GitLab provides you with great solutions to help you manage your +infrastructure: -The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC) -workflows to tie into GitLab authentication and authorization. These features focus on -lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in -GitLab, and support Terraform best practices. - -## Quick Start - -Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration -for GitLab versions 14.0 and later: - -```yaml -include: - - template: Terraform.gitlab-ci.yml - -variables: - # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables - TF_STATE_NAME: default - TF_CACHE_KEY: default - # If your terraform files are in a subdirectory, set TF_ROOT accordingly - # TF_ROOT: terraform/production -``` - -This template includes some opinionated decisions, which you can override: - -- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). -- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as - the Terraform state storage backend. -- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml): - `init`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) - `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. - -This video from January 2021 walks you through all the GitLab Terraform integration features: - -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -## GitLab Managed Terraform state - -[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) -enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) -to securely store the state files in local storage (the default) or -[the remote store of your choice](../../administration/terraform_state.md). - -The GitLab managed Terraform state backend can store your Terraform state easily and -securely. It spares you from setting up additional remote resources like -Amazon S3 or Google Cloud Storage. Its features include: - -- Supporting encryption of the state file both in transit and at rest. -- Locking and unlocking state. -- Remote Terraform plan and apply execution. - -Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md) - -WARNING: -Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. -Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan -includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly -recommends encrypting plan output or modifying the project visibility settings. - -## Terraform module registry - -GitLab can be used as a [Terraform module registry](../packages/terraform_module_registry/index.md) -to create and publish Terraform modules to a private registry specific to your -top-level namespace. - -## Terraform integration in Merge Requests - -Collaborating around Infrastructure as Code (IaC) changes requires both code changes -and expected infrastructure changes to be checked and approved. GitLab provides a -solution to help collaboration around Terraform code changes and their expected -effects using the Merge Request pages. This way users don't have to build custom -tools or rely on 3rd party solutions to streamline their IaC workflows. - -Read more on setting up and [using the merge request integrations](mr_integration.md). - -## The GitLab Terraform provider - -WARNING: -The GitLab Terraform provider is released separately from GitLab. -We are working on migrating the GitLab Terraform provider for GitLab.com. - -You can use the [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) -to manage various aspects of GitLab using Terraform. The provider is an open source project, -owned by GitLab, where everyone can contribute. - -The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) -is available as part of the official Terraform provider documentations. - -## Create a new cluster through IaC - -Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](clusters/connect/new_gke_cluster.md). - -## Troubleshooting - -### `gitlab_group_share_group` resources not detected when subgroup state is refreshed - -The GitLab Terraform provider can fail to detect existing `gitlab_group_share_group` resources -due to the issue ["User with permissions cannot retrieve `share_with_groups` from the API"](https://gitlab.com/gitlab-org/gitlab/-/issues/328428). -This results in an error when running `terraform apply` because Terraform attempts to recreate an -existing resource. - -For example, consider the following group/subgroup configuration: - -```plaintext -parent-group -├── subgroup-A -└── subgroup-B -``` - -Where: - -- User `user-1` creates `parent-group`, `subgroup-A`, and `subgroup-B`. -- `subgroup-A` is shared with `subgroup-B`. -- User `terraform-user` is member of `parent-group` with inherited `owner` access to both subgroups. - -When the Terraform state is refreshed, the API query `GET /groups/:subgroup-A_id` issued by the provider does not return the -details of `subgroup-B` in the `shared_with_groups` array. This leads to the error. - -To workaround this issue, make sure to apply one of the following conditions: - -1. The `terraform-user` creates all subgroup resources. -1. Grant Maintainer or Owner role to the `terraform-user` user on `subgroup-B`. -1. The `terraform-user` inherited access to `subgroup-B` and `subgroup-B` contains at least one project. +- [Infrastructure as Code and GitOps](iac/index.md) +- [Kubernetes clusters](../project/clusters/index.md) +- [Runbooks](../project/clusters/runbooks/index.md) diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 66e00bab6ce..29bf218b109 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -15,12 +15,17 @@ you can expose details from `terraform plan` runs directly into a merge request enabling you to see statistics about the resources that Terraform creates, modifies, or destroys. -## Setup +WARNING: +Like any other job artifact, Terraform Plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform Plan +includes sensitive data such as passwords, access tokens, or certificates, we strongly +recommend encrypting plan output or modifying the project visibility settings. -NOTE: -GitLab ships with a [pre-built CI template](index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. +## Configure Terraform report artifacts -To manually configure a GitLab Terraform Report artifact requires the following steps: +GitLab ships with a [pre-built CI template](iac/index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. + +To manually configure a GitLab Terraform Report artifact: 1. For simplicity, let's define a few reusable variables to allow us to refer to these files multiple times: diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index 57db2b47de4..179f9677b96 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -14,6 +14,11 @@ enable you to store the state file in a remote, shared store. GitLab uses the to securely store the state files in local storage (the default) or [the remote store of your choice](../../administration/terraform_state.md). +WARNING: +Using local storage (the default) on clustered deployments of GitLab will result in +a split state across nodes, making subsequent executions of Terraform inconsistent. +You are highly advised to use a remote storage in that case. + The GitLab managed Terraform state backend can store your Terraform state easily and securely, and spares you from setting up additional remote resources like Amazon S3 or Google Cloud Storage. Its features include: @@ -83,6 +88,14 @@ local machine, this is a simple way to get started: -backend-config="retry_wait_min=5" ``` +If you already have a GitLab-managed Terraform state, you can use the `terraform init` command +with the prepopulated parameters values: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Infrastructure > Terraform**. +1. Next to the environment you want to use, select the [Actions menu](#managing-state-files) + **{ellipsis_v}** and select **Copy Terraform init command**. + You can now run `terraform plan` and `terraform apply` as you normally would. ### Get started using GitLab CI @@ -222,7 +235,7 @@ An example setup is shown below: ```plaintext example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> example_username=<GitLab username> - example_access_token=<GitLab Personal Acceess Token> + example_access_token=<GitLab Personal Access Token> ``` 1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): @@ -362,10 +375,8 @@ contains these fields: state file is locked. - **Pipeline**: A link to the most recent pipeline and its status. - **Details**: Information about when the state file was created or changed. -- **Actions**: Actions you can take on the state file, including downloading, - locking, unlocking, or [removing](#remove-a-state-file) the state file and versions: - -  +- **Actions**: Actions you can take on the state file, including copying the `terraform init` command, + downloading, locking, unlocking, or [removing](#remove-a-state-file) the state file and versions. NOTE: Additional improvements to the diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 24fabbc5a42..5f51286cf7f 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -28,7 +28,7 @@ GitLab tries to match clusters in the following order: - Instance-level clusters. To be selected, the cluster must be enabled and -match the [environment selector](../../../ci/environments/index.md#scoping-environments-with-specs). +match the [environment selector](../../../ci/environments/index.md#scope-environments-with-specs). ## Cluster environments **(PREMIUM)** diff --git a/doc/user/markdown.md b/doc/user/markdown.md index fc278007463..4149307c45a 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -410,7 +410,7 @@ To create a task list, follow the format of an ordered or unordered list: A table of contents is an unordered list that links to subheadings in the document. To add a table of contents to a Markdown file, wiki page, issue request, or merge request -description, add the `[[_TOC_]]` tag on its own line. +description, add either the `[[_TOC_]]` or `[TOC]` tag on its own line. NOTE: You can add a table of contents to issues and merge requests, but you can't add one @@ -511,7 +511,7 @@ This example links to `<wiki_root>/miscellaneous.md`: GitLab Flavored Markdown renders GitLab-specific references. For example, you can reference an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns -that reference into a link so you can navigate between them. All references to projects should use the +that reference into a link so you can navigate between them. All references to projects should use the **project slug** rather than the project name. Additionally, GitLab Flavored Markdown recognizes certain cross-project references and also has a shorthand diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index b6eb2975374..2787aefdeca 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -63,7 +63,7 @@ a group's namespace, rather than a user's namespace. Composer packages git commit -m 'Composer package test' git tag v1.0.0 git remote add origin git@gitlab.example.com:<namespace>/<project-name>.git - git push --set-upstream origin master + git push --set-upstream origin main git push origin v1.0.0 ``` diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index c6cc7e7905a..d3e913edfda 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -210,13 +210,6 @@ conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_acc Now when you run commands with `--remote=gitlab`, your username and password are included in the requests. -Alternatively, you can explicitly include your credentials in any given command. -For example: - -```shell -CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> conan upload Hello/0.1@mycompany/beta --all --remote=gitlab -``` - NOTE: Because your authentication with GitLab expires on a regular basis, you may occasionally need to re-enter your personal access token. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index eecc17fd60d..18b86c4a357 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -236,7 +236,7 @@ combining the two to save us some typing in the `script` section. Here's a more elaborate example that splits up the tasks into 4 pipeline stages, including two tests that run in parallel. The `build` is stored in the container registry and used by subsequent stages, downloading the image -when needed. Changes to `master` also get tagged as `latest` and deployed using +when needed. Changes to `main` also get tagged as `latest` and deployed using an application-specific deploy script: ```yaml @@ -285,14 +285,14 @@ release-image: - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE - docker push $CONTAINER_RELEASE_IMAGE only: - - master + - main deploy: stage: deploy script: - ./deploy.sh only: - - master + - main ``` NOTE: @@ -436,7 +436,7 @@ build_image: only: - branches except: - - master + - main delete_image: image: docker:19.03.12 @@ -457,7 +457,7 @@ delete_image: only: - branches except: - - master + - main ``` NOTE: @@ -488,8 +488,8 @@ To delete the underlying layers and images that aren't associated with any tags, Cleanup policies can be run on all projects, with these exceptions: - For GitLab.com, the project must have been created after 2020-02-22. - Support for projects created earlier - [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). + Support for projects created earlier is tracked + [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). - For self-managed GitLab instances, the project must have been created in GitLab 12.8 or later. However, an administrator can enable the cleanup policy for all projects (even those created before 12.8) in @@ -605,10 +605,10 @@ Here are examples of regex patterns you may want to use: v.+ ``` -- Match only the tag named `master`: +- Match only the tag named `main`: ```plaintext - master + main ``` - Match tags that are either named or start with `release`: @@ -617,10 +617,10 @@ Here are examples of regex patterns you may want to use: release.* ``` -- Match tags that either start with `v`, are named `master`, or begin with `release`: +- Match tags that either start with `v`, are named `main`, or begin with `release`: ```plaintext - (?:v.+|master|release.*) + (?:v.+|main|release.*) ``` ### Set cleanup limits to conserve resources @@ -675,11 +675,11 @@ You can set, update, and disable the cleanup policies using the GitLab API. Examples: -- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: +- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `main` and the policy is enabled: ```shell curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" \ - --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' \ + --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-main"}}' \ "https://gitlab.example.com/api/v4/projects/2" ``` @@ -745,6 +745,47 @@ You can, however, remove the Container Registry for a project: The **Packages & Registries > Container Registry** entry is removed from the project's sidebar. +## Change visibility of the Container Registry + +By default, the Container Registry is visible to everyone with access to the project. +You can, however, change the visibility of the Container Registry for a project. + +See the [Container Registry visibility permissions](#container-registry-visibility-permissions) +for more details about the permissions that this setting grants to users. + +1. Go to your project's **Settings > General** page. +1. Expand the section **Visibility, project features, permissions**. +1. Under **Container Registry**, select an option from the dropdown: + + - **Everyone With Access** (Default): The Container Registry is visible to everyone with access + to the project. If the project is public, the Container Registry is also public. If the project + is internal or private, the Container Registry is also internal or private. + + - **Only Project Members**: The Container Registry is visible only to project members with + Reporter role or higher. This is similar to the behavior of a private project with Container + Registry visibility set to **Everyone With Access**. + +1. Select **Save changes**. + +## Container Registry visibility permissions + +The ability to view the Container Registry and pull images is controlled by the Container Registry's +visibility permissions. You can change this through the [visibility setting on the UI](#change-visibility-of-the-container-registry) +or the [API](../../../api/container_registry.md#change-the-visibility-of-the-container-registry). +[Other permissions](../../permissions.md) +such as updating the Container Registry, pushing or deleting images, and so on are not affected by +this setting. However, disabling the Container Registry disables all Container Registry operations. + +| | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | +| -------------------- | --------------------- | --------- | ----- | ------------------------------------------ | +| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes | +| Public 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 | +| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes | +| Internal 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 | +| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| 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 diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 59213ccb1a0..789902c03e3 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -6,7 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Debian packages in the Package Registry **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) in GitLab 14.1. +> - Debian API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42670) in GitLab 13.5. +> - Debian group API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66188) in GitLab 14.2. +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. WARNING: The Debian package registry for GitLab is under development and isn't ready for production use due to @@ -20,7 +22,7 @@ Project and Group packages are supported. For documentation of the specific API endpoints that Debian package manager clients use, see the [Debian API documentation](../../../api/packages/debian.md). -## Enable Debian repository feature +## Enable the Debian API **(FREE SELF)** Debian repository support is still a work in progress. It's gated behind a feature flag that's **disabled by default**. @@ -39,10 +41,35 @@ To disable it: Feature.disable(:debian_packages) ``` +## Enable the Debian group API **(FREE SELF)** + +The Debian group repository is also behind a second feature flag that is disabled by default. + +To enable it: + +```ruby +Feature.enable(:debian_group_packages) +``` + +To disable it: + +```ruby +Feature.disable(:debian_group_packages) +``` + ## Build a Debian package Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian.org/Packaging). +## Authenticate to the Package Registry + +To create a distribution, publish a package, or install a private package, you need one of the +following: + +- [Personal access token](../../../api/index.md#personalproject-access-tokens) +- [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token) +- [Deploy token](../../project/deploy_tokens/index.md) + ## Create a Distribution On the project-level, Debian packages are published using *Debian Distributions*. To publish @@ -98,7 +125,7 @@ To upload these files, you can use `dput-ng >= 1.32` (Debian bullseye): cat <<EOF > dput.cf [gitlab] method = https -fqdn = <login>:<your_access_token>@gitlab.example.com +fqdn = <username>:<your_access_token>@gitlab.example.com incoming = /api/v4/projects/<project_id>/packages/debian EOF @@ -107,5 +134,27 @@ dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes ## Install a package -The Debian package registry for GitLab is under development, and isn't ready for production use. You -cannot install packages from the registry. However, you can download files directly from the UI. +To install a package: + +1. Configure the repository: + + If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt config: + + ```shell + echo 'machine gitlab.example.com login <username> password <your_access_token>' \ + | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf + ``` + + Add your project as a source: + + ```shell + echo 'deb [trusted=yes] https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian <codename> <component1> <component2>' \ + | sudo tee /etc/apt/sources.list.d/gitlab_project.list + sudo apt-get update + ``` + +1. Install the package: + + ```shell + sudo apt-get -y install -t <codename> <package-name> + ``` diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index e2957aff756..c76b0a6810f 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -20,7 +20,7 @@ upstream image from a registry, acting as a pull-through cache. ## Prerequisites -The Dependency Proxy must be [enabled by an administrator](../../../administration/packages/dependency_proxy.md). +- The Dependency Proxy is enabled by default but can be [turned off by an administrator](../../../administration/packages/dependency_proxy.md). ### Supported images and packages @@ -33,11 +33,6 @@ The following images and packages are supported. For a list of planned additions, view the [direction page](https://about.gitlab.com/direction/package/#dependency-proxy). -## Enable the Dependency Proxy - -The Dependency Proxy is disabled by default. -[Learn how an administrator can enable it](../../../administration/packages/dependency_proxy.md). - ## View the Dependency Proxy To view the Dependency Proxy: @@ -68,11 +63,6 @@ The requirement to authenticate is a breaking change added in 13.7. An [administ disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication) if it has disrupted your existing Dependency Proxy usage. -WARNING: -If [SSO enforcement](../../group/saml_sso/index.md#sso-enforcement) -is enabled for your Group, requests to the dependency proxy will fail. This bug is being tracked in -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/294018). - Because the Dependency Proxy is storing Docker images in a space associated with your group, you must authenticate against the Dependency Proxy. @@ -89,6 +79,13 @@ You can authenticate using: - Your GitLab username and password. - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. +- A [group deploy token](../../../user/project/deploy_tokens/index.md#group-deploy-token) with the scope set to `read_registry` and `write_registry`. + +#### SAML SSO + +When [SSO enforcement](../../group/saml_sso/index.md#sso-enforcement) +is enabled, users must be signed-in through SSO before they can pull images through the Dependency +Proxy. #### Authenticate within CI/CD @@ -123,7 +120,7 @@ Proxy manually without including the port: docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest ``` -You can also use [custom CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) to store and access your personal access token or other valid credentials. +You can also use [custom CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) to store and access your personal access token or deploy token. ### Store a Docker image in Dependency Proxy cache @@ -253,6 +250,10 @@ hub_docker_quota_check: TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 ``` +## Use the NPM Dependency Proxy for NPM packages + +For information on this, see [Dependency Proxy](../npm_registry/#dependency-proxy). + ## Troubleshooting ### Dependency Proxy Connection Failure diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index cb5258981be..aa6373b66cb 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -33,8 +33,6 @@ a [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or a [deploy t When you publish a package file, if the package does not exist, it is created. -If a package with the same name, version, and filename already exists, it is also created. It does not overwrite the existing package. - Prerequisites: - You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. @@ -69,6 +67,30 @@ Example response: } ``` +### Publishing a package with the same name or version + +When you publish a package with the same name and version as an existing package, the new package +files are added to the existing package. You can still use the UI or API to access and view the +existing package's older files. To delete these older package revisions, consider using the Packages +API or the UI. + +#### Do not allow duplicate Generic packages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293755) in GitLab Free 13.12. + +To prevent users from publishing duplicate generic packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) +or the UI. + +In the UI: + +1. For your group, go to **Settings > Packages & Registries**. +1. Expand the **Package Registry** section. +1. Turn on the **Reject duplicates** toggle. +1. Optional. To allow some duplicate packages, in the **Exceptions** box enter a regex pattern that + matches the names and/or versions of packages to allow. + +Your changes are automatically saved. + ## Download package file Download a package file. @@ -131,6 +153,18 @@ download: - 'wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt' ``` +When using a Windows runner with PowerShell, you must use `Invoke-WebRequest` or `Invoke-RestMethod` +instead of `curl` in the `upload` and `download` stages. + +For example: + +```yaml +upload: + stage: upload + script: + - 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. diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 26d8bf76cd6..f98fc352ab5 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -8,10 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. -WARNING: -The Helm package registry for GitLab is under development and isn't ready for production use due to -limited functionality. - Publish Helm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -20,7 +16,10 @@ clients use, see the [Helm API documentation](../../../api/packages/helm.md). ## Build a Helm package -Creating a Helm package is documented [in the Helm documentation](https://helm.sh/docs/intro/using_helm/#creating-your-own-charts). +Read more in the Helm documentation about these topics: + +- [Create your own Helm charts](https://helm.sh/docs/intro/using_helm/#creating-your-own-charts) +- [Package a Helm chart into a chart archive](https://helm.sh/docs/helm/helm_package/#helm-package) ## Authenticate to the Helm repository @@ -32,6 +31,10 @@ To authenticate to the Helm repository, you need either: ## Publish a package +NOTE: +You can publish Helm charts with duplicate names or versions. If duplicates exist, GitLab always +returns the chart with the latest version. + Once built, a chart can be uploaded to the `stable` channel with `curl` or `helm-push`: - With `curl`: @@ -87,3 +90,12 @@ helm repo update To update the Helm client with the most currently available charts. See [Using Helm](https://helm.sh/docs/intro/using_helm/) for more information. + +## Troubleshooting + +### The chart is not visible in the Package Registry after uploading + +Check the [Sidekiq log](../../../administration/logs.md#sidekiqlog) +for any related errors. If you see `Validation failed: Version is invalid`, it means that the +version in your `Chart.yaml` file does not follow [Helm Chart versioning specifications](https://helm.sh/docs/topics/charts/#charts-and-versioning). +To fix the error, use the correct version syntax and upload the chart again. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 70b9c28da76..17571047353 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -711,7 +711,7 @@ you can configure GitLab CI/CD to build new packages automatically. ### Create Maven packages with GitLab CI/CD by using Maven -You can create a new package each time the `master` branch is updated. +You can create a new package each time the `main` branch is updated. 1. Create a `ci_settings.xml` file that serves as Maven's `settings.xml` file. @@ -768,7 +768,7 @@ You can create a new package each time the `master` branch is updated. script: - 'mvn deploy -s ci_settings.xml' only: - - master + - main ``` 1. Push those files to your repository. @@ -781,7 +781,7 @@ user's home location. In this example: ### Create Maven packages with GitLab CI/CD by using Gradle -You can create a package each time the `master` branch +You can create a package each time the `main` branch is updated. 1. Authenticate with [a CI job token in Gradle](#authenticate-with-a-ci-job-token-in-gradle). @@ -794,7 +794,7 @@ is updated. script: - 'gradle publish' only: - - master + - main ``` 1. Commit files to your repository. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 1e5c294689b..fe7e6a0ea46 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -353,6 +353,13 @@ In this configuration: You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. +This rule has a different impact depending on the package name: + +- For packages following the [naming convention](#package-naming-convention), you can't publish a + package with a duplicate name and version to the root namespace. +- For packages not following the [naming convention](#package-naming-convention), you can't publish + a package with a duplicate name and version to the project you target with the upload. + This aligns with npmjs.org's behavior. However, npmjs.org does not ever let you publish the same version more than once, even if it has been deleted. @@ -594,3 +601,8 @@ The GitLab npm repository supports the following commands for the npm CLI (`npm` - `npm view`: Show package metadata. - `yarn add`: Install an npm package. - `yarn update`: Update your dependencies. + +## Dependency Proxy + +The NPM Dependency Proxy for NPM packages isn't available. For more information, see +[this epic](https://gitlab.com/groups/gitlab-org/-/epics/3608). diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 46cfd763668..40e8b74c2b6 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -322,7 +322,7 @@ If you're using NuGet with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. -This example shows how to create a new package each time the `master` branch is +This example shows how to create a new package each time the `main` branch is updated: 1. Add a `deploy` job to your `.gitlab-ci.yml` file: @@ -340,7 +340,7 @@ updated: - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text - dotnet nuget push "bin/Release/*.nupkg" --source gitlab only: - - master + - main ``` 1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. @@ -423,6 +423,21 @@ CLI (`dotnet`): - `nuget install`: Install a package from the registry. - `dotnet add`: Install a package from the registry. +## Example project + +For an example, see the Guided Exploration project +[Utterly Automated Software and Artifact Versioning with GitVersion](https://gitlab.com/guided-explorations/devops-patterns/utterly-automated-versioning). +This project: + +- Generates NuGet packages by the `msbuild` method. +- Generates NuGet packages by the `nuget.exe` method. +- Uses GitLab releases and `release-cli` in connection with NuGet packaging. +- Uses a tool called [GitVersion](https://gitversion.net/) + to automatically determine and increment versions for the NuGet package in complex repositories. + +You can copy this example project to your own group or instance for testing. See the project page +for more details on what other GitLab CI patterns are demonstrated. + ## Troubleshooting To improve performance, NuGet caches files related to a package. If you encounter issues, clear the diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 30d61770094..2d54cfc5f7d 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -181,7 +181,9 @@ username = <your_personal_access_token_name> password = <your_personal_access_token> ``` -- Your project ID is on your project's home page. +The `<project_id>` is either the project's +[URL-encoded](../../../api/index.md#namespaced-path-encoding) +path (for example, `group%2Fproject`), or the project's ID (for example `42`). ### Authenticate with a deploy token @@ -198,7 +200,9 @@ username = <deploy token username> password = <deploy token> ``` -Your project ID is on your project's home page. +The `<project_id>` is either the project's +[URL-encoded](../../../api/index.md#namespaced-path-encoding) +path (for example, `group%2Fproject`), or the project's ID (for example `42`). ### Authenticate with a CI job token @@ -324,6 +328,11 @@ more than once, a `400 Bad Request` error occurs. ## Install a PyPI package +In [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/233413), +when a PyPI package is not found in the Package Registry, the request is forwarded to [pypi.org](https://pypi.org/). + +Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). + ### Install from the project level To install the latest version of a package, use the following command: @@ -335,7 +344,8 @@ pip install --index-url https://<personal_access_token_name>:<personal_access_to - `<package_name>` is the package name. - `<personal_access_token_name>` is a personal access token name with the `read_api` scope. - `<personal_access_token>` is a personal access token with the `read_api` scope. -- `<project_id>` is the project ID. +- `<project_id>` is either the project's [URL-encoded](../../../api/index.md#namespaced-path-encoding) + path (for example, `group%2Fproject`), or the project's ID (for example `42`). In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using `--extra-index-url` makes you vulnerable to dependency confusion attacks because it checks the PyPi diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 1365f401506..e3b9563a143 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -35,8 +35,8 @@ PUT /projects/:id/packages/terraform/modules/:module_name/:module_system/:module | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | | `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 (`-`). -| `module_system` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). +| `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_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. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 0c3428ee7ee..81681ec1303 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -33,8 +33,7 @@ usernames. A GitLab administrator can configure the GitLab instance to ## Project members permissions -NOTE: -In GitLab 11.0, the Master role was renamed to Maintainer. +> The Master role was renamed to Maintainer in GitLab 11.0. The Owner role is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, or an instance administrator, who receives all permissions. @@ -42,160 +41,163 @@ For more information, see [projects members documentation](project/members/index The following table lists project permissions available for each role: -| Action | Guest | Reporter | Developer |Maintainer| Owner | -|---------------------------------------------------|---------|------------|-------------|----------|--------| -| Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +<!-- Keep this table sorted: first, by minimum role, then alphabetically. --> + +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|-------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|-------| +| [Analytics](analytics/index.md):<br>View issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | +| [CI/CD](../ci/README.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>View list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>View [environments](../ci/environments/index.md) | | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Cancel and retry jobs | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Create new [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Stop [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Manage CI/CD variables | | | | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Manage job triggers | | | | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Manage runners | | | | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals) | | | | ✓ | ✓ | +| [CI/CD](../ci/README.md):<br>Delete pipelines | | | | | ✓ | +| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Assign | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Move issues (*15*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Approve (*9*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Create | | | ✓ | ✓ | ✓ | +| [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 | | | | | ✓ | +| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | +| [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View 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 statistics | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*11*) | ✓ | ✓ | +| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (14) | ✓ | +| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*12*) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*) | +| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | +| [Projects](project/index.md):<br>Archive project | | | | | ✓ | +| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | +| [Projects](project/index.md):<br>Delete project | | | | | ✓ | +| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | +| [Projects](project/index.md):<br>Rename project | | | | | ✓ | +| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | | View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | | View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| View Dependency list **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| View [Threats list](application_security/threat_monitoring/#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Create and run [on-demand DAST scans](application_security/dast/#on-demand-scans) | | | ✓ | ✓ | ✓ | -| View licenses in Dependency list **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | -| View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| See a list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| See a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| See a job with [debug logging](../ci/variables/index.md#debug-logging) | | | ✓ | ✓ | ✓ | -| Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create new issue | ✓ | ✓ | ✓ | ✓ | ✓ | -| See linked issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | -| View requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Merge Request analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | -| Assign issues | | ✓ | ✓ | ✓ | ✓ | -| Assign reviewers | | ✓ | ✓ | ✓ | ✓ | -| Label issues | | ✓ | ✓ | ✓ | ✓ | -| Set issue weight | | ✓ | ✓ | ✓ | ✓ | -| [Set issue estimate and record time spent](project/time_tracking.md) | | ✓ | ✓ | ✓ | ✓ | -| View a time tracking report | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Lock issue threads | | ✓ | ✓ | ✓ | ✓ | -| Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | -| Manage linked issues | | ✓ | ✓ | ✓ | ✓ | -| Manage labels | | ✓ | ✓ | ✓ | ✓ | -| Create code snippets | | ✓ | ✓ | ✓ | ✓ | -| See a commit status | | ✓ | ✓ | ✓ | ✓ | -| See a container registry | | ✓ | ✓ | ✓ | ✓ | -| See environments | | ✓ | ✓ | ✓ | ✓ | -| See [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | -| View CI/CD analytics | | ✓ | ✓ | ✓ | ✓ | -| View Code Review analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| View Repository analytics | | ✓ | ✓ | ✓ | ✓ | -| View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | -| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| Archive [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Archive/reopen requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| Create new [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Import/export requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Create new [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Archive [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Pull [packages](packages/index.md) | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | -| View project statistics | | ✓ | ✓ | ✓ | ✓ | -| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | -| Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | -| Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | -| Create/edit/delete [releases](project/releases/index.md)| | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | -| Manage merge approval rules (project settings) | | | | ✓ | ✓ | -| Create new merge request | | | ✓ | ✓ | ✓ | +| See a commit status | | ✓ | ✓ | ✓ | ✓ | +| View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | +| View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| Add tags | | | ✓ | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | -| Push to non-protected branches | | | ✓ | ✓ | ✓ | +| Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | +| Create/edit/delete [releases](project/releases/index.md)| | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | +| Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | +| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | Force push to non-protected branches | | | ✓ | ✓ | ✓ | -| Remove non-protected branches | | | ✓ | ✓ | ✓ | -| Assign merge requests | | | ✓ | ✓ | ✓ | -| Label merge requests | | | ✓ | ✓ | ✓ | -| Lock merge request threads | | | ✓ | ✓ | ✓ | -| Approve merge requests (*9*) | | | ✓ | ✓ | ✓ | -| Manage/Accept merge requests | | | ✓ | ✓ | ✓ | -| Create new environments | | | ✓ | ✓ | ✓ | -| Stop environments | | | ✓ | ✓ | ✓ | -| Enable Review Apps | | | ✓ | ✓ | ✓ | -| View Pods logs | | | ✓ | ✓ | ✓ | +| Manage Feature Flags **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | +| Push to non-protected branches | | | ✓ | ✓ | ✓ | | Read Terraform state | | | ✓ | ✓ | ✓ | -| Add tags | | | ✓ | ✓ | ✓ | -| Cancel and retry jobs | | | ✓ | ✓ | ✓ | -| Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | -| Update a container registry | | | ✓ | ✓ | ✓ | | Remove a container registry image | | | ✓ | ✓ | ✓ | -| Create/edit/delete project milestones | | | ✓ | ✓ | ✓ | -| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| View vulnerability findings in Dependency list **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Revert vulnerability to detected state **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Apply code change suggestions | | | ✓ | ✓ | ✓ | -| Create and edit wiki pages | | | ✓ | ✓ | ✓ | +| Remove non-protected branches | | | ✓ | ✓ | ✓ | | Rewrite/remove Git tags | | | ✓ | ✓ | ✓ | -| Manage Feature Flags **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | +| Update a container registry | | | ✓ | ✓ | ✓ | +| View Pods logs | | | ✓ | ✓ | ✓ | +| Configure project hooks | | | | ✓ | ✓ | | Delete [packages](packages/index.md) | | | | ✓ | ✓ | -| Request a CVE ID **(FREE SAAS)** | | | | ✓ | ✓ | -| Use environment terminals | | | | ✓ | ✓ | -| Run Web IDE's Interactive Web Terminals **(ULTIMATE SELF)** | | | | ✓ | ✓ | -| Add new team members | | | | ✓ | ✓ | | Enable/disable branch protection | | | | ✓ | ✓ | -| Push to protected branches | | | | ✓ | ✓ | -| Turn on/off protected branch push for developers | | | | ✓ | ✓ | | Enable/disable tag protections | | | | ✓ | ✓ | -| Edit project settings | | | | ✓ | ✓ | -| Edit project badges | | | | ✓ | ✓ | -| Export project | | | | ✓ | ✓ | -| Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*)| -| Add deploy keys to project | | | | ✓ | ✓ | -| Configure project hooks | | | | ✓ | ✓ | -| Manage runners | | | | ✓ | ✓ | -| Manage job triggers | | | | ✓ | ✓ | -| Manage CI/CD variables | | | | ✓ | ✓ | +| Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | +| Manage clusters | | | | ✓ | ✓ | +| Manage Error Tracking | | | | ✓ | ✓ | | Manage GitLab Pages | | | | ✓ | ✓ | | Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | -| Remove GitLab Pages | | | | ✓ | ✓ | -| Manage clusters | | | | ✓ | ✓ | -| Manage Project Operations | | | | ✓ | ✓ | -| Manage Terraform state | | | | ✓ | ✓ | | Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | -| Manage security policy **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Create or assign security policy project **(ULTIMATE)** | | | | | ✓ | -| Edit comments (posted by any user) | | | | ✓ | ✓ | -| Reposition comments on images (posted by any user)|✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | -| Manage Error Tracking | | | | ✓ | ✓ | -| Delete wiki pages | | | | ✓ | ✓ | -| View project Audit Events | | | ✓ (*11*) | ✓ | ✓ | -| Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*12*) | | | | ✓ | ✓ | -| View 2FA status of members | | | | ✓ | ✓ | -| Switch visibility level | | | | | ✓ | -| Transfer project to another namespace | | | | | ✓ | -| Rename project | | | | | ✓ | +| Manage Terraform state | | | | ✓ | ✓ | +| Push to protected branches | | | | ✓ | ✓ | +| Remove GitLab Pages | | | | ✓ | ✓ | +| Turn on/off protected branch push for developers | | | | ✓ | ✓ | | Remove fork relationship | | | | | ✓ | -| Delete project | | | | | ✓ | -| Archive project | | | | | ✓ | -| Delete issues | | | | | ✓ | -| Delete pipelines | | | | | ✓ | -| Delete merge request | | | | | ✓ | -| Disable notification emails | | | | | ✓ | -| Administer project compliance frameworks | | | | | ✓ | | Force push to protected branches (*4*) | | | | | | | Remove protected branches (*4*) | | | | | | 1. Guest users are able to perform this action on public and internal projects, but not private projects. This doesn't apply to [external users](#external-users) where explicit access must be given even if the project is internal. -1. Guest users can only view the confidential issues they created themselves. +1. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves. 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. 1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 1. If the [branch is protected](project/protected_branches.md), this depends on the access Developers and Maintainers are given. @@ -209,6 +211,11 @@ The following table lists project permissions available for each role: 1. Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). 1. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access Developers and Maintainers are given. +1. A Maintainer can't change project features visibility level if + [project visibility](../public_access/public_access.md) is set to private. +1. Attached design files are moved together with the issue even if the user doesn't have the + Developer role. +1. Guest users can set metadata (for example, labels, assignees, or milestones) when creating an issue. ## Project features permissions @@ -248,10 +255,15 @@ Read through the documentation on [permissions for File Locking](project/file_lo ### Confidential Issues permissions -Confidential issues can be accessed by users with reporter and higher permission levels, +[Confidential issues](project/issues/confidential_issues.md) can be accessed by users with reporter and higher permission levels, as well as by guest users that create a confidential issue. To learn more, read through the documentation on [permissions and access to confidential issues](project/issues/confidential_issues.md#permissions-and-access-to-confidential-issues). +### Container Registry visibility permissions + +Find the visibility permissions for the Container Registry, as described in the +[related documentation](packages/container_registry/index.md#container-registry-visibility-permissions). + ## Group members permissions NOTE: @@ -262,6 +274,8 @@ the group. 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 | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -287,6 +301,8 @@ The following table lists group permissions available for each role: | Create/edit/delete iterations | | | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | +| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | +| Purge the dependency proxy for a group | | | | | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | @@ -314,7 +330,7 @@ The following table lists group permissions available for each role: Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) 1. Introduced in GitLab 12.2. 1. Default project creation role can be changed at: - - The [instance level](admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection). + - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - The [group level](group/index.md#specify-who-can-add-projects-to-a-group). 1. Does not apply to subgroups. 1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index c4ab54736bc..f6af373e295 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -70,7 +70,7 @@ 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#blocking-a-user) +[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) diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d49f4ab0c16..2c76b46249e 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -5,7 +5,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# User account +# User account **(FREE)** Each GitLab account has a user profile, which contains information about you and your GitLab activity. @@ -86,7 +86,7 @@ not. When visiting the public page of a user, you can only see the projects which you have privileges to. -If the [public level is restricted](../admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels), +If the [public level is restricted](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels), user profiles are only visible to signed-in users. ## Add external accounts to your user profile page @@ -106,8 +106,6 @@ To add links to other accounts: ## Show private contributions on your user profile page -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14078) in GitLab 11.3. - In the user contribution calendar graph and recent activity list, you can see your [contribution actions](../../api/events.md#action-types) to private projects. To show private contributions: @@ -131,10 +129,23 @@ To specify your pronouns: 1. In the **Pronouns** field, enter your pronouns. 1. Select **Update profile settings**. +## Add your name pronunciation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25742) in GitLab 14.2. + +You can add your name pronunciation to your GitLab account. This is displayed in your profile, below +your name. + +To add your name pronunciation: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the **Pronunciation** field, enter how your name is pronounced. +1. Select **Update profile settings**. + ## Set your current status -> - Introduced in GitLab 11.2. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56649) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56649) in GitLab 13.10, users can schedule the clearing of their status. You can provide a custom status message for your user profile along with an emoji that describes it. This may be helpful when you are out of office or otherwise not available. @@ -195,9 +206,15 @@ To set the busy status indicator, either: | --- | --- | |  |  | -## Change the email displayed on your commits +## Set your time zone + +To set your time zone: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the **Time settings** section, select your time zone from the dropdown list. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21598) in GitLab 11.4. +## Change the email displayed on your commits A commit email is an email address displayed in every Git-related action carried out through the GitLab interface. @@ -212,8 +229,6 @@ To change your commit email: ### Use an automatically-generated private commit email -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22560) in GitLab 11.5. - GitLab provides an automatically-generated private commit email address, so you can keep your email information private. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index eaf1d33a938..17b4251662e 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -56,11 +56,11 @@ Your **Global notification settings** are the default settings unless you select different values for a project or a group. - **Notification email**: the email address your notifications are sent to. -- **Receive product marketing emails**: select this check box to receive +- **Receive product marketing emails**: select this checkbox to receive [periodic emails](#product-marketing-emails) about GitLab features. - **Global notification level**: the default [notification level](#notification-levels) which applies to all your notifications. -- **Receive notifications about your own activity**: select this check box to receive +- **Receive notifications about your own activity**: select this checkbox to receive notifications about your own activity. Not selected by default.  @@ -143,7 +143,7 @@ For each project and group you can select one of the following levels: |:------------|:------------| | Global | Your global settings apply. | | Watch | Receive notifications for any activity. | -| On mention | Receive notifications when `@mentioned` in comments. | +| On mention | Receive notifications when [mentioned](../project/issues/issue_data_and_actions.md#mentions) in a comment. | | Participate | Receive notifications for threads you have participated in. | | Disabled | Turns off notifications. | | Custom | Receive notifications for custom selected events. | @@ -278,7 +278,7 @@ The participants are: - Authors of the design (can be multiple people if different authors have uploaded different versions of the design). - Authors of comments on the design. -- Anyone that is `@mentioned` in a comment on the design. +- Anyone that is [mentioned](../project/issues/issue_data_and_actions.md#mentions) in a comment on the design. ## Opt out of all GitLab emails @@ -328,5 +328,12 @@ reason `assigned` has this sentence in the footer: - `You are receiving this email because you have been assigned an item on <configured GitLab hostname>.` -NOTE: Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/20689). + +For example, an alert notification email can have one of +[the alert's](../../operations/incident_management/alerts.md) statuses: + +- `alert_triggered` +- `alert_acknowledged` +- `alert_resolved` +- `alert_ignored` diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 0dbf00a83fb..c534a630480 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -5,13 +5,12 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Personal access tokens +# Personal access tokens **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3749) in GitLab 8.8. -> - [Notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in GitLab 12.6. -> - [Token lifetime limits](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. -> - [Additional notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/214721) added in GitLab 13.3. -> - [Prefill token name and scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/334664) added in GitLab 14.1. +> - Introduced in GitLab 12.6: [Notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649). +> - Introduced in GitLab Ultimate 12.6: [Token lifetime limits](https://gitlab.com/gitlab-org/gitlab/-/issues/3649). +> - Introduced in GitLab 13.3: [Additional notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/214721). +> - Introduced in GitLab 14.1: [Prefill token name and scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/334664). If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/index.md#personalproject-access-tokens). You can also use a personal access token with Git to authenticate over HTTP. @@ -73,16 +72,16 @@ To view the last time a token was used: A personal access token can perform actions based on the assigned scopes. -| Scope | Introduced in | Access | -| ------------------ | ------------- | ----------- | -| `api` | [8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | Read-write for the complete API, including all groups and projects, the Container Registry, and the Package Registry. | -| `read_user` | [8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | Read-only for endpoints under `/users`. Essentially, access to any of the `GET` requests in the [Users API](../../api/users.md). | -| `read_api` | [12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) | Read-only for the complete API, including all groups and projects, the Container Registry, and the Package Registry. | -| `read_repository` | [10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) | Read-only (pull) for the repository through `git clone`. | -| `write_repository` | [11.11](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26021) | Read-write (pull, push) for the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled. | -| `read_registry` | [9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11845) | Read-only (pull) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | [12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) | Read-write (push) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `sudo` | [10.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14838) | API actions as any user in the system (if the authenticated user is an administrator). | +| Scope | Access | +|--------------------|--------| +| `api` | Read-write for the complete API, including all groups and projects, the Container Registry, and the Package Registry. | +| `read_user` | Read-only for endpoints under `/users`. Essentially, access to any of the `GET` requests in the [Users API](../../api/users.md). | +| `read_api` | Read-only for the complete API, including all groups and projects, the Container Registry, and the Package Registry. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) in GitLab 12.10.) | +| `read_repository` | Read-only (pull) for the repository through `git clone`. | +| `write_repository` | Read-write (pull, push) for the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled. | +| `read_registry` | Read-only (pull) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Read-write (push) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | +| `sudo` | API actions as any user in the system (if the authenticated user is an administrator). | ## When personal access tokens expire diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index fad9b67eee4..e079e6dcbee 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -54,9 +54,10 @@ See the epic for: If you find an issue that isn't listed, please leave a comment on the epic or create a new issue. -Dark mode is available as a navigation theme, for MVC and compatibility reasons. In -the future, we plan to make it configurable in its own section along with support for -[different navigation themes](https://gitlab.com/gitlab-org/gitlab/-/issues/219512). +Dark mode is available as a navigation theme, for MVC and compatibility reasons. +[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/219512) +to make it configurable in its own section along with support for +different navigation themes. Dark theme only works with the **Dark** syntax highlighting theme. diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md deleted file mode 100644 index 1ecfb3b7292..00000000000 --- a/doc/user/project/bulk_editing.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'issues/managing_issues.md' -remove_date: '2021-08-12' ---- - -This document was moved to [another location](issues/managing_issues.md). - -<!-- This redirect file can be deleted after <2021-08-12>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 6cada5648cb..fba02183be5 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Creating a new cluster or adding an existing cluster to GitLab through the certificate-based method +Creating a new cluster through the certificate-based method is deprecated and no longer recommended. Kubernetes cluster, similar to any other infrastructure, should be created, updated, maintained using [Infrastructure as Code](../../infrastructure/index.md). GitLab is developing a built-in capability to create clusters with Terraform. @@ -42,8 +42,8 @@ providers. To host them on premises and with other providers, use either the EKS or GKE method to guide you through and enter your cluster's settings manually: -- [New cluster hosted on Google Kubernetes Engine (GKE)](add_eks_clusters.md). -- [New cluster hosted on Amazon Elastic Kubernetes Service (EKS)](add_gke_clusters.md). +- [New cluster hosted on Google Kubernetes Engine (GKE)](add_gke_clusters.md). +- [New cluster hosted on Amazon Elastic Kubernetes Service (EKS)](add_eks_clusters.md). ## Add existing cluster diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 713a60b2dd0..7bf202f6963 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -83,6 +83,4 @@ arbitrary images as they effectively have root access. If you don't want to use a runner in privileged mode, either: - Use shared runners on GitLab.com. They don't have this security issue. -- Set up your own runners using the configuration described at -[shared runners](../../gitlab_com/index.md#shared-runners) using -[`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). +- Set up your own runners that use [`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). diff --git a/doc/user/project/clusters/runbooks/img/ingress-install.png b/doc/user/project/clusters/runbooks/img/ingress-install.png Binary files differdeleted file mode 100644 index 08256a65138..00000000000 --- a/doc/user/project/clusters/runbooks/img/ingress-install.png +++ /dev/null diff --git a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png Binary files differdeleted file mode 100644 index 784e508ff25..00000000000 --- a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png +++ /dev/null diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png Binary files differdeleted file mode 100644 index 7b5d6497f0e..00000000000 --- a/doc/user/project/clusters/serverless/img/dns-entry.png +++ /dev/null diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png Binary files differdeleted file mode 100644 index 1dc830848f2..00000000000 --- a/doc/user/project/clusters/serverless/img/install-knative.png +++ /dev/null diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 2a60c06814b..7d51fb59793 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -8,22 +8,21 @@ type: reference # Code Owners **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3. -> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. +> - Code Owners for merge request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. > - Moved to GitLab Premium in 13.9. -Code Owners define who owns specific files or paths in a repository. -You can require that Code Owners approve a merge request before it's merged. +Code Owners define who owns specific files or directories in a repository. -Code Owners help you determine who should review or approve merge requests. -If you have a question about a file or feature, Code Owners -can help you find someone who knows the answer. +- The users you define as Code Owners are displayed in the UI when you browse directories. +- You can set your merge requests so they must be approved by Code Owners before merge. +- You can protect a branch and allow only Code Owners to approve changes to the branch. If you don't want to use Code Owners for approvals, you can [configure rules](merge_requests/approvals/rules.md) instead. ## Set up Code Owners -You can specify users or [shared groups](members/share_project_with_groups.md) +You can use Code Owners to specify users or [shared groups](members/share_project_with_groups.md) that are responsible for specific files and directories in a repository. To set up Code Owners: @@ -38,150 +37,102 @@ To set up Code Owners: 1. In the file, enter text that follows one of these patterns: ```plaintext - # A member as Code Owner of a file - filename @username + # Code Owners for a file + filename @username1 @username2 - # A member as Code Owner of a directory - directory @username + # Code Owners for a directory + directoryname/ @username1 @username2 - # All group members as Code Owners of a file + # All group members as Code Owners for a file filename @groupname - # All group members as Code Owners of a directory - directory @groupname + # All group members as Code Owners for a directory + directoryname/ @groupname ``` -The Code Owners are displayed in the UI by the files or directory they apply to. -These owners apply to this branch only. When you add new files to the repository, -you should update the `CODEOWNERS` file. +The Code Owners are now displayed in the UI. They apply to the current branch only. -## When a file matches multiple `CODEOWNERS` entries +Next steps: -When a file matches multiple entries in the `CODEOWNERS` file, -the users from last pattern matching the file are used. - -For example, in the following `CODEOWNERS` file: +- [Add Code Owners as merge request approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). +- Set up [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch). -```plaintext -README.md @user1 - -# This line would also match the file README.md -*.md @user2 -``` - -The user that would show for `README.md` would be `@user2`. - -## Approvals by Code Owners +## Groups as Code Owners -After you've added Code Owners to a project, you can configure it to -be used for merge request approvals: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. -- As [merge request eligible approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). -- As required approvers for [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch). **(PREMIUM)** +You can use members of groups and subgroups as Code Owners for a project. -Developer or higher [permissions](../permissions.md) are required to -approve a merge request. +For example, if you have these groups: -After it's set, Code Owners are displayed in merge request widgets: +- **Group X** (`group-x`) with **Project A** in it. +- **Subgroup Y** (`group-x/subgroup-y`), which belongs to **Group X**, with **Project B** in it. - +The eligible Code Owners: -While you can use the `CODEOWNERS` file in addition to Merge Request -[Approval Rules](merge_requests/approvals/rules.md), -you can also use it as the sole driver of merge request approvals -without using [Approval Rules](merge_requests/approvals/rules.md): +- For **Project A** are the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. +- For **Project B** are the members of both **Group X** and **Subgroup Y**. -1. Create the file in one of the three locations specified above. -1. Set the code owners as required approvers for - [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch). -1. Use [the syntax of Code Owners files](code_owners.md) - to specify the actual owners and granular permissions. + -Using Code Owners in conjunction with [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch) -prevents any user who is not specified in the `CODEOWNERS` file from pushing -changes for the specified files/paths, except those included in the -**Allowed to push** column. This allows for a more inclusive push strategy, as -administrators don't have to restrict developers from pushing directly to the -protected branch, but can restrict pushing to certain files where a review by -Code Owners is required. +You can [invite](members/share_project_with_groups.md) **Subgroup Y** to **Project A** +so that their members also become eligible Code Owners. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules, Code Owners included. + -## Groups as Code Owners +If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval +of the merge request becomes optional. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. -> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. +### Add a group as a Code Owner -Groups and subgroups members are inherited as eligible Code Owners to a -project, as long as the hierarchy is respected. +To set a group as a Code Owner: -For example, consider a given group called "Group X" (slug `group-x`) and a -"Subgroup Y" (slug `group-x/subgroup-y`) that belongs to the Group X, and -suppose you have a project called "Project A" within the group and a -"Project B" within the subgroup. +In the `CODEOWNERS` file, enter text that follows one of these patterns: -The eligible Code Owners to Project B are both the members of the Group X and -the Subgroup Y. The eligible Code Owners to the Project A are just the -members of the Group X, given that Project A doesn't belong to the Subgroup Y: +```plaintext +# All group members as Code Owners for a file +file.md @group-x - +# All subgroup members as Code Owners for a file +file.md @group-x/subgroup-y -But you have the option to [invite](members/share_project_with_groups.md) -the Subgroup Y to the Project A so that their members also become eligible -Code Owners: +# All group and subgroup members as Code Owners for a file +file.md @group-x @group-x/subgroup-y +``` -NOTE: -If you do not invite Subgroup Y to Project A, but make them Code Owners, their approval -of the merge request becomes optional. +## When a file matches multiple `CODEOWNERS` entries - +When a file matches multiple entries in the `CODEOWNERS` file, +the users from last pattern matching the file are used. -After being invited, any member (`@user`) of the group or subgroup can be set -as Code Owner to files of the Project A or B, and the entire Group X -(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as follows: +For example, in the following `CODEOWNERS` file: ```plaintext -# A member of the group or subgroup as Code Owner to a file -file.md @user +README.md @user1 -# All group members as Code Owners to a file -file.md @group-x +# This line would also match the file README.md +*.md @user2 +``` -# All subgroup members as Code Owners to a file -file.md @group-x/subgroup-y +The Code Owner for `README.md` would be `@user2`. -# All group and subgroup members as Code Owners to a file -file.md @group-x @group-x/subgroup-y -``` +If you use sections, the last user _for each section_ is used. -### Code Owners Sections **(PREMIUM)** +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. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. -Code Owner rules can be grouped into named sections. This allows for better -organization of broader categories of Code Owner rules to be applied. -Additionally, the usual guidance that only the last pattern matching the file is -applied is expanded such that the last pattern matching _for each section_ is -applied. - -For example, in a large organization, independent teams may have a common interest -in parts of the application, for instance, a payment processing company may have -"development", "security", and "compliance" teams looking after common parts of -the codebase. All three teams may need to approve changes. Although approval rules -make this possible, they apply to every merge request. Also, while Code Owners are -applied based on which files are changed, only one CODEOWNERS pattern can match per -file path. - -Using `CODEOWNERS` sections allows multiple teams that only need to approve certain -changes, to set their own independent patterns by specifying discrete sections in the -`CODEOWNERS` file. The section rules may be used for shared paths so that multiple -teams can be added as reviewers. - -Sections can be added to `CODEOWNERS` files as a new line with the name of the -section inside square brackets. Every entry following is assigned to that -section. The following example would create two Code Owner rules for the "README -Owners" section: +You can organize Code Owners by putting them into named sections. + +You can use sections for shared directories, so that multiple +teams can be reviewers. + +To add a section to the `CODEOWNERS` file, enter a section name in brackets, +followed by the files or directories, and users, groups, or subgroups: ```plaintext [README Owners] @@ -189,43 +140,41 @@ README.md @user1 @user2 internal/README.md @user2 ``` -Multiple sections can be used, even with matching file or directory patterns. -Reusing the same section name groups the results together under the same -section, with the most specific rule or last matching pattern being used. For -example, consider the following entries in a `CODEOWNERS` file: +Each Code Owner in the merge request widget is listed under a label. +The following image shows a **Groups** and **Documentation** section: + + + +### Sections with duplicate names + +If multiple sections have the same name, they are combined. +Also, section headings are not case-sensitive. For example: ```plaintext [Documentation] -ee/docs @gl-docs -docs @gl-docs +ee/docs/ @docs +docs/ @docs [Database] -README.md @gl-database -model/db @gl-database +README.md @database +model/db/ @database [DOCUMENTATION] -README.md @gl-docs +README.md @docs ``` -This results in three entries under the "Documentation" section header, and two -entries under "Database". Case is not considered when combining sections, so in -this example, entries defined under the sections "Documentation" and -"DOCUMENTATION" would be combined into one, using the case of the first instance -of the section encountered in the file. +This code results in three entries under the **Documentation** section header, and two +entries under **Database**. The entries defined under the sections **Documentation** and +**DOCUMENTATION** are combined, using the case of the first section. -When assigned to a section, each code owner rule displayed in merge requests -widget is sorted under a "section" label. In the screenshot below, we can see -the rules for "Groups" and "Documentation" sections: - - - -#### Optional Code Owners Sections **(PREMIUM)** +### Make a Code Owners section optional > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9. -To make a certain section optional, add a code owners section prepended with the -caret `^` character. Approvals from owners listed in the section are **not** required. For example: +You can make a section optional, so that approval from the Code Owners in that section is optional. + +Put a caret `^` character before the Code Owners section name. For example: ```plaintext [Documentation] @@ -238,102 +187,83 @@ caret `^` character. Approvals from owners listed in the section are **not** req *.go @root ``` -The optional code owners section displays in merge requests under the **Approval Rules** area: - - - -If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. - -For example, the code owners of the "Documentation" section below is still required to approve merge requests: - -```plaintext -[Documentation] -*.md @root - -[Ruby] -*.rb @root +The optional Code Owners section displays in merge requests under the **Approval Rules** area: -^[Go] -*.go @root + -^[Documentation] -*.txt @root -``` +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the section is required. -Optional sections in the code owners file are treated as optional only +Optional sections in the `CODEOWNERS` file are treated as optional only when changes are submitted by using merge requests. If a change is submitted directly -to the protected branch, approval from code owners is still required, even if the -section is marked as optional. We plan to change this behavior in a -[future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638), -and allow direct pushes to the protected branch for sections marked as optional. +to the protected branch, approval from Code Owners is still required, even if the +section is marked as optional. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297638) +to allow direct pushes to the protected branch for sections marked as optional. ## Example `CODEOWNERS` file ```plaintext -# This is an example of a code owners file -# lines starting with a `#` will be ignored. +# This is an example of a CODEOWNERS file. +# Lines that start with `#` are ignored. # app/ @commented-rule -# We can specify a default match using wildcards: +# Specify a default Code Owner by using a wildcard: * @default-codeowner -# We can also specify "multiple tab or space" separated codeowners: +# Specify multiple Code Owners by using a tab or space: * @multiple @code @owners # Rules defined later in the file take precedence over the rules # defined before. -# This will match all files for which the file name ends in `.rb` +# For example, for all files with a filename ending in `.rb`: *.rb @ruby-owner -# Files with a `#` can still be accessed by escaping the pound sign +# Files with a `#` can still be accessed by escaping the pound sign: \#file_with_pound.rb @owner-file-with-pound -# Multiple codeowners can be specified, separated by spaces or tabs +# Specify multiple Code Owners separated by spaces or tabs. # In the following case the CODEOWNERS file from the root of the repo -# has 3 code owners (@multiple @code @owners) +# has 3 Code Owners (@multiple @code @owners): CODEOWNERS @multiple @code @owners -# Both usernames or email addresses can be used to match -# users. Everything else will be ignored. For example this will -# specify `@legal` and a user with email `janedoe@gitlab.com` as the -# owner for the LICENSE file +# You can use both usernames or email addresses to match +# users. Everything else is ignored. For example, this code +# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the +# owner for the LICENSE file: LICENSE @legal this_does_not_match janedoe@gitlab.com -# Group names can be used to match groups and nested groups to specify -# them as owners for a file +# Use group names to match groups, and nested groups to specify +# them as owners for a file: README @group @group/with-nested/subgroup -# Ending a path in a `/` will specify the code owners for every file -# nested in that directory, on any level +# End a path in a `/` to specify the Code Owners for every file +# nested in that directory, on any level: /docs/ @all-docs -# Ending a path in `/*` will specify code owners for every file in -# that directory, but not nested deeper. This will match -# `docs/index.md` but not `docs/projects/index.md` +# End a path in `/*` to specify Code Owners for every file in +# a directory, but not nested deeper. This code matches +# `docs/index.md` but not `docs/projects/index.md`: /docs/* @root-docs -# This will make a `lib` directory nested anywhere in the repository -# match +# This code makes matches a `lib` directory nested anywhere in the repository: lib/ @lib-owner -# This will only match a `config` directory in the root of the -# repository +# This code match only a `config` directory in the root of the repository: /config/ @config-owner -# If the path contains spaces, these need to be escaped like this: +# If the path contains spaces, escape them like this: path\ with\ spaces/ @space-owner # Code Owners section: [Documentation] -ee/docs @gl-docs -docs @gl-docs +ee/docs @docs +docs @docs [Database] -README.md @gl-database -model/db @gl-database +README.md @database +model/db @database -# This section will be joined with the [Documentation] section previously defined: +# This section is combined with the previously defined [Documentation] section: [DOCUMENTATION] -README.md @gl-docs +README.md @docs ``` diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index a09448d4755..64a5515136b 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -59,7 +59,7 @@ specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the environments list, verify that what's running in staging is what you think is - running, then click on the [manual action](../../ci/yaml/index.md#whenmanual) to deploy to production. + running, then click on the [manual job](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) to deploy to production. - You trigger a deploy, and you have many containers to upgrade so you know this takes a while (you've also throttled your deploy to only take down X containers at a time). But you need to tell someone when it's deployed, so you diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 800aa27f612..70363b67c88 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -20,6 +20,8 @@ Deploy tokens can be managed by [maintainers only](../../permissions.md). Deploy tokens cannot be used with the GitLab API. +Deploy tokens are tied to the project and stay enabled even when the user who created the token is removed from the project. + If you have a key pair, you might want to use [deploy keys](../../project/deploy_keys/index.md) instead. @@ -171,6 +173,16 @@ To use a group deploy token: The scopes applied to a group deploy token (such as `read_repository`) apply consistently when cloning the repository of related projects. +### Pull images from the Dependency Proxy + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280586) in GitLab 14.2. + +To pull images from the Dependency Proxy, you must: + +1. Create a group deploy token with both `read_registry` and `write_registry` scopes. +1. Take note of your `username` and `token`. +1. Follow the Depenency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). + ### GitLab deploy token > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18414) in GitLab 10.8. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index aa8cf4549e2..728f51a8062 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -14,18 +14,23 @@ The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Edito 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 -<!-- vale gitlab.Spelling = NO --> Prolog <!-- vale gitlab.Spelling = YES --> +`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: +<!-- vale gitlab.Spelling = YES --> + ``` conf *.pl gitlab-language=prolog ``` <!-- vale gitlab.Spelling = NO --> + When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. + <!-- vale gitlab.Spelling = YES --> 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: @@ -44,7 +49,7 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen /other-file gitlab-language=text?token=Error ``` -Please note that these configurations only take effect when the `.gitattributes` +These configurations only take effect when the `.gitattributes` file is in your [default branch](repository/branches/default.md). NOTE: diff --git a/doc/user/project/img/code_owners_mr_widget_v12_4.png b/doc/user/project/img/code_owners_mr_widget_v12_4.png Binary files differdeleted file mode 100644 index 7f7b15ee017..00000000000 --- a/doc/user/project/img/code_owners_mr_widget_v12_4.png +++ /dev/null diff --git a/doc/user/project/img/epics_swimlanes_v13.6.png b/doc/user/project/img/epics_swimlanes_v13.6.png Binary files differdeleted file mode 100644 index 6f787ba8b10..00000000000 --- a/doc/user/project/img/epics_swimlanes_v13.6.png +++ /dev/null diff --git a/doc/user/project/img/epics_swimlanes_v14_1.png b/doc/user/project/img/epics_swimlanes_v14_1.png Binary files differnew file mode 100644 index 00000000000..6c1e23ad685 --- /dev/null +++ b/doc/user/project/img/epics_swimlanes_v14_1.png diff --git a/doc/user/project/img/issue_board_add_list_v13_6.png b/doc/user/project/img/issue_board_add_list_v13_6.png Binary files differdeleted file mode 100644 index 4239ab6e7e4..00000000000 --- a/doc/user/project/img/issue_board_add_list_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_add_list_v14_1.png b/doc/user/project/img/issue_board_add_list_v14_1.png Binary files differnew file mode 100644 index 00000000000..28c1d9bf2d6 --- /dev/null +++ b/doc/user/project/img/issue_board_add_list_v14_1.png diff --git a/doc/user/project/img/issue_board_assignee_lists_v13_6.png b/doc/user/project/img/issue_board_assignee_lists_v13_6.png Binary files differdeleted file mode 100644 index d0fbb0a2ef0..00000000000 --- a/doc/user/project/img/issue_board_assignee_lists_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_assignee_lists_v14_1.png b/doc/user/project/img/issue_board_assignee_lists_v14_1.png Binary files differnew file mode 100644 index 00000000000..db2afe9c31e --- /dev/null +++ b/doc/user/project/img/issue_board_assignee_lists_v14_1.png diff --git a/doc/user/project/img/issue_board_milestone_lists_v13_6.png b/doc/user/project/img/issue_board_milestone_lists_v13_6.png Binary files differdeleted file mode 100644 index a7718ffd66c..00000000000 --- a/doc/user/project/img/issue_board_milestone_lists_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_milestone_lists_v14_1.png b/doc/user/project/img/issue_board_milestone_lists_v14_1.png Binary files differnew file mode 100644 index 00000000000..7d833d39c45 --- /dev/null +++ b/doc/user/project/img/issue_board_milestone_lists_v14_1.png diff --git a/doc/user/project/img/issue_boards_core_v13_6.png b/doc/user/project/img/issue_boards_core_v13_6.png Binary files differdeleted file mode 100644 index 8695b523c12..00000000000 --- a/doc/user/project/img/issue_boards_core_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_core_v14_1.png b/doc/user/project/img/issue_boards_core_v14_1.png Binary files differnew file mode 100644 index 00000000000..728e7743e54 --- /dev/null +++ b/doc/user/project/img/issue_boards_core_v14_1.png diff --git a/doc/user/project/img/issue_boards_premium_v13_6.png b/doc/user/project/img/issue_boards_premium_v13_6.png Binary files differdeleted file mode 100644 index 8d1c1299d5c..00000000000 --- a/doc/user/project/img/issue_boards_premium_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_premium_v14_1.png b/doc/user/project/img/issue_boards_premium_v14_1.png Binary files differnew file mode 100644 index 00000000000..ee7d1dbe05d --- /dev/null +++ b/doc/user/project/img/issue_boards_premium_v14_1.png diff --git a/doc/user/project/img/protected_branches_devs_can_push_v12_3.png b/doc/user/project/img/protected_branches_devs_can_push_v12_3.png Binary files differdeleted file mode 100644 index adc03a41abb..00000000000 --- a/doc/user/project/img/protected_branches_devs_can_push_v12_3.png +++ /dev/null diff --git a/doc/user/project/img/remaining_time_v14_2.png b/doc/user/project/img/remaining_time_v14_2.png Binary files differnew file mode 100644 index 00000000000..76dd0792943 --- /dev/null +++ b/doc/user/project/img/remaining_time_v14_2.png diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 27a84476590..120c64e00f2 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -31,7 +31,7 @@ _Taken from the slides [ClearCase and the journey to Git](https://docplayer.net/ ## Why migrate -ClearCase can be difficult to manage both from a user and an admin perspective. +ClearCase can be difficult to manage both from a user and an administrator perspective. Migrating to Git/GitLab there is: - **No licensing costs**, Git is GPL while ClearCase is proprietary. diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md deleted file mode 100644 index 37460da1289..00000000000 --- a/doc/user/project/import/gemnasium.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2021-08-15' ---- - -This document was deleted. - -<!-- This redirect file can be deleted after <2021-08-15>. --> -<!-- 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/project/import/github.md b/doc/user/project/import/github.md index e67b6a45280..1ab343d75fb 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -179,8 +179,8 @@ Sidekiq workers that process the following queues: For an optimal experience, it's recommended having at least 4 Sidekiq processes (each running a number of threads equal to the number of CPU cores) that *only* process these queues. It's also recommended that these processes run on separate -servers. For 4 servers with 8 cores this means you can import up to 32 objects (e.g., issues) in parallel. +servers. For 4 servers with 8 cores this means you can import up to 32 objects (for example, issues) in parallel. Reducing the time spent in cloning a repository can be done by increasing network throughput, CPU capacity, and disk -performance (e.g., by using high performance SSDs) of the disks that store the Git repositories (for your GitLab instance). +performance (by using high performance SSDs, for example) of the disks that store the Git repositories (for your GitLab instance). Increasing the number of Sidekiq workers will *not* reduce the time spent cloning repositories. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index f7eb5e43a79..f25b29317a7 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -15,7 +15,7 @@ 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, -you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data) +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 07419080d7d..3e0faec0a49 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -46,7 +46,7 @@ GitLab project that you wish to import into. ### Jira integration -This feature uses the existing GitLab [Jira integration](../integrations/jira.md). +This feature uses the existing GitLab [Jira integration](../../../integration/jira/index.md). Make sure you have the integration set up before trying to import Jira issues. @@ -68,7 +68,7 @@ To import Jira issues to a GitLab project: The **Import from Jira** option is only visible if you have the [correct permissions](#permissions). The following form appears. - If you've previously set up the [Jira integration](../integrations/jira.md), you can now see + 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.  diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 6a1370f3301..80f2d6d7e62 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -36,4 +36,4 @@ of the project being imported into, then the user will be linked. ## Enable this feature -Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area. +Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) in the Admin Area. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index fca9c3e7023..668a0dffd32 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -36,7 +36,7 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Deploy tokens](deploy_tokens/index.md): Manage access to the repository and Container Registry. - [Web IDE](web_ide/index.md) - [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a - vulnerability in your project. + vulnerability in your project. **(FREE SAAS)** **Issues and merge requests:** @@ -121,7 +121,7 @@ Kubernetes, Slack, and a lot more. - [Bitbucket to GitLab](import/bitbucket.md) - [Gitea to GitLab](import/gitea.md) - [FogBugz to GitLab](import/fogbugz.md) -- [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) +- [Export a project from GitLab](settings/import_export.md#export-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) ## GitLab Workflow - VS Code extension diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index b9552fff110..e1e926da19b 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 1eb8a8c60e0..58cfd8c3a2f 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- @@ -55,7 +55,7 @@ service in GitLab. 1. If necessary, enter username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require authentication. -1. Save or optionally click **Test Settings**. Please note that **Test Settings** +1. Save or optionally click **Test Settings**. **Test Settings** actually triggers a build in Bamboo. ## Troubleshooting diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index e8427e36015..a54a3adc408 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 19beafd6663..eaab1933b79 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 2ec657eec22..c9333b879f3 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 3ef4a4e5004..33c197b962e 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 5b0059673ad..bc9b2d59db3 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 019ca9da9f1..6b342392bdf 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index ac70c7e4b4e..0d8ea636eba 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index d5dc02d5455..bcaedbc4b10 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/img/prometheus_deploy.png b/doc/user/project/integrations/img/prometheus_deploy.png Binary files differdeleted file mode 100644 index 3f19f23b0cc..00000000000 --- a/doc/user/project/integrations/img/prometheus_deploy.png +++ /dev/null diff --git a/doc/user/project/integrations/img/services_templates_redmine_example.png b/doc/user/project/integrations/img/services_templates_redmine_example.png Binary files differdeleted file mode 100644 index 34594dfdd55..00000000000 --- a/doc/user/project/integrations/img/services_templates_redmine_example.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index f9e15ced858..6f86098b33d 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 295300fb55d..b96605ff5c9 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,60 +1,72 @@ --- -stage: Create -group: Ecosystem +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 --- -# Irker IRC Gateway **(FREE)** +# irker IRC Gateway **(FREE)** -GitLab provides a way to push update messages to an Irker server. When +GitLab provides a way to push update messages to an irker server. When configured, pushes to a project trigger the service to send data directly -to the Irker server. +to the irker server. -See the [project homepage](https://gitlab.com/esr/irker) for further information. +See also the [irker integration API documentation](../../../api/services.md). -## Needed setup +For more information, see the [irker project homepage](https://gitlab.com/esr/irker). -You first need an Irker daemon. You can download the Irker code -[from its repository](https://gitlab.com/esr/irker): +## Set up an irker daemon -```shell -git clone https://gitlab.com/esr/irker.git -``` +You need to set up an irker daemon. To do so: -Once you have downloaded the code, you can run the Python script named `irkerd`. -This script is the gateway script, it acts both as an IRC client, for sending -messages to an IRC server, and as a TCP server, for receiving messages -from the GitLab service. +1. Download the irker code [from its repository](https://gitlab.com/esr/irker): -If the Irker server runs on the same machine, you are done. If not, you + ```shell + git clone https://gitlab.com/esr/irker.git + ``` + +1. Run the Python script named `irkerd`. This is the gateway script. + It acts both as an IRC client, for sending messages to an IRC server, + and as a TCP server, for receiving messages from the GitLab service. + +If the irker server runs on the same machine, you are done. If not, you need to follow the first steps of the next section. +WARNING: +irker does **not** have built-in authentication, which makes it vulnerable to spamming IRC channels if +it is hosted outside of a firewall. To prevent abuse, make sure you run the daemon on a secured +network. For more details, read +[Security analysis of irker](http://www.catb.org/~esr/irker/security.html). + ## Complete these steps in GitLab -1. Navigate to the project you want to configure for notifications. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click "Irker". +1. On the top bar, select **Menu > Projects** and find the project you want to + configure for notifications. +1. Navigate to the [Integrations page](overview.md#accessing-integrations). +1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. -1. Enter the server host address where `irkerd` runs (defaults to `localhost`) - in the `Server host` field on the Web page -1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the - `Server port` field on the Web page. -1. Optional: if `Default IRC URI` is set, it has to be in the format - `irc[s]://domain.name` and is prepended to each and every channel provided - by the user which is not a full URI. -1. Specify the recipients (e.g. #channel1, user1, etc.) -1. Save or optionally click "Test Settings". - -## Note on Irker recipients - -Irker accepts channel names of the form `chan` and `#chan`, both for the -`#chan` channel. If you want to send messages in query, you need to add -`,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter -case, `Aorimn` is treated as a nick and no more as a channel name. - -Irker can also join password-protected channels. Users need to append -`?key=thesecretpassword` to the channel name. When using this feature remember to -**not** put the `#` sign in front of the channel name; failing to do so -results in Irker joining a channel literally named `#chan?key=password` henceforth -leaking the channel key through the `/whois` IRC command (depending on IRC server -configuration). This is due to a long standing Irker bug. +1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty, + it defaults to `localhost`. +1. Optional. Under **Server port**, enter the server port of `irkerd`. If empty, it defaults to `6659`. +1. Optional. Under **Default IRC URI**, enter the default IRC URI, in the format `irc[s]://domain.name`. + It's prepended to every channel or user provided under **Recipients**, which is not a full URI. +1. Under **Recipients**, enter the users or channels to receive updates, separated by spaces + (for example, `#channel1 user1`). For more details, see [Enter irker recipients](#enter-irker-recipients). +1. Optional. Under **Colorize messages**, select the checkbox. irker will highlight your messages. +1. Select **Save changes** or optionally select **Test Settings**. + +## Enter irker recipients + +If you left the **Default IRC URI** field empty, enter recipients as a full URI: +`irc[s]://irc.network.net[:port]/#channel`. If you entered a default IRC URI there, you can use just +channel or user names. + +To send messages: + +- To a channel (for example, `#chan`), irker accepts channel names of the form `chan` and + `#chan`. +- To a password-protected channel, append `?key=thesecretpassword` to the channel name, + with the channel password instead of `thesecretpassword`. For example, `chan?key=hunter2`. + Do **not** put the `#` sign in front of the channel name. If you do, irker tries to join a + channel named `#chan?key=password` and so it can leak the channel password through the + `/whois` IRC command. This is due to a long-standing irker bug. +- In a user query, add `,isnick` after the user name. For example, `UserSmith,isnick`. diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md deleted file mode 100644 index 521f15f330e..00000000000 --- a/doc/user/project/integrations/jira.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../../integration/jira/index.md' -remove_date: '2021-07-07' ---- - -This document was moved to [another location](../../../integration/jira/index.md). - -<!-- This redirect file can be deleted after 2021-07-07. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md deleted file mode 100644 index 3aacf051c22..00000000000 --- a/doc/user/project/integrations/jira_integrations.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../../integration/jira/index.md' -remove_date: '2021-07-13' ---- - -This document was moved to [another location](../../../integration/jira/index.md). - -<!-- This redirect file can be deleted after <2021-07-13>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 18ff6e324e3..92e5feefb73 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 619ae52481b..5b5feb73b69 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- @@ -110,7 +110,7 @@ provide to GitLab: 1. In the GitLab browser tab from [getting configuration values from GitLab](#get-configuration-values-from-gitlab), - select the **Active** check box to enable this configuration. + select the **Active** checkbox to enable this configuration. 1. In the **Token** field, paste the token you obtained from Mattermost. ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 795ead573f2..fac26f8e70c 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- @@ -38,7 +38,7 @@ GitLab to send the notifications: to your project's page. 1. Go to **Settings > Integrations** and select **Microsoft Teams Notification**. 1. Select **Active** to enable the integration. -1. Select the check box next to each **Trigger** to enable: +1. Select the checkbox next to each **Trigger** to enable: - Push - Issue - Confidential issue @@ -51,7 +51,7 @@ GitLab to send the notifications: 1. In **Webhook**, paste the URL you copied when you [configured Microsoft Teams](#configure-microsoft-teams). 1. (Optional) If you enabled the pipeline trigger, you can select the - **Notify only broken pipelines** check box to push notifications only when pipelines break. + **Notify only broken pipelines** checkbox to push notifications only when pipelines break. 1. Select the branches you want to send notifications for. 1. Click **Save changes**. diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 934510fd155..631c53dcc44 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 53aa9da30ab..13def74450c 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- @@ -41,14 +41,14 @@ Click on the service links to see further configuration instructions and details | [Flowdock](../../../api/services.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 | -| [Irker (IRC gateway)](irker.md) | Send IRC messages. | **{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 | -| [Jira](jira.md) | Use Jira as the issue tracker. | **{dotted-circle}** No | +| [Jira](../../../integration/jira/index.md) | Use Jira as the issue tracker. | **{dotted-circle}** No | | [Mattermost notifications](mattermost.md) | Send notifications about project events to Mattermost channels. | **{dotted-circle}** No | | [Mattermost slash commands](mattermost_slash_commands.md) | Perform common tasks with slash commands. | **{dotted-circle}** No | | [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications. | **{dotted-circle}** No | -| Packagist | Update your projects. | **{check-circle}** Yes | +| Packagist | Keep your PHP dependencies updated on Packagist. | **{check-circle}** Yes | | Pipelines emails | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | | [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index c2c827c240b..d464007dd5e 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index adc98151ce4..acae0793e19 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -109,7 +109,7 @@ can use only one: [Cluster precedence](../../instance/clusters/index.md#cluster-precedence). - If you have managed Prometheus applications installed on multiple Kubernetes clusters at the **same** level, the Prometheus application of a cluster with a - matching [environment scope](../../../ci/environments/index.md#scoping-environments-with-specs) is used. + matching [environment scope](../../../ci/environments/index.md#scope-environments-with-specs) is used. ## Determining the performance impact of a merge diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 77e6eb75b9f..05d7c31a288 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index bdc05552c31..fdcbb498621 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 17d1c3adcb5..5db4e839b54 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,52 +1,57 @@ --- -stage: Create -group: Ecosystem +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 --- -# Slack Notifications Service **(FREE)** +# Slack notifications service **(FREE)** -The Slack Notifications Service allows your GitLab project to send events +The Slack notifications service enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -NOTE: You can also use Slack slash commands to control GitLab inside Slack. This is the separately configured [Slack slash commands](slack_slash_commands.md). ## Slack configuration 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). -1. Select the Slack channel where notifications should be sent to by default. - Click the **Add Incoming WebHooks integration** button to add the configuration. -1. Copy the **Webhook URL**, which we use later in the GitLab configuration. +1. Identify the Slack channel where notifications should be sent to by default. + Select **Add Incoming WebHooks integration** to add the configuration. +1. Copy the **Webhook URL**, which is used later in the GitLab configuration. ## GitLab configuration -1. Open your project's page, and navigate to your project's - [Integrations page](overview.md#accessing-integrations) at - **Settings > Integrations**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Slack notifications** integration to configure it. -1. Click **Enable integration**. -1. In **Trigger**, select the checkboxes for each type of GitLab event to send to Slack as a - notification. See [Triggers available for Slack notifications](#triggers-available-for-slack-notifications) - for a full list. By default, messages are sent to the channel you configured during +1. In the **Enable integration** section, select the **Active** checkbox. +1. In the **Trigger** section, select the checkboxes for each type of GitLab + event to send to Slack as a notification. For a full list, see + [Triggers available for Slack notifications](#triggers-available-for-slack-notifications). + By default, messages are sent to the channel you configured during [Slack integration](#slack-configuration). -1. (Optional) To send messages to a different channel, multiple channels, or as a direct message: - - To send messages to channels, enter the Slack channel names, separated by commas. - - To send direct messages, use the Member ID found in the user's Slack profile. +1. (Optional) To send messages to a different channel, multiple channels, or as + a direct message: + - *To send messages to channels,* enter the Slack channel names, separated by + commas. + - *To send direct messages,* use the Member ID found in the user's Slack profile. NOTE: Usernames and private channels are not supported. -1. In **Webhook**, provide the webhook URL that you copied from the +1. In **Webhook**, enter the webhook URL you copied from the previous [Slack integration](#slack-configuration) step. -1. (Optional) In **Username**, provide the username of the Slack bot that sends the notifications. -1. Select the **Notify only broken pipelines** check box to only notify on failures. -1. In the **Branches to be notified** select box, choose which types of branches +1. (Optional) In **Username**, enter the username of the Slack bot that sends + the notifications. +1. Select the **Notify only broken pipelines** checkbox to notify only on failures. +1. In the **Branches to be notified** dropdown, select which types of branches to send notifications for. -1. Leave the **Labels to be notified** field blank to get all notifications or add labels that the issue or merge request must have in order to trigger a notification. -1. Click **Test settings and save changes**. +1. Leave the **Labels to be notified** field blank to get all notifications or + add labels that the issue or merge request must have in order to trigger a + notification. +1. Select **Test settings** to verify your information, and then select + **Save changes**. Your Slack team now starts receiving GitLab event notifications as configured. @@ -54,19 +59,19 @@ Your Slack team now starts receiving GitLab event notifications as configured. The following triggers are available for Slack notifications: -- **Push**: Triggered by a push to the repository. -- **Issue**: Triggered when an issue is created, updated, or closed. -- **Confidential issue**: Triggered when a confidential issue is created, - updated, or closed. -- **Merge request**: Triggered when a merge request is created, updated, or - merged. -- **Note**: Triggered when someone adds a comment. -- **Confidential note**: Triggered when someone adds a confidential note. -- **Tag push**: Triggered when a new tag is pushed to the repository. -- **Pipeline**: Triggered when a pipeline status changes. -- **Wiki page**: Triggered when a wiki page is created or updated. -- **Deployment**: Triggered when a deployment starts or finishes. -- **Alert**: Triggered when a new, unique alert is recorded. +| Trigger | Description | +|------------------------|-------------| +| **Push** | Triggered by a push to the repository. | +| **Issue** | Triggered when an issue is created, updated, or closed. | +| **Confidential issue** | Triggered when a confidential issue is created, updated, or closed. | +| **Merge request** | Triggered when a merge request is created, updated, or merged. | +| **Note** | Triggered when someone adds a comment. | +| **Confidential note** | Triggered when someone adds a confidential note. | +| **Tag push** | Triggered when a new tag is pushed to the repository. | +| **Pipeline** | Triggered when a pipeline status changes. | +| **Wiki page** | Triggered when a wiki page is created or updated. | +| **Deployment** | Triggered when a deployment starts or finishes. | +| **Alert** | Triggered when a new, unique alert is recorded. | ## Troubleshooting @@ -89,7 +94,7 @@ You may see an entry similar to the following in your Sidekiq log: ``` This is probably a problem either with GitLab communicating with Slack, or GitLab -communicating with itself. The former is less likely since Slack's security certificates +communicating with itself. The former is less likely, as Slack's security certificates should _hopefully_ always be trusted. We can establish which we're dealing with by using the below rails console script. @@ -114,6 +119,7 @@ If GitLab is not trusting HTTPS connections to itself, then you may need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). If GitLab is not trusting connections to Slack, then the GitLab -OpenSSL trust store is incorrect. Some typical causes: overriding -the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`, -or by accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. +OpenSSL trust store is incorrect. Some typical causes: + +- Overriding the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`. +- Accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 4f206cd3e45..dfebf9a1123 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 3e5e368722e..2e166e87ff5 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 2851fe0b299..3632fdf0e0c 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 01f3424d993..44225ac2921 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- @@ -94,7 +94,7 @@ Triggered when you push to the repository except when pushing tags. NOTE: When more than 20 commits are pushed at once, the `commits` webhook -attribute only contains the first 20 for performance reasons. Loading +attribute only contains the newest 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. @@ -1157,7 +1157,8 @@ X-Gitlab-Event: Pipeline Hook }, "environment": { "name": "production", - "action": "start" + "action": "start", + "deployment_tier": "production" } }, { @@ -1291,7 +1292,8 @@ X-Gitlab-Event: Pipeline Hook }, "environment": { "name": "staging", - "action": "start" + "action": "start", + "deployment_tier": "staging" } } ] @@ -1394,6 +1396,7 @@ X-Gitlab-Event: Deployment Hook "object_kind": "deployment", "status": "success", "status_changed_at":"2021-04-28 21:50:00 +0200", + "deployment_id": 15, "deployable_id": 796, "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", "environment": "staging", diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index f39c34ccc0a..eda0874ac08 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Ecosystem +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 --- diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index a32a8ed8ec7..0c624d7df01 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -29,7 +29,7 @@ To let your team members organize their own workflows, use [multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue boards in the same project. - + Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: @@ -42,7 +42,7 @@ as shown in the following table: To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. - + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of @@ -227,21 +227,21 @@ and vice versa. <!-- This anchor is linked from #blocked-issues as well. --> > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** +> - [Deployed behind a feature flag](../feature_flags.md), enabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1 +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +There can be +[risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. -The work-in-progress GraphQL-based boards come with these features: +Using GraphQL-based boards gives you these +additional features: - [Edit more issue attributes](#edit-an-issue) - [View blocked issues](#blocked-issues) -The GraphQL-based Issue Board is a work in progress. Learn more about the known issues in [epic 5596](https://gitlab.com/groups/gitlab-org/-/epics/5596). ## GitLab Enterprise features for issue boards @@ -307,15 +307,16 @@ an assignee list that shows all issues assigned to a user. You can have a board with both label lists and assignee lists. To add an assignee list: -1. Select the **Add list** dropdown button. -1. Select the **Assignee list** tab. -1. Search and select the user you want to add as an assignee. +1. Select **Create list**. +1. Select **Assignee**. +1. In the dropdown, select a user. +1. Select **Add to board**. Now that the assignee list is added, you can assign or unassign issues to that user by [moving issues](#move-issues-and-lists) to and from an assignee list. To remove an assignee list, just as with a label list, click the trash icon. - + ### Milestone lists **(PREMIUM)** @@ -324,15 +325,16 @@ To remove an assignee list, just as with a label list, click the trash icon. You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. To add a milestone list: -1. Select the **Add list** dropdown button. -1. Select the **Milestone** tab. -1. Search and click the milestone. +1. Select **Create list**. +1. Select **Milestone**. +1. In the dropdown, select a milestone. +1. Select **Add to board**. Like the assignee lists, you're able to [drag issues](#move-issues-and-lists) to and from a milestone list to manipulate the milestone of the dragged issues. As in other list types, click the trash icon to remove a list. - + ### Iteration lists **(PREMIUM)** @@ -343,7 +345,7 @@ As in other list types, click the trash icon to remove a list. > - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** There can be -[risks when disabling released features](../feature_flags.md#risks-when-disabling-released-features). +[risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. You're also able to create lists of an iteration. @@ -351,7 +353,7 @@ These are lists that filter issues by the assigned iteration. To add an iteration list: 1. Select **Create list**. -1. Select the **Iteration**. +1. Select **Iteration**. 1. In the dropdown, select an iteration. 1. Select **Add to board**. @@ -378,7 +380,7 @@ To group issues by epic in an issue board: 1. Select the **Group by** dropdown button. 1. Select **Epic**. - + To edit an issue without leaving this view, select the issue card (not its title), and a sidebar appears on the right. There you can see and edit the issue's: @@ -481,17 +483,12 @@ When you use [GraphQL-based boards](#graphql-based-issue-boards), you can also e ### Create a new list -Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. +Create a new list by clicking the **Create** button in the upper right corner of the issue board. - + -Then, choose the label or user to base the new list on. The new list is inserted -at the end of the lists, before **Done**. To move and reorder lists, drag them around. - -To create a list for a label that doesn't yet exist, create the label by -choosing **Create project label** or **Create group label**. -This creates the label immediately and adds it to the dropdown. -You can now choose it to create a list. +Then, choose the label, user or milestone to base the new list on. The new list is inserted +at the end of the lists, before **Closed**. To move and reorder lists, drag them around. ### Remove a list @@ -632,7 +629,7 @@ and the target list. > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)** This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). Refer to this feature's version history for more details. You can select multiple issue cards, then drag the group to another position within the list, or to @@ -682,10 +679,9 @@ NOTE: When enabling GraphQL-based issue boards, you must also enable the [new add list form](#enable-or-disable-new-add-list-form). -GraphQL-based issue boards is not ready for production use. -It is deployed behind a feature flag that is **disabled by default** as of GitLab 13.12. +It is deployed behind a feature flag that is **enabled by default** as of GitLab 14.1. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can disable it. To enable it: diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 92c26fb654e..136e8ee2ebb 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -45,8 +45,8 @@ system note in the issue's comments. ## Indications of a confidential issue There are a few things that visually separate a confidential issue from a -regular one. In the issues index page view, you can see the eye-slash icon -next to the issues that are marked as confidential. +regular one. In the issues index page view, you can see the eye-slash (**(eye-slash)**) icon +next to the issues that are marked as confidential:  @@ -67,6 +67,12 @@ There is also an indicator on the sidebar denoting confidentiality. | :-----------: | :----------: | |  |  | +## Merge requests for confidential issues + +Although you can make issues be confidential in public projects, you cannot make +confidential merge requests. Learn how to create [merge requests for confidential issues](../merge_requests/confidential.md) +that prevent leaks of private data. + ## Permissions and access to confidential issues There are two kinds of level access for confidential issues. The general rule @@ -82,48 +88,9 @@ sees in the project's search results respectively. |:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| |  |  | -## Merge Requests for Confidential Issues - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. - -To help prevent confidential information being leaked from a public project -in the process of resolving a confidential issue, confidential issues can be -resolved by creating a merge request from a private fork. - -The created merge request targets the default branch of the private fork, -not the default branch of the public upstream project. This prevents the merge -request, branch, and commits entering the public repository, and revealing -confidential information prematurely. To make a confidential commit public, -open a merge request from the private fork to the public upstream project. - -Permissions are inherited from parent groups. Developers have the same permissions -for private forks created in the same group or in a subgroup of the original -Permissions are inherited from parent groups. When private forks are created -in the same group or subgroup as the original upstream repository, users -receive the same permissions in both projects. This inheritance ensures -Developer users have the needed permissions to both view confidential issues and -resolve them. - -### How it works - -On a confidential issue, a **Create confidential merge request** button is -available. Clicking on it opens a dropdown where you can choose to -**Create confidential merge request and branch** or **Create branch**: - -| Create confidential merge request | Create branch | -| :-------------------------------: | :-----------: | -|  |  | - -The **Project** dropdown includes the list of private forks the user is a member -of as at least a Developer and merge requests are enabled. - -Whenever the **Branch name** and **Source (branch or tag)** fields change, the -availability of the target and source branch are checked. Both branches should -be available in the selected private fork. - -By clicking the **Create confidential merge request** button, GitLab creates -the branch and merge request in the private fork. When you choose -**Create branch**, GitLab creates only the branch. +## Related links -After the branch is created in the private fork, developers can push code to -that branch to fix the confidential issue. +- [Merge requests for confidential issues](../merge_requests/confidential.md) +- [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) +- [Mark a comment as confidential](../../discussions/index.md#mark-a-comment-as-confidential) +- [Security practices for confidential merge requests](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) at GitLab diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 29adf396d4d..a9fca4f2b75 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -18,9 +18,12 @@ file, which stores tabular data in plain text. > _CSVs are a handy way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) +<!-- vale gitlab.Spelling = NO --> + CSV files can be used with any plotter or spreadsheet-based program, such as -Microsoft Excel, Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO -->, -or Google Sheets. +Microsoft Excel, Open Office Calc, or Google Sheets. + +<!-- vale gitlab.Spelling = YES --> Here are some of the uses of exporting issues as CSV files: diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index e0eb35d1e49..7f2713b81e6 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -48,7 +48,7 @@ If the requirements are not met, the **Designs** tab displays a message to the u Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. -Support for [PDF](https://gitlab.com/gitlab-org/gitlab/-/issues/32811) is planned for a future release. +Support for PDF is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/32811). ## Limitations diff --git a/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png b/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png Binary files differdeleted file mode 100644 index 1f4ad5c42bb..00000000000 --- a/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png b/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png Binary files differdeleted file mode 100644 index 7b7bd599a71..00000000000 --- a/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index ec0cdc116d6..56c219eb8c3 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -41,7 +41,7 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Upload designs to issues](design_management.md) - [Linked issues](related_issues.md) - [Cross-link issues](crosslinking_issues.md) -- [Bulk edit issues](../bulk_editing.md) +- [Bulk edit issues](../issues/managing_issues.md) - [Sort issue lists](sorting_issue_lists.md) - [Search for issues](../../search/index.md#filtering-issue-and-merge-request-lists) - [Epics](../../group/epics/index.md) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2ef12cd1240..78dc6805f2b 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -199,7 +199,7 @@ You can mention a user or a group present in your GitLab instance with `@usernam unless they have disabled all [notifications](#notifications) in their user settings. This is controlled in the [notification settings](../../profile/notifications.md). -Mentions for yourself (the current logged in user) are highlighted +Mentions for yourself (the user currently signed in) are highlighted in a different color, which allows you to quickly see which comments involve you. Avoid mentioning `@all` in issues and merge requests, as it sends an email notification diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index c570bc9612a..a2185c83f4d 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -59,7 +59,7 @@ When you're creating a new issue, these are the fields you can fill in: - Title - Description -- Checkbox to make the issue confidential +- Checkbox to make the issue [confidential](confidential_issues.md) - Assignee - Weight - [Epic](../../group/epics/index.md) diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 8987c663860..8a70b74fcc1 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -99,7 +99,7 @@ In this example: - **Administrator** is the [Owner](../../permissions.md) and member of all groups. They have inherited their role from the **demo** group. -If a user is a direct member of a project, the expiration date can be updated. If membership is inherited from a parent group, the expiration date can be updated only from the parent group itself. +If a user is a direct member of a project, the expiration date can be updated. If membership is inherited from a parent group, the expiration date can be updated only from the parent group itself. ## Remove a member from a project @@ -107,7 +107,7 @@ If a user is a direct member of a project, you can remove them. If membership is inherited from a parent group, then the member can be removed only from the parent group itself. -Prerequisite: +Prerequisites: - You must have the [Owner role](../../permissions.md). - Optional. Unassign the member from all issues and merge requests that @@ -117,7 +117,13 @@ To remove a member from a project: 1. Go to your project and select **Project information > Members**. 1. Next to the project member you want to remove, select **Remove member** **{remove}**. -1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. +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 + user has not forked the private repository. Existing forks continue to receive + changes from the upstream project. You may also want to configure your project + to prevent projects in a group + [from being forked outside their group](../../group/index.md#prevent-project-forking-outside-group). 1. Select **Remove member**. ## Filter and sort members diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 40345f33cb2..47744edd5ce 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -42,17 +42,12 @@ rules to define what types of users can approve work. Some examples of rules you - Users with specific permissions can be allowed or denied the ability to [override approval rules on a specific merge request](rules.md#edit-or-override-merge-request-approval-rules). -You can also configure additional [settings for merge request approvals](settings.md) -for more control of the level of oversight and security your project needs, including: +You can also configure: -- [Prevent users from overriding a merge request approval rule.](settings.md#prevent-overrides-of-default-approvals) -- [Reset approvals when new code is pushed.](settings.md#reset-approvals-on-push) -- Allow (or disallow) [authors and committers](settings.md) to approve their own merge requests. -- [Require password authentication when approving.](settings.md#require-authentication-for-approvals) -- [Require security team approval.](settings.md#security-approvals-in-merge-requests) - -You can configure your merge request approval rules and settings through the GitLab -user interface or with the [Merge request approvals API](../../../../api/merge_request_approvals.md). +- Additional [settings for merge request approvals](settings.md) for more control of the + level of oversight and security your project needs. +- Merge request approval rules and settings through the GitLab UI or with the + [Merge request approvals API](../../../../api/merge_request_approvals.md). ## Approve a merge request @@ -74,10 +69,10 @@ such as merge conflicts, [pending discussions](../../../discussions/index.md#pre or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). To prevent merge request authors from approving their own merge requests, -enable [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) +enable [**Prevent author approval**](settings.md#prevent-approval-by-author) in your project's settings. -If you enable [approval rule overrides](settings.md#prevent-overrides-of-default-approvals), +If you enable [approval rule overrides](settings.md#prevent-editing-approval-rules-in-merge-requests), merge requests created before a change to default approval rules are not affected. The only exceptions are changes to the [target branch](rules.md#approvals-for-protected-branches) of the rule. @@ -121,6 +116,6 @@ important to describe those, too. Think of things that may go wrong and include 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`. +Each scenario can be a third-level heading, for example, `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 82685f9101e..7e168fb239a 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -49,7 +49,7 @@ Users of GitLab Premium and higher tiers can create [additional approval rules]( Your configuration for approval rule overrides determines if the new rule is applied to existing merge requests: -- If [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, +- If [approval rule overrides](settings.md#prevent-editing-approval-rules-in-merge-requests) are allowed, changes to these default rules are not applied to existing merge requests, except for changes to the [target branch](#approvals-for-protected-branches) of the rule. - If approval rule overrides are not allowed, all changes to default rules @@ -138,10 +138,10 @@ approve in these ways: counts as one approver, and not two. - Merge request authors do not count as eligible approvers on their own merge requests by default. To change this behavior, disable the - [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) + [**Prevent author approval**](settings.md#prevent-approval-by-author) project setting. - Committers to merge requests can approve a merge request. To change this behavior, enable the - [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) + [**Prevent committers approval**](settings.md#prevent-approvals-by-users-who-add-commits) project setting. ### Code owners as eligible approvers **(PREMIUM)** @@ -201,7 +201,7 @@ on a merge request, you can either add or remove approvers: 1. Add or remove your desired approval rules. 1. Select **Save changes**. -Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals) +Administrators can change the [merge request approvals settings](settings.md#prevent-editing-approval-rules-in-merge-requests) to prevent users from overriding approval rules for merge requests. ## Configure optional approval rules **(PREMIUM)** diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 8a81ff8c94b..ebd07f30f52 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -20,37 +20,17 @@ To view or edit merge request approval settings: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -In this section of general settings, you can configure the settings described -on this page. +In this section of general settings, you can configure the following settings: -## Prevent overrides of default approvals +| Setting | Description | +| ------ | ------ | +| [Prevent approval by author](#prevent-approval-by-author) | When enabled, the author of a merge request cannot approve it. | +| [Prevent approvals by users who add commits](#prevent-approvals-by-users-who-add-commits) | When enabled, users who have committed to a merge request cannot approve it. | +| [Prevent editing approval rules in merge requests](#prevent-editing-approval-rules-in-merge-requests) | When enabled, users can't override the project's approval rules on merge requests. | +| [Require user password to approve](#require-user-password-to-approve) | Force potential approvers to first authenticate with a password. | +| [Remove all approvals when commits are added to the source branch](#remove-all-approvals-when-commits-are-added-to-the-source-branch) | When enabled, remove all existing approvals on a merge request when more changes are added to it. | -By default, users can override the approval rules you [create for a project](rules.md) -on a per-merge request basis. If you don't want users to change approval rules -on merge requests, you can disable this setting: - -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox. -1. Select **Save changes**. - -This change affects all open merge requests. - -## Reset approvals on push - -By default, an approval on a merge request remains in place, even if you add more changes -after the approval. If you want to remove all existing approvals on a merge request -when more changes are added to it: - -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Require new approvals when new commits are added to an MR** checkbox. -1. Select **Save changes**. - -Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) -However, approvals are reset if the target branch is changed. - -## Prevent authors from approving their own work **(PREMIUM)** +## Prevent approval by author **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. > - Moved to GitLab Premium in 13.9. @@ -65,14 +45,14 @@ By default, the author of a merge request cannot approve it. To change this sett Authors can edit the approval rule in an individual merge request and override this setting, unless you configure one of these options: -- [Prevent overrides of default approvals](#prevent-overrides-of-default-approvals) at +- [Prevent overrides of default approvals](#prevent-editing-approval-rules-in-merge-requests) at the project level. - *(Self-managed instances only)* Prevent overrides of default approvals [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured at the instance level, you can't edit this setting at the project or individual merge request levels. -## Prevent committers from approving their own work **(PREMIUM)** +## Prevent approvals by users who add commits **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. > - Moved to GitLab Premium in 13.9. @@ -96,7 +76,20 @@ to a merge request can approve merge requests that affect files they own. To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), read the official Git documentation for an explanation. -## Require authentication for approvals +## Prevent editing approval rules in merge requests + +By default, users can override the approval rules you [create for a project](rules.md) +on a per-merge request basis. If you don't want users to change approval rules +on merge requests, you can disable this setting: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox. +1. Select **Save changes**. + +This change affects all open merge requests. + +## Require user password to approve > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. > - Moved to GitLab Premium in 13.9. @@ -112,6 +105,20 @@ permission enables an electronic signature for approvals, such as the one define 1. Select the **Require user password for approvals** checkbox. 1. Select **Save changes**. +## Remove all approvals when commits are added to the source branch + +By default, an approval on a merge request remains in place, even if you add more changes +after the approval. If you want to remove all existing approvals on a merge request +when more changes are added to it: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Require new approvals when new commits are added to an MR** checkbox. +1. Select **Save changes**. + +Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) +However, approvals are reset if the target branch is changed. + ## Security approvals in merge requests **(ULTIMATE)** You can require that a member of your security team approves a merge request if a @@ -129,5 +136,5 @@ To learn more, see [Coverage check approval rule](../../../../ci/pipelines/setti ## Related links - [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) -- [Compliance Dashboard](../../../compliance/compliance_dashboard/index.md) +- [Compliance report](../../../compliance/compliance_report/index.md) - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index e594f8048e3..c59d5973e21 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -85,11 +85,15 @@ entire content by selecting **Show file contents**. ## Ignore whitespace changes in Merge Request diff view -If you select the **Hide whitespace changes** button, you can see the diff -without whitespace changes (if there are any). This is also working when on a -specific commit page. +Whitespace changes can make it more difficult to see the substantive changes in +a merge request. You can choose to hide or show whitespace changes: - +1. Go to your merge request, and select the **Changes** tab. +1. Above the list of changed files, select **(settings)** **Preferences** to + display the preferences menu. +1. Select or deselect **Show whitespace changes**: + +  ## Mark files as viewed @@ -140,7 +144,7 @@ Feature.disable(:local_file_reviews) > - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). Refer to this feature's version history for more details. To avoid displaying the changes that are already on target branch in the diff, diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 710638128f3..a0c3efe7143 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -37,7 +37,8 @@ request thread. It crosslinks the new commit and the existing merge request. Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. NOTE: -We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. +We only track cherry-pick executed from GitLab (both UI and API). Support for tracking cherry-picked commits through the command line +is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). ## Cherry-picking a commit @@ -62,8 +63,8 @@ git cherry-pick -m 2 7a39eb0 ### Cherry-pick into a project -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0 +> - [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. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 19302572dc9..6337fb1e87b 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -65,7 +65,7 @@ See also the Code Climate list of [Supported Languages for Maintainability](http Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example: - + ## Example configuration @@ -296,6 +296,40 @@ code_quality: - if: '$CI_COMMIT_TAG' # Run code quality job in pipelines for tags ``` +### Configure Code Quality to use a private container image registry + +> [Introduced](https://gitlab.com/gitlab-org/ci-cd/codequality/-/merge_requests/30) in 13.7. + +To reduce network time and external dependency, you can use your own +container image registry to host the Code Quality Docker images. Because of +the nested architecture of container execution, the registry prefix must +be specifically configured to be passed down into CodeClimate's subsequent +`docker pull` commands for individual engines. + +The following two variables can address all of the required image pulls: + +- `CODE_QUALITY_IMAGE`: A fully prefixed image name that can be located anywhere + accessible from your job environment. GitLab Container Registry can be used here + to host your own copy. +- `CODECLIMATE_PREFIX`: The domain of your intended container image registry. This + is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948). You must: + - Include a trailing slash (`/`). + - Not include a protocol prefix, such as `https://`. + +```yaml +include: + - template: Jobs/Code-Quality.gitlab-ci.yml + +code_quality: + variables: + CODE_QUALITY_IMAGE: "my-private-registry.local:12345/codequality:0.85.24" + CODECLIMATE_PREFIX: "my-private-registry.local:12345/" +``` + +This example is specific to GitLab Code Quality. For more general +instructions on how to configure DinD with a registry mirror, see the +relevant [documentation](../../../ci/docker/using_docker_build.md#enable-registry-mirror-for-dockerdind-service). + ## Configuring jobs using variables The Code Quality job supports environment variables that users can set to @@ -511,7 +545,7 @@ This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not have anything to compare to yet, so no information can be displayed. It only displays after future merge requests have something to compare to. -- Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. +- Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. In this situation you will see an error stating `Base pipeline codequality artifact not found`. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) CI/CD diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index fb1b7f8b9b6..3d3032bb193 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -42,7 +42,7 @@ Previously merged commits can be added, but they can't be removed due to [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/325538). This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). Refer to this feature's version history for more details. When reviewing a merge request, it helps to have more context about the changes diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md new file mode 100644 index 00000000000..6df84dd1dd1 --- /dev/null +++ b/doc/user/project/merge_requests/confidential.md @@ -0,0 +1,75 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Merge requests for confidential issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. + +Merge requests in a public repository are also public, even when the merge +request is created for a [confidential issue](../issues/confidential_issues.md). +To avoid leaking confidential information when working on a confidential issue, +create your merge request from a private fork. + +Roles are inherited from parent groups. If you create your private fork in the +same group or subgroup as the original (public) repository, developers receive +the same permissions in your fork. This inheritance ensures: + +- Developer users have the needed permissions to view confidential issues and resolve them. +- You do not need grant individual users access to your fork. + +The [security practices for confidential merge requests](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) at GitLab are available to read. + +## Create a confidential merge request + +WARNING: +To create a confidential merge request, you must create a private fork. This fork +may expose confidential information, if you create your fork in another namespace +that may have other members. + +Branches are public by default. To protect the confidentiality of your work, you +must create your changes in a private fork. + +Prerequisites: + +- You have the Owner or Maintainer role in the public repository, as you need one + of these roles to [create a subgroup](../../group/subgroups/index.md). +- You have [forked](../repository/forking_workflow.md) the public repository. +- Your fork has a **Visibility level** of _Private_. + +To create a confidential merge request: + +1. Go to the confidential issue's page. Scroll below the issue description and + select **Create confidential merge request**. +1. Select the item that meets your needs: + - *To create both a branch and a merge request,* select + **Create confidential merge request and branch**. Your merge request will + target the default branch of your fork, *not* the default branch of the + public upstream project. + - *To create only a branch,* select **Create branch**. +1. Select a **Project** to use. These projects have merge requests enabled, and + you have the Developer role (or greater) in them. +1. Provide a **Branch name**, and select a **Source (branch or tag)**. GitLab + checks whether these branches are available in your private fork, because both + branches must be available in your selected fork. +1. Select **Create**. + +If you created a branch in your private fork, users with the Developer role in the +public repository can push code to that branch in your private fork to fix the +confidential issue. + +As your merge request targets your private fork, not the public upstream project, +your branch, merge request, and commits do not enter the public repository. This +prevents prematurely revealing confidential information. + +To make a confidential commit public, open a merge request from the private fork +to the public upstream project. + +## Related links + +- [Confidential issues](../issues/confidential_issues.md) +- [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) +- [Mark a comment as confidential](../../discussions/index.md#mark-a-comment-as-confidential) +- [Security practices for confidential merge requests](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) at GitLab diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 0d56fbc89b8..918f9830edc 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -105,7 +105,7 @@ fork from its upstream project. Go to **Settings > Advanced Settings** and For more information, [see the forking workflow documentation](../repository/forking_workflow.md). -## By sending an email **(FREE SELF)** +## By sending an email > The format of the generated email address changed in GitLab 11.7. The earlier format is still supported so existing aliases diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 5556e54f875..6dbbab316a0 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -36,8 +36,8 @@ The following table shows what attributes will be present in the CSV. | Merged User | Full name of the merged user | | Merged Username | Username of the merge user, with the @ symbol omitted | | Milestone ID | ID of the merge request milestone | -| Created At (UTC) | Formatted as YYYY-MM-DD HH:MM:SS | -| Updated At (UTC) | Formatted as YYYY-MM-DD HH:MM:SS | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | ## Limitations diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 15ab2d9c8e2..6d8a128c39f 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -19,7 +19,7 @@ that it believes to be relevant to the input files. `tff` is designed for Ruby on Rails projects, so the `Verify/FailFast` template is configured to run when changes to Ruby files are detected. By default, it runs in -the [`.pre` stage](../../../ci/yaml/index.md#pre-and-post) of a GitLab CI/CD pipeline, +the [`.pre` stage](../../../ci/yaml/index.md#stage-pre) of a GitLab CI/CD pipeline, before all other stages. ## Example use case diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index ce39f39f0a1..46fc3ec141d 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -129,7 +129,7 @@ To request a review of a merge request, expand the **Reviewers** select box in the right-hand sidebar. Search for the users you want to request a review from. When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. -To learn more, read [Review and manage merge requests](reviews/index.md). +To learn more, read [Review a merge request](reviews/index.md). ### Merge requests to close issues @@ -140,7 +140,7 @@ when merged. If the issue is [confidential](../issues/confidential_issues.md), you may want to use a different workflow for -[merge requests for confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) +[merge requests for confidential issues](confidential.md) to prevent confidential information from being exposed. ### Deleting the source branch diff --git a/doc/user/project/merge_requests/img/checkout_button.png b/doc/user/project/merge_requests/img/checkout_button.png Binary files differdeleted file mode 100644 index 9850795c9b4..00000000000 --- a/doc/user/project/merge_requests/img/checkout_button.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png Binary files differdeleted file mode 100644 index 0fcdc252735..00000000000 --- a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png Binary files differdeleted file mode 100644 index da7d4115bd9..00000000000 --- a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14_2.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14_2.png Binary files differnew file mode 100644 index 00000000000..c1e9aad24ac --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14_2.png diff --git a/doc/user/project/merge_requests/img/merge_request_diff.png b/doc/user/project/merge_requests/img/merge_request_diff.png Binary files differdeleted file mode 100644 index 9c5488cb207..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_diff.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_diff_v14_2.png b/doc/user/project/merge_requests/img/merge_request_diff_v14_2.png Binary files differnew file mode 100644 index 00000000000..de534f17bf1 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_diff_v14_2.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index fa90cf524ec..6c2f07d7012 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -119,7 +119,7 @@ For a software developer working in a team: 1. Pushes a commit with their final review. 1. [Approves the merge request](approvals/index.md). 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). -1. Your changes get deployed to production with [manual actions](../../../ci/yaml/index.md#whenmanual) for GitLab CI/CD. +1. Your changes get deployed to production with [manual jobs](../../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. For a web developer writing a webpage for your company's website: @@ -135,6 +135,6 @@ For a web developer writing a webpage for your company's website: ## Related topics - [Create a merge request](creating_merge_requests.md) -- [Review and manage merge requests](reviews/index.md) +- [Review a merge request](reviews/index.md) - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md deleted file mode 100644 index 42de04085a9..00000000000 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'approvals/index.md' -remove_date: '2021-07-27' ---- - -This document was moved to [another location](approvals/index.md). - -<!-- This redirect file can be deleted after <2021-07-27>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md deleted file mode 100644 index b32dce0b230..00000000000 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'reviews/index.md' -remove_date: '2021-08-03' ---- - -This document was moved to [another location](reviews/index.md). - -<!-- This redirect file can be deleted after <2021-08-03>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/reviews/img/pending_review_comment.png b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png Binary files differdeleted file mode 100644 index 70a66b3f4f0..00000000000 --- a/doc/user/project/merge_requests/reviews/img/pending_review_comment.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 16267e13fd5..61cd0d25aaf 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Review and manage merge requests **(FREE)** +# Review a merge request **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. @@ -16,47 +16,6 @@ to propose changes. Your team leaves [comments](../../../discussions/index.md), makes [code suggestions](suggestions.md) you can accept from the user interface. When your work is reviewed, your team members can choose to accept or reject it. -## Bulk edit merge requests at the project level - -Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. - -When bulk editing merge requests in a project, you can edit the following attributes: - -- Status (open/closed) -- Assignee -- Milestone -- Labels -- Subscriptions - -To update multiple project merge requests at the same time: - -1. In a project, go to **Merge requests**. -1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with - editable fields. -1. Select the checkboxes next to each merge request you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Bulk edit merge requests at the group level - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. - -Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. - -When bulk editing merge requests in a group, you can edit the following attributes: - -- Milestone -- Labels - -To update multiple group merge requests at the same time: - -1. In a group, go to **Merge requests**. -1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with - editable fields. -1. Select the checkboxes next to each merge request you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - ## Review a merge request > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. @@ -204,12 +163,51 @@ Multiline comments display the comment's line numbers above the body of the comm  +## Bulk edit merge requests at the project level + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions + +To update multiple project merge requests at the same time: + +1. In a project, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the group level + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a group, you can edit the following attributes: + +- Milestone +- Labels + +To update multiple group merge requests at the same time: + +1. In a group, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + ## Associated features These features are associated with merge requests: -- [Bulk editing merge requests](../../../project/bulk_editing.md): - Update the attributes of multiple merge requests simultaneously. - [Cherry-pick changes](../cherry_pick_changes.md): Cherry-pick any commit in the UI by selecting the **Cherry-pick** button in a merged merge requests or a commit. - [Fast-forward merge requests](../fast_forward_merge.md): diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 47c7e208f2d..2842c084bc5 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -61,7 +61,7 @@ meaningful commit messages and: ## Enabling squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed -on the merge request form. Users can select or clear the check box when they +on the merge request form. Users can select or clear the checkbox when they create the merge request:  diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 70e2d718406..1576b639a76 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -11,9 +11,6 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/statu > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - You can create a status check that sends merge request data to third-party tools. When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows can then update the status of merge requests from outside of GitLab. 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 8c77714a2de..51f1ec96c22 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 @@ -139,7 +139,7 @@ If you're using Cloudflare, check > - **Do not** use a CNAME record if you want to point your `domain.com` to your GitLab Pages site. Use an `A` record instead. > - **Do not** add any special chars after the default Pages - domain. E.g., don't point `subdomain.domain.com` to + domain. For example, don't point `subdomain.domain.com` to or `namespace.gitlab.io/`. Some domain hosting providers may request a trailing dot (`namespace.gitlab.io.`), though. > - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/releases/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017. > - GitLab Pages IP on GitLab.com [has changed](https://about.gitlab.com/blog/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains) @@ -315,6 +315,6 @@ important to describe those, too. Think of things that may go wrong and include 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`. +Each scenario can be a third-level heading, for example, `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/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 f0a922ff390..ee1004a3416 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 @@ -99,6 +99,6 @@ important to describe those, too. Think of things that may go wrong and include 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`. +Each scenario can be a third-level heading, for example, `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index 48412f48c12..5b7f6454ef7 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -32,8 +32,11 @@ nor credit card transactions, then why do we need secure connections? Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" security measure, necessary just for big companies like banks and shopping sites with financial transactions. + <!-- vale gitlab.Spelling = NO --> + Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): + <!-- vale gitlab.rulename = YES --> > _We've since come to realize that HTTPS is important for almost all websites. It's important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn't want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We've also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 4ff651891b2..a4e94c03e86 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -30,7 +30,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#default-branch-protection). +[Admin Area](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches). ## Configure a protected branch @@ -179,8 +179,7 @@ When enabled, members who are can push to this branch can also force push. > - [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. -You can require at least one approval by a [Code Owner](code_owners.md) to a file changed by the -merge request. +For a protected branch, you can require at least one approval by a [Code Owner](code_owners.md). To protect a new branch and enable Code Owner's approval: @@ -201,6 +200,16 @@ When enabled, all merge requests for these branches require approval by a Code Owner per matched rule before they can be merged. Additionally, direct pushes to the protected branch are denied if a rule is matched. +Any user who is not specified in the `CODEOWNERS` file cannot push +changes for the specified files or paths, unless they are specifically allowed to. +You don't have to restrict developers from pushing directly to the +protected branch. Instead, you can restrict pushing to certain files where a review by +Code Owners is required. + +In [GitLab Premium 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35097), users and groups +who are allowed to push to protected branches do not need a merge request to merge their feature branches. +Thus, they can skip merge request approval rules, Code Owners included. + ## Run pipelines on protected branches The permission to merge or push to protected branches defines diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index d8d464ce6d8..683496b4a9b 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -94,6 +94,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | | `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/334045). | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | | `/spend <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | | `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 3a25b148fdf..76b300bdd57 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -102,7 +102,7 @@ release tag. When the `released_at` date and time has passed, the badge is autom > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. Asset link editing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. -Only users with at least the Developer can edit releases. +Only users with at least the Developer role can edit releases. Read more about [Release permissions](#release-permissions). To edit the details of a release: @@ -181,7 +181,7 @@ 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 the **New release** check box. +1. Select the **New release** checkbox. 1. Close the dialog box to save. ## Prevent unintentional releases by setting a deploy freeze @@ -589,25 +589,6 @@ As an example of release permission control, you can allow only to create, update, and delete releases by protecting the tag with a wildcard (`*`), and set **Maintainer** in the **Allowed to create** column. -#### Enable or disable protected tag evaluation on releases **(FREE SELF)** - -Protected tag evaluation on release permissions is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:evalute_protected_tag_for_release_permissions) -``` - -To disable it: - -```ruby -Feature.disable(:evalute_protected_tag_for_release_permissions) -``` - ## Release Command Line > [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. @@ -631,6 +612,18 @@ These metrics include: - Total number of releases in the group - Percentage of projects in the group that have at least one release +## Working example project + +The Guided Exploration project [Utterly Automated Software and Artifact Versioning with GitVersion](https://gitlab.com/guided-explorations/devops-patterns/utterly-automated-versioning) demonstrates: + +- Using GitLab releases. +- Using the GitLab `release-cli`. +- Creating a generic package. +- Linking the package to the release. +- Using a tool called [GitVersion](https://gitversion.net/) to automatically determine and increment versions for complex repositories. + +You can copy the example project to your own group or instance for testing. More details on what other GitLab CI patterns are demonstrated are available at the project page. + ## Troubleshooting ### Getting `403 Forbidden` or `Something went wrong while creating a new release` errors when creating, updating or deleting releases and their assets diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 2f1171a7d4f..12fd7389f21 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -37,10 +37,10 @@ the [Git commands you need](#update-the-default-branch-name-in-your-repository) To update the default branch name for an individual [project](../../index.md): -1. Sign in to GitLab as a user with [Administrator](../../../permissions.md) permissions. +1. Sign in to GitLab as a user with the [Administrator](../../../permissions.md) role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. -1. (Optional) Select the **Auto-close referenced issues on default branch** check box to close +1. (Optional) Select the **Auto-close referenced issues on default branch** checkbox to close issues when a merge request [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). 1. Select **Save changes**. @@ -168,6 +168,7 @@ current default branch, instead of displaying the "not found" page. ## Resources +- [Configure a default branch for your wiki](../../wiki/index.md) - [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) on the Git mailing list - [March 2021 blog post: The new Git default branch name](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/) diff --git a/doc/user/project/repository/img/csv_file_rendered_as_table_v14_1.png b/doc/user/project/repository/img/csv_file_rendered_as_table_v14_1.png Binary files differindex 0f9b623e7b4..f1dd8dc920b 100644 --- a/doc/user/project/repository/img/csv_file_rendered_as_table_v14_1.png +++ b/doc/user/project/repository/img/csv_file_rendered_as_table_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_branch_dropdown.png b/doc/user/project/repository/img/web_editor_new_branch_dropdown.png Binary files differdeleted file mode 100644 index a6edea1fcce..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_dropdown.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png Binary files differnew file mode 100644 index 00000000000..20d76797977 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v12_6.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v12_6.png Binary files differdeleted file mode 100644 index 1ef210240d4..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png Binary files differnew file mode 100644 index 00000000000..fae0fc1425b --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png Binary files differnew file mode 100644 index 00000000000..150ec3ebf90 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v_12_6.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v_12_6.png Binary files differdeleted file mode 100644 index 02cadd5de4c..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v_12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_page.png b/doc/user/project/repository/img/web_editor_new_branch_page.png Binary files differdeleted file mode 100644 index 7bb8b9e29e3..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_page.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png Binary files differnew file mode 100644 index 00000000000..cba15631fa8 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_directory_dialog.png b/doc/user/project/repository/img/web_editor_new_directory_dialog.png Binary files differdeleted file mode 100644 index 590989c360e..00000000000 --- a/doc/user/project/repository/img/web_editor_new_directory_dialog.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png b/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png Binary files differnew file mode 100644 index 00000000000..1f7a6263d9a --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_directory_dropdown.png b/doc/user/project/repository/img/web_editor_new_directory_dropdown.png Binary files differdeleted file mode 100644 index efa3087fc0c..00000000000 --- a/doc/user/project/repository/img/web_editor_new_directory_dropdown.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png Binary files differnew file mode 100644 index 00000000000..326605baaab --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_file_dropdown.png b/doc/user/project/repository/img/web_editor_new_file_dropdown.png Binary files differdeleted file mode 100644 index b40fb1ce58d..00000000000 --- a/doc/user/project/repository/img/web_editor_new_file_dropdown.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png Binary files differnew file mode 100644 index 00000000000..4a4c1f8cd11 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_file_editor.png b/doc/user/project/repository/img/web_editor_new_file_editor.png Binary files differdeleted file mode 100644 index d0bcc69bf63..00000000000 --- a/doc/user/project/repository/img/web_editor_new_file_editor.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png b/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png Binary files differnew file mode 100644 index 00000000000..3c568e304b2 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_first_file.png b/doc/user/project/repository/img/web_editor_template_dropdown_first_file.png Binary files differdeleted file mode 100644 index a4440ec3cc9..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_first_file.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png b/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png Binary files differnew file mode 100644 index 00000000000..ecc4d8e8716 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license.png b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license.png Binary files differdeleted file mode 100644 index afd44d78959..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png Binary files differnew file mode 100644 index 00000000000..d0bdefaa437 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_upload_file_dialog.png b/doc/user/project/repository/img/web_editor_upload_file_dialog.png Binary files differdeleted file mode 100644 index c0e9a99aa61..00000000000 --- a/doc/user/project/repository/img/web_editor_upload_file_dialog.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png b/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png Binary files differnew file mode 100644 index 00000000000..632f591e25a --- /dev/null +++ b/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_upload_file_dropdown.png b/doc/user/project/repository/img/web_editor_upload_file_dropdown.png Binary files differdeleted file mode 100644 index c80a9ae4b3d..00000000000 --- a/doc/user/project/repository/img/web_editor_upload_file_dropdown.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png Binary files differnew file mode 100644 index 00000000000..1b2fa59726a --- /dev/null +++ b/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png 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 323a2efce76..81429ea5384 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,6 +13,8 @@ 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 @@ -21,7 +23,7 @@ over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and WARNING: Rewriting repository history is a destructive operation. Make sure to back up your repository before you begin. The best way back up a repository is to -[export the project](../settings/import_export.md#exporting-a-project-and-its-data). +[export the project](../settings/import_export.md#export-a-project-and-its-data). ## Purge files from repository history @@ -42,7 +44,7 @@ To purge files from a GitLab repository: using a supported package manager or from source. 1. Generate a fresh [export from the - project](../settings/import_export.html#exporting-a-project-and-its-data) and download it. + project](../settings/import_export.html#export-a-project-and-its-data) and download it. This project export contains a backup copy of your repository *and* refs we can use to purge files from your repository. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 71bece03a33..76eae58b431 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -62,8 +62,8 @@ For an existing project, you can set up push mirroring as follows: 1. In the **Mirror direction** dropdown, select **Push**. 1. Select an authentication method from the **Authentication method** dropdown. You can authenticate with either a password or an [SSH key](#ssh-authentication). -1. Select the **Only mirror protected branches** check box, if necessary. -1. Select the **Keep divergent refs** check box, if desired. +1. Select the **Only mirror protected branches** checkbox, if necessary. +1. Select the **Keep divergent refs** checkbox, if desired. 1. Select **Mirror repository** to save the configuration. When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the @@ -92,19 +92,18 @@ You can also create and modify project push mirrors through the > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. -By default, if any ref on the remote mirror has diverged from the local -repository, the *entire push* fails, and no updates occur. +By default, if any ref (branch or tag) on the remote mirror has diverged from the local repository, the local differences are forced to the remote. -For example, if a repository has `main`, `develop`, and `stable` branches that +For example, if a repository has `main` and `develop` branches that have been mirrored to a remote, and then a new commit is added to `develop` on -the mirror, the next push attempt fails, leaving `main` and `stable` -out-of-date despite not having diverged. No change on any branch can be mirrored -until the divergence is resolved. +the remote mirror. The next push updates all of the references on the remote mirror to match +the local repository, and the new commit added to the remote `develop` branch is lost. With the **Keep divergent refs** option enabled, the `develop` branch is -skipped, allowing `main` and `stable` to be updated. The mirror status -reflects that `develop` has diverged and was skipped, and be marked as a failed -update. +skipped, causing only `main` to be updated. The mirror status +reflects that `develop` has diverged and was skipped, and be marked as a +failed update. Refs that exist in the mirror repository but not in the local +repository are left untouched. NOTE: After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md). diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index cca8d770115..8074f311e5f 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -17,7 +17,7 @@ dropdown menu. From a project's files page, click the '+' button to the right of the branch selector. Choose **New file** from the dropdown. - + Enter a filename in the **Filename** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field @@ -27,7 +27,7 @@ request after you commit the changes. When you are satisfied with your new file, click **Commit Changes** at the bottom. - + ### Shortcuts @@ -39,12 +39,12 @@ as the Web IDE. For details, read the documentation for [Command Palette](../web When starting a new project, there are some common files that the new project might need. GitLab displays a message to help you: - + When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown displays to provide you a template that may be suitable for your project: - + The license, changelog, contribution guide, or `.gitlab-ci.yml` file can also be added through a button on the project page. In this example, the license @@ -86,7 +86,7 @@ this case, you need to upload a file. From a project's files page, click the '+' button to the right of the branch selector. Choose **Upload file** from the dropdown: - + After the upload dialog pops up, there are two ways to upload your file. Either drag and drop a file on the popup or use the **click to upload** link. After you @@ -95,7 +95,7 @@ select a file to upload, a file preview displays. Enter a commit message, choose a branch, and click **Upload file** when you are ready. - + ## Create a directory @@ -105,12 +105,12 @@ directory. From a project's files page, click the plus button (`+`) to the right of the branch selector. Choose **New directory** from the dropdown. - + In the new directory dialog, enter a directory name, a commit message, and choose the target branch. Click **Create directory** to finish. - + ## Create a new branch @@ -137,11 +137,11 @@ To make this button appear, one possible workaround is to After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks. - + This dropdown contains the options **Create merge request and branch** and **Create branch**. - + After selecting one of these options, a new branch or branch and merge request is created based on your project's [default branch](branches/default.md). @@ -172,7 +172,7 @@ request, you can create a new branch upfront. 1. From a project's files page, choose **New branch** from the dropdown. -  +  1. Enter a new **Branch name**. 1. (Optional) Change the **Create from** field to choose which branch, tag, or @@ -180,7 +180,7 @@ request, you can create a new branch upfront. start typing an existing branch or tag. 1. Click **Create branch** to return to the file browser on this new branch. -  +  You can now make changes to any files, as needed. When you're ready to merge the changes back to your [default branch](branches/default.md), you can use the widget at the top of the screen. @@ -214,7 +214,7 @@ When creating or uploading a new file or creating a new directory, you can trigger a new merge request rather than committing directly to your default branch: 1. Enter a new branch name in the **Target branch** field. -1. GitLab displays the **Start a new merge request with these changes** check box. +1. GitLab displays the **Start a new merge request with these changes** checkbox. 1. Commit your changes, and GitLab redirects you to a new merge request form.  diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index c89f3a267ba..7c115734345 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -7,6 +7,8 @@ type: concepts, howto # Signing commits and tags with X.509 **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. + [X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). Personal X.509 certificates are used for authentication or signing purposes @@ -37,6 +39,20 @@ Self signed certificates without `authorityKeyIdentifier`, recommend using certificates from a PKI that are in line with [RFC 5280](https://tools.ietf.org/html/rfc5280). +## Limitations + +- If you have more than one email in the Subject Alternative Name list in + your signing certificate, + [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). +- The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the + signing certificate + [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). + If your SKI is shorter, commits will not show as verified in GitLab, and + short subject key identifiers may also + [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), + such as 'An error occurred while loading commit signatures' and + `HTTP 422 Unprocessable Entity` errors. + ## Obtaining an X.509 key pair If your organization has Public Key Infrastructure (PKI), that PKI provides diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 4ac1113152c..3be3b1682bb 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -68,7 +68,7 @@ To edit a requirement: 1. From the requirements list, select the **Edit** icon (**{pencil}**). 1. Update the title and description in text input field. You can also mark a - requirement as satisfied in the edit form by using the check box **Satisfied**. + requirement as satisfied in the edit form by using the checkbox **Satisfied**. 1. Select **Save changes**. ## Archive a requirement @@ -295,8 +295,10 @@ To export requirements: ### Exported CSV file format <!-- vale gitlab.Spelling = NO --> + You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel, OpenOffice Calc, or Google Sheets. + <!-- vale gitlab.Spelling = YES --> The exported CSV file contains the following headers: diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index d5fdb86c9b0..a0718e875d7 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -32,8 +32,8 @@ To set up a project import/export: Note the following: -- Before you can import a project, you need to export the data first. - See [Exporting a project and its data](#exporting-a-project-and-its-data) +- Before you can import a project, you must export the data first. + See [Export a project and its data](#export-a-project-and-its-data) for how you can export a project through the UI. - Imports from a newer version of GitLab are not supported. The Importing GitLab version must be greater than or equal to the Exporting GitLab version. @@ -42,7 +42,7 @@ Note the following: - Exports are generated in your configured `shared_path`, a temporary shared directory, and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. - Group members are exported as project members, as long as the user has - maintainer or administrator access to the group where the exported project lives. + a maintainer or administrator role in the group where the exported project lives. - Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and @@ -51,10 +51,10 @@ Note the following: possible through a [professional services engagement](https://about.gitlab.com/services/migration/). - If an imported project contains merge requests originating from forks, then new branches associated with such merge requests are created - within a project during the import/export. Thus, the number of branches + in a project during the import/export. Thus, the number of branches in the exported project could be bigger than in the original project. - Deploy keys allowed to push to protected branches are not exported. Therefore, - you need to recreate this association by first enabling these deploy keys in your + you must recreate this association by first enabling these deploy keys in your imported project and then updating your protected branches accordingly. ## Version history @@ -141,7 +141,7 @@ NOTE: For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. -## Exporting a project and its data +## Export a project and its data Full project export functionality is limited to project maintainers and owners. You can configure such functionality through [project settings](index.md): @@ -156,18 +156,22 @@ To export a project and its data, follow these steps:  -1. Once the export is generated, you should receive an email with a link to +1. After the export is generated, you should receive an email with a link to download the file:  1. Alternatively, you can come back to the project settings and download the - file from there, or generate a new export. Once the file is available, the page + file from there, or generate a new export. After the file is available, the page should show the **Download export** button:  -## Importing the project +## Import the project + +WARNING: +Only import projects from sources you trust. If you import a project from an untrusted source, it +may be possible for an attacker to steal your sensitive data. 1. The GitLab project import feature is the first import option when creating a new project. Click on **GitLab export**: @@ -209,4 +213,60 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 projects per minute | -Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. +GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. + +## Troubleshooting + +### Import workaround for large repositories + +[Maximum import size limitations](#import-the-project) +can prevent an import from being successful. +If changing the import limits is not possible, +the following local workflow can be used to temporarily +reduce the repository size for another import attempt. + +1. Create a temporary working directory from the export: + + ```shell + EXPORT=<filename-without-extension> + + mkdir "$EXPORT" + tar -xf "$EXPORT".tar.gz --directory="$EXPORT"/ + cd "$EXPORT"/ + git clone project.bundle + + # Prevent interference with recreating an importable file later + mv project.bundle ../"$EXPORT"-original.bundle + mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz + ``` + +1. To reduce the repository size, + [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) + or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) + to reduce the number of commits. + + ```shell + # Reduce the .git/objects/pack/ file size + cd project + git reflog expire --expire=now --all + git gc --prune=now --aggressive + + # Prepare recreating an importable file + git bundle create ../project.bundle <default-branch-name> + cd .. + mv project/ ../"$EXPORT"-project + cd .. + + # Recreate an importable file + tar -czf "$EXPORT"-smaller.tar.gz --directory="$EXPORT"/ . + ``` + +1. Import this new, smaller file into GitLab. +1. In a full clone of the original repository, + use `git remote set-url origin <new-url> && git push --force --all` + to complete the import. +1. Update the imported repository's + [branch protection rules](../protected_branches.md) and + its [default branch](../repository/branches/default.md), and + delete the temporary, `smaller-…` branch, and + the local, temporary data. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index d79d9f5b9dc..66fdace81ba 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -30,32 +30,39 @@ Adjust your project's name, description, avatar, [default branch](../repository/  -The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown). +You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and +[line-breaks](../../markdown.md#line-breaks) to add more context to the project description. #### Compliance frameworks **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. -You can create a framework label to identify that your project has certain compliance requirements or needs additional oversight. +You can create a framework label to identify that your project has certain compliance requirements +or needs additional oversight. -Group owners can create, edit and delete compliance frameworks by going to **Settings** > **General** and expanding the **Compliance frameworks** section. -Compliance frameworks created can then be assigned to any number of projects via the project settings page inside the group or subgroups. +Group owners can create, edit, and delete compliance frameworks: + +1. Go to the group's **Settings** > **General**. +1. Expand the **Compliance frameworks** section. + +Compliance frameworks created can then be assigned to any number of projects using: + +- The project settings page inside the group or subgroups. +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the + [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). NOTE: -Attempting to create compliance frameworks on subgroups via GraphQL will cause the framework to be created on the root ancestor if the user has the correct permissions. -The web UI presents a read-only view to discourage this behavior. +Creating compliance frameworks on subgroups with GraphQL causes the framework to be +created on the root ancestor if the user has the correct permissions. The GitLab UI presents a +read-only view to discourage this behavior. #### Compliance pipeline configuration **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9. -> - [Deployed behind a feature flag](../../feature_flags.md). +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. -> - Enabled on GitLab.com. -> - Recommended for production use. - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. Group owners can use the compliance pipeline configuration to define compliance requirements such as scans or tests, and enforce them in individual projects. @@ -135,6 +142,7 @@ audit trail: include: # Execute individual project's configuration project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch. ``` ##### Ensure compliance jobs are always run @@ -227,7 +235,7 @@ Some features depend on others: - Metrics dashboard access requires reading both project environments and deployments. Users with access to the metrics dashboard can also access environments and deployments. -#### Disabling the CVE ID request button +#### Disabling the CVE ID request button **(FREE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. @@ -263,7 +271,7 @@ Enable [Service Desk](../service_desk.md) for your project to offer customer sup ### Export project -Learn how to [export a project](import_export.md#importing-the-project) in GitLab. +Learn how to [export a project](import_export.md#import-the-project) in GitLab. ### Advanced settings @@ -296,7 +304,7 @@ available in project listings. Only project owners and administrators have the To find an archived project: -1. Sign in to GitLab as a user with project owner or administrator permissions. +1. Sign in to GitLab as the project owner or a user with the Administrator role. 1. If you: - Have the project's URL, open the project's page in your browser. - Don't have the project's URL: @@ -362,6 +370,14 @@ NOTE: GitLab administrators can use the administration interface to move any project to any namespace if needed. +##### Transferring a GitLab.com project to a different subscription tier + +When you transfer a project from a namespace that's licensed for GitLab SaaS Premium or Ultimate to Free, some data related to the paid features is deleted. + +For example, [project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked, and +[pipeline subscriptions](../../../ci/pipelines/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) +and [test cases](../../../ci/test_cases/index.md) are deleted. + #### Delete a project You can mark a project to be deleted. @@ -409,8 +425,10 @@ To immediately delete a project marked for deletion: 1. In the "Permanently delete project" section, select **Delete project**. 1. Confirm the action when asked to. -Your project, its repository, and all related resources, including issues and merge requests, -are deleted. +The following are deleted: + +- Your project and its repository. +- All related resources including issues and merge requests. #### Restore a project **(PREMIUM)** diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 5e045ee2455..643042cb96a 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -94,3 +94,62 @@ the following table. You may enable or disable project access token creation for all projects in a group in **Group > Settings > General > Permissions, LFS, 2FA > Allow project access token creation**. Even when creation is disabled, you can still use and revoke existing project access tokens. This setting is available only on top-level groups. + +## Group access token workaround **(FREE SELF)** + +NOTE: +This section describes a workaround and is subject to change. + +Group access tokens let you use a single token to: + +- Perform actions at the group level. +- Manage the projects within the group. +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate + with Git over HTTPS. + +We don't support group access tokens in the GitLab UI, though GitLab self-managed +administrators can create them using the [Rails console](../../../administration/operations/rails_console.md). + +<div class="video-fallback"> + For a demo of the group access token workaround, see <a href="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/W2fg1P1xmU0" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +### Create a group access token + +To create a group access token, run the following in a Rails console: + +```ruby +admin = User.find(1) # group admin +group = Group.find(109) # the group you want to create a token for +bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute # create the group bot user +# for further group access tokens, the username should be group_#{group.id}_bot#{bot_count}, e.g. group_109_bot2, and their email should be group_109_bot2@example.com +bot.confirm # confirm the bot +group.add_user(bot, :maintainer) # add the bot to the group at the desired access level +token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') # give it a PAT +gtoken = token.token # get the token value +``` + +Test if the generated group access token works: + +1. Pass the group access token in the `PRIVATE-TOKEN` header to GitLab REST APIs. For example: + + - [Create an epic](../../../api/epics.md#new-epic) on the group. + - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) + in one of the group's projects. + - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. + +1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) + using HTTPS. + +### Revoke a group access token + +To revoke a group access token, run the following in a Rails console: + +```ruby +bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke +token = bot.personal_access_tokens.last # the token you want to revoke +token.revoke! +``` diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 29aedb33003..2b901ddc17b 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -14,8 +14,8 @@ requests in GitLab. Use time tracking for these tasks: - Record the time spent working on an issue or a merge request. -- Add an estimate of the amount of time needed to complete an issue or a merge - request. +- Add or update an estimate of the total time to complete an issue or a merge +request. - View a breakdown of time spent working on an issue or a merge request. You don't have to indicate an estimate to enter the time spent, and vice versa. @@ -45,9 +45,14 @@ For example, if you need to enter an estimate of 1 month, 2 weeks, 3 days, 4 hou type `/estimate 1mo 2w 3d 4h 5m`. Check the [time units you can use](#configuration). -Every time you enter a new time estimate, any previous time estimates are -overridden by this new value. There should only be one valid estimate in an -issue or a merge request. +The estimate is designed to show the total estimated time. The estimated +time remaining is automatically calculated and displayed when hovering over +the time tracking information in the right sidebar. + + + +An issue or a merge request can have only one estimate. Every time you enter a +new time estimate, it overwrites the previous value. To remove an estimation entirely, use `/remove_estimate`. @@ -125,4 +130,7 @@ With this option enabled, `75h` is displayed instead of `1w 4d 3h`. - [Connection](../../api/graphql/reference/index.md#timelogconnection) - [Edge](../../api/graphql/reference/index.md#timelogedge) - [Fields](../../api/graphql/reference/index.md#timelog) + - [Timelogs](../../api/graphql/reference/index.md#querytimelogs) - [Group timelogs](../../api/graphql/reference/index.md#grouptimelogs) + - [Project Timelogs](../../api/graphql/reference/index.md#projecttimelogs) + - [User Timelogs](../../api/graphql/reference/index.md#usertimelogs) diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 722505304c0..160c2314ded 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -234,16 +234,29 @@ different branch. > - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. > - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. +> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in [GitLab Free](https://about.gitlab.com/pricing/) 14.3 -When you edit Markdown files in the Web IDE, you can preview your changes by -clicking the **Preview Markdown** tab above the file editor. The Markdown preview -supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). +To edit Markdown files in the Web IDE: -You can also upload any local images by pasting them directly in the Markdown file. +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. 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**. + +When editing, you can upload local images by pasting them directly in the Markdown file. The image is uploaded to the same directory and is named `image.png` by default. If another file already exists with the same name, a numeric suffix is automatically added to the filename. +There are two ways to preview Markdown content in the Web IDE: + +1. At the top of the file's tab, select **Preview Markdown** to preview the formatting + in your file. You can't edit the file in this view. + 1. To add more changes to the file, select **Edit**. +1. Right-click or use the keyboard shortcut `Command/Control + Shift + P` and + select **Preview Markdown** to toggle a live Markdown preview panel. + ## Live Preview > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. @@ -362,6 +375,8 @@ terminal: After the terminal has started, the console is displayed and we could access the project repository files. +When you use the image keyword, a container with the specified image is created. If you specify an image, it has no effect. This is the case when you use the [shell executor](https://docs.gitlab.com/runner/executors/shell.html). + **Important**. The terminal job is branch dependent. This means that the configuration file used to trigger and configure the terminal is the one in the selected branch of the Web IDE. @@ -452,7 +467,7 @@ when: The Web IDE has a few limitations: -- Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, please note that the user is limited to having only one +- Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, the user is limited to having only one active terminal at a time. - LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 527db38c980..0507b6b78ca 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -29,6 +29,21 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se  +## Configure a default branch for your wiki + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221159) in GitLab 14.1. + +The default branch for your wiki repository depends on your version of GitLab: + +- *GitLab versions 14.1 and later:* Wikis inherit the + [default branch name](../repository/branches/default.md) configured for + your instance or group. If no custom value is configured, GitLab uses `main`. +- *GitLab versions 14.0 and earlier:* GitLab uses `master`. + +For any version of GitLab, you can +[rename this default branch](../repository/branches/default.md#update-the-default-branch-name-in-your-repository) +for previously created wikis. + ## Create the wiki home page When a wiki is created, it is empty. On your first visit, create the landing page @@ -210,7 +225,7 @@ A `_sidebar` example, formatted with Markdown: - [Sidebar](_sidebar) ``` -Support for displaying a generated table of contents with a custom side navigation is planned. +Support for displaying a generated table of contents with a custom side navigation is being considered. ## Enable or disable a project wiki @@ -238,6 +253,14 @@ Group wikis can be edited by members with the [Developer role](../../permissions and above. Group wiki repositories can be moved using the [Group repository storage moves API](../../../api/group_repository_storage_moves.md). +### Export a group wiki **(PREMIUM)** + +Users with the [Owner role](../../permissions.md) in a group can +[import and export group wikis](../../group/settings/import_export.md) when importing +or exporting a group. + +Content created in a group wiki is not deleted when an account is downgraded or a GitLab trial ends. + ## Link an external wiki To add a link to an external wiki from a project's left sidebar: diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 08b63bfed5f..77dd44e5c7f 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -22,7 +22,7 @@ projects with the largest number of comments in the past month, click **Trending NOTE: By default, `/explore` is visible to unauthenticated users. However, if the -[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels) +[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) is restricted, `/explore` is visible only to signed-in users. ## Create a project @@ -148,39 +148,44 @@ To use a custom project template on the **New project** page: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. -When you create a new repository locally, instead of manually creating a new project in GitLab -and then [cloning the repository](../../gitlab-basics/start-using-git.md#clone-a-repository) -locally, you can directly push it to GitLab to create the new project, all without leaving -your terminal. If you have access rights to the associated namespace, GitLab -automatically creates a new project under that GitLab namespace with its visibility -set to Private by default (you can later change it in the [project's settings](../../public_access/public_access.md#change-project-visibility)). - -This can be done by using either SSH or HTTPS: - -```shell -## Git push using SSH -git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master - -## Git push using HTTPS -git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master -``` - -You can pass the flag `--tags` to the `git push` command to export existing repository tags. - -Once the push finishes successfully, a remote message indicates -the command to set the remote and the URL to the new project: - -```plaintext -remote: -remote: The private project namespace/nonexistent-project was created. -remote: -remote: To configure the remote, run: -remote: git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git -remote: -remote: To view the project, visit: -remote: https://gitlab.example.com/namespace/nonexistent-project -remote: -``` +When you create a new repository locally, you don't have to sign in to the GitLab +interface to create a project and +[clone its repository](../../gitlab-basics/start-using-git.md#clone-a-repository). +You can directly push your new repository to GitLab, which creates your new project +without leaving your terminal. + +To push a new project: + +1. Identify the [namespace](../group/index.md#namespaces) you want to add the new + project to, as you need this information in a future step. To determine if you have + permission to create new projects in a namespace, view the group's page in a + web browser and confirm the page displays a **New project** button. + + NOTE: + As project creation permissions can have many factors, contact your + GitLab administrator if you're unsure. + +1. If you want to push using SSH, ensure you have [created a SSH key](../../ssh/README.md) and + [added it to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). +1. Push with one of the following methods. Replace `gitlab.example.com` with the + domain name of the machine that hosts your Git repository, `namespace` with the name of + your namespace, and `myproject` with the name of your new project: + - To push with SSH: `git push --set-upstream git@gitlab.example.com:namespace/myproject.git master` + - To push with HTTPS: `git push --set-upstream https://gitlab.example.com/namespace/myproject.git master` + Optional: to export existing repository tags, append the `--tags` flag to your `git push` command. +1. When the push completes, GitLab displays a message: + + ```plaintext + remote: The private project namespace/myproject was created. + ``` + +1. (Optional) To configure the remote, alter the command + `git remote add origin https://gitlab.example.com/namespace/myproject.git` + to match your namespace and project names. + +You can view your new project at `https://gitlab.example.com/namespace/myproject`. +Your project's visibility is set to **Private** by default, but you can change it +in your [project's settings](../../public_access/public_access.md#change-project-visibility)). ## Fork a project diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index 2b585315326..a8107d77113 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -64,5 +64,5 @@ in the abuse report's **Message** field. ## Managing abuse reports -Admins are able to view and resolve abuse reports. +Administrators are able to view and resolve abuse reports. For more information, see [abuse reports administration documentation](admin_area/review_abuse_reports.md). diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index bb74a035121..f29ac531d2e 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -35,9 +35,9 @@ The Advanced Search can be useful in various scenarios: Advanced Search is based on Elasticsearch, which is a purpose-built full text search engine that can be horizontally scaled so that it can provide search results in 1-2 seconds in most cases. -- **Code Maintenance:** - Finding all the code that needs to be updated at once across an entire - instance can save time spent maintaining code. +- **Code Maintenance:** + Finding all the code that needs to be updated at once across an entire + instance can save time spent maintaining code. This is especially helpful for organizations with more than 10 active projects. This can also help build confidence is code refactoring to identify unknown impacts. - **Promote innersourcing:** diff --git a/doc/user/search/index.md b/doc/user/search/index.md index d90841fae88..92d01e6a43e 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -186,10 +186,9 @@ Some filters can be added multiple times. These include but are not limited to a ## To-Do List -Your [To-Do List](../todos.md#gitlab-to-do-list) can be searched by "to do" and "done". -You can [filter](../todos.md#filtering-your-to-do-list) them per project, -author, type, and action. Also, you can sort them by -[**Label priority**](../../user/project/labels.md#label-priority), +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), **Last created**, and **Oldest created**. ## Projects @@ -307,10 +306,10 @@ GitLab instance. ## Search settings > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8 behind a feature flag, disabled by default. -> - [Added to Group, Admin, and User settings](https://gitlab.com/groups/gitlab-org/-/epics/4842) in GitLab 13.9. +> - [Added to Group, Administrator, and User settings](https://gitlab.com/groups/gitlab-org/-/epics/4842) in GitLab 13.9. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. -You can search inside a Project, Group, Admin, or User's settings by entering +You can search inside a Project, Group, Administrator, or User's settings by entering a search term in the search box located at the top of the page. The search results appear highlighted in the sections that match the search term. diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 9fb6152168e..64da024f5ba 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -215,8 +215,7 @@ which can encourage user collaboration. - Git tags are not supported in snippet repositories. - Snippets' repositories are limited to 10 files. Attempting to push more than 10 files results in an error. -- Revisions are not visible to the user on the GitLab UI, but this feature is planned - in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) +- Revisions are not visible to the user on the GitLab UI, but [an issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) for updates. - The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) is 50 MB, by default. @@ -229,3 +228,16 @@ it's recommended to keep snippets' repositories as compact as possible. For more information about tools to compact repositories, see the documentation on [reducing repository size](../user/project/repository/reducing_the_repo_size_using_git.md). + +### Cannot enter text into the snippet text box + +If the text area after the filename field is disabled and prevents you from +creating a new snippet, use this workaround: + +1. Enter a title for your snippet. +1. Scroll to the bottom of the **Files** field, then select + **Add another file**. GitLab displays a second set of fields to add a second file. +1. In the filename field for the second file, enter a filename to avoid a [known copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). +1. Enter any string into the text area for the second file. +1. Scroll back to the first filename, and select **Delete file**. +1. Create the rest of your file, and select **Create snippet** when done. diff --git a/doc/user/todos.md b/doc/user/todos.md index 719ab6f6e7c..f0601db0300 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -5,47 +5,37 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab To-Do List **(FREE)** +# To-Do List **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2817) in GitLab 8.5. -When you sign in to GitLab, you normally want to determine where you should -spend your time. This can include taking an action, or keeping track of things -(without having to read lots of email notifications). Because GitLab is where you -do your work, being able to get started quickly is important. +Your *To-Do List* is a chronological list of items waiting for your input. +The items are known as *to-do items*. -Your *To-Do List* offers a chronological list of items waiting for your input -(known as *to-do items*) in a single dashboard. - -The To-Do List supports tracking [actions](#what-triggers-a-to-do-item) related to -the following: +You can use the To-Do List to track [actions](#actions-that-create-to-do-items) related to: - [Issues](project/issues/index.md) - [Merge requests](project/merge_requests/index.md) - [Epics](group/epics/index.md) - [Designs](project/issues/design_management.md) - +## Access the To-Do List -You can access your To-Do List by clicking the To-Do List icon (**{task-done}**) -next to the search bar in the top navigation. If the to-do item count is: +To access your To-Do List: -- *Less than 100*, the number in blue is the number of to-do items. -- *100 or more*, the number displays as 99+. The exact number displays in the - To-Do List. +On the top bar, in the top right, select To-Do List (**{task-done}**). -## What triggers a to-do item +## Actions that create to-do items -A to-do item appears on your To-Do List when: +Many to-do items are created automatically. +A to-do item is added to your To-Do List when: - An issue or merge request is assigned to you. -- You're `@mentioned` in the description or comment of an issue or merge request - (or epic). -- You are `@mentioned` in a comment on a: - - Commit - - Design -- The CI/CD pipeline for your merge request failed. -- An open merge request becomes unmergeable due to conflict, and one of the +- You're [mentioned](project/issues/issue_data_and_actions.md#mentions) in the description or + comment of an issue, merge request, or epic. +- You are mentioned in a comment on a commit or design. +- The CI/CD pipeline for your merge request fails. +- An open merge request cannot be merged due to conflict, and one of the following is true: - You're the author. - You're the user that set the merge request to automatically merge after a @@ -55,24 +45,32 @@ A to-do item appears on your To-Do List when: [merge train](../ci/pipelines/merge_trains.md), and you're the user that added it. -When several trigger actions occur for the same user on the same object (for -example, an issue), GitLab displays only the first action as a single to-do -item. +When several actions occur for the same user on the same object, +GitLab displays the first action as a single to-do item. + +To-do items aren't affected by [GitLab notification email settings](profile/notifications.md). + +## Create a to-do item + +You can manually add an item to your To-Do List. -To-do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md). +1. Go to your: -NOTE: -When a user no longer has access to a resource related to a to-do item (such as -an issue, merge request, epic, project, or group), for security reasons GitLab -deletes any related to-do items within the next hour. Deletion is delayed to -prevent data loss, in the case where a user's access is accidentally revoked. + - [Issue](project/issues/index.md) + - [Merge request](project/merge_requests/index.md) + - [Epic](group/epics/index.md) + - [Design](project/issues/design_management.md) -### Directly addressing a to-do item +1. On the right sidebar, at the top, select **Add a to do**. + +  + +## Create a to-do item by directly addressing someone > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0. -If you're mentioned at the start of a line, the to-do item you receive is -listed as *directly addressed*. For example, in the following comment: +You can create a to-do item by directly addressing someone at the start of a line. +For example, in the following comment: ```markdown @alice What do you think? cc: @bob @@ -86,22 +84,15 @@ listed as *directly addressed*. For example, in the following comment: @erin @frank thank you! ``` -The people receiving directly addressed to-do items are `@alice`, `@erin`, and -`@frank`. Directly addressed to-do items only differ from mentions in their type -for filtering purposes; otherwise, they appear as normal. +The people who receive to-do items are `@alice`, `@erin`, and +`@frank`. -### Manually creating a to-do item +To view to-do items where a user was directly addressed, go to the To-Do List and +from the **Action** filter, select **Directly addressed**. -You can also add the following to your To-Do List by clicking the **Add a to do** button on: +Mentioning a user many times only creates one to-do item. -- [Issues](project/issues/index.md) -- [Merge requests](project/merge_requests/index.md) -- [Epics](group/epics/index.md) -- [Designs](project/issues/design_management.md) - - - -## Marking a to-do item as done +## Actions that mark a to-do item as done Any action to an issue, merge request, or epic marks its corresponding to-do item as done. @@ -110,53 +101,36 @@ Actions that dismiss to-do items include: - Changing the assignee - Changing the milestone -- Adding/removing a label +- Closing the issue or merge request +- Adding or removing a label - Commenting on the issue - Resolving a [design discussion thread](project/issues/design_management.md#resolve-design-threads) -Your To-Do List is personal, and items are only marked as done if you take -action. If you close the issue or merge request, your to-do item is marked as -done. - -To prevent other users from closing issues without you being notified, if -someone else closes, merges, or takes action on an issue, merge request, or +If someone else closes, merges, or takes action on an issue, merge request, or epic, your to-do item remains pending. -There's just one to-do item for each of these, so mentioning a user many times -in an issue only triggers one to-do item. +## Mark a to-do item as done -If no action is needed, you can manually mark the to-do item as done by -clicking its corresponding **Done** button to have GitLab remove the item from -your To-Do List. +You can manually mark a to-do item as done. - +There are two ways to do this: -You can also mark a to-do item as done by clicking the **Mark as done** button -in the sidebar of an issue, merge request, or epic. +- In the To-Do List, to the right of the to-do item, select **Done**. +- In the sidebar of an issue, merge request, or epic, select **Mark as done**. - +  -You can mark all your to-do items as done at once by clicking the -**Mark all as done** button. +## Mark all to-do items as done -## Filtering your To-Do List +You can mark all your to-do items as done at the same time. -You can use the following types of filters with your To-Do List: +In the To-Do List, in the top right, select **Mark all as done**. -| Filter | Description | -| ------- | ---------------------------------------------------------------- | -| Project | Filter by project. | -| Group | Filter by group. | -| Author | Filter by the author that triggered the to-do item. | -| Type | Filter by issue, merge request, design, or epic. | -| Action | Filter by the action that triggered the to-do item. | +## How a user's To-Do List is affected when their access changes -You can also filter by more than one of these at the same time. The previously -described [triggering actions](#what-triggers-a-to-do-item) include: +For security reasons, GitLab deletes to-do items when a user no longer has access to a related resource. +For example, if the user no longer has access to an issue, merge request, epic, project, or group, +GitLab deletes the related to-do items. -- Any action -- Assigned -- Mentioned -- Added -- Pipelines -- Directly addressed +This process occurs in the hour after their access changes. Deletion is delayed to +prevent data loss, in case the user's access was accidentally revoked. diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 7d2f2395815..3272ff30e72 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -73,7 +73,7 @@ Your account has been blocked. Fatal: Could not read from remote repository Your primary email address is not confirmed. ``` -You can assure your users that they have not been [Blocked](admin_area/moderate_users.md#blocking-and-unblocking-users) by an administrator. +You can assure your users that they have not been [Blocked](admin_area/moderate_users.md#block-and-unblock-users) by an administrator. When affected users see this message, they must confirm their email address before they can commit code. ## What do I need to know as an administrator of a GitLab self-managed Instance? diff --git a/doc/user/workspace/img/1.1-Instance_overview.png b/doc/user/workspace/img/1.1-Instance_overview.png Binary files differindex 7612cc7c092..a3c642cda3f 100644 --- a/doc/user/workspace/img/1.1-Instance_overview.png +++ b/doc/user/workspace/img/1.1-Instance_overview.png diff --git a/doc/user/workspace/img/1.2-Groups_overview.png b/doc/user/workspace/img/1.2-Groups_overview.png Binary files differindex b4f034bba16..7771e5f4c3c 100644 --- a/doc/user/workspace/img/1.2-Groups_overview.png +++ b/doc/user/workspace/img/1.2-Groups_overview.png diff --git a/doc/user/workspace/img/1.3-Admin.png b/doc/user/workspace/img/1.3-Admin.png Binary files differindex 018ed8a1bfc..5f531e4ef5e 100644 --- a/doc/user/workspace/img/1.3-Admin.png +++ b/doc/user/workspace/img/1.3-Admin.png diff --git a/doc/user/workspace/img/Admin_Settings.png b/doc/user/workspace/img/Admin_Settings.png Binary files differindex 5c4656ff342..b0d13f43ccb 100644 --- a/doc/user/workspace/img/Admin_Settings.png +++ b/doc/user/workspace/img/Admin_Settings.png diff --git a/doc/user/workspace/img/hardware_settings.png b/doc/user/workspace/img/hardware_settings.png Binary files differnew file mode 100644 index 00000000000..ff460918f25 --- /dev/null +++ b/doc/user/workspace/img/hardware_settings.png diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index f098cef6053..d9c9d19721b 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -6,17 +6,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Workspace -Workspace will be the top-level [namespace](../group/index.md#namespaces) for you to manage +Workspace will be the top [namespace](../group/index.md#namespaces) for you to manage everything GitLab, including: - Defining and applying settings to all of your groups, subgroups, and projects. - Aggregating data from all your groups, subgroups, and projects. Workspace will take many of the features from the -[Admin Area](../admin_area/index.md), and there will be one workspace per: +[Admin Area](../admin_area/index.md) and will: -- Instance, for self-managed instances. -- Namespace, for GitLab.com. +- Enable a top namespace for GitLab.com. +- Eventually replace the instance level for self-managed installations. + +Our goal is to reach feature parity between SaaS and self-managed installations, with one +exception: **Hardware Controls** will appear **only** on self-managed installations. NOTE: Workspace is currently in development. @@ -32,3 +35,5 @@ The following provide a preview to the Workspace concept.   + + |
