diff options
Diffstat (limited to 'doc/user')
260 files changed, 3475 insertions, 2567 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index 62fea3c266a..ede9e342a2e 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -20,11 +20,11 @@ To see DevOps Reports: > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) from Conversational Development Index in GitLab 12.6. NOTE: -To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). This is because DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. +To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. You can use the DevOps score to compare your DevOps status to other organizations. -The DevOps Score tab displays the usage of major GitLab features on your instance over +The DevOps Score tab displays usage of major GitLab features on your instance over the last 30 days, averaged over the number of billable users in that time period. You can also see the Leader usage score, calculated from top-performing instances based on [Service Ping data](../settings/usage_statistics.md#service-ping) that GitLab has collected. @@ -47,29 +47,27 @@ feature is available. > - Multi-select [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. > - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. -DevOps Adoption shows you which groups in your organization are using the most essential features of GitLab: - -- Dev - - Approvals - - Code owners - - Issues - - Merge requests -- Sec - - DAST - - Dependency Scanning - - Fuzz Testing - - SAST -- Ops - - Deployments - - Pipelines - - Runners - -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. +DevOps Adoption shows feature adoption for development, security, and operations. + +| Category | Feature | +| --- | --- | +| Development | Approvals<br>Code owners<br>Issues<br>Merge requests | +| Security | DAST<br>Dependency Scanning<br>Fuzz Testing<br>SAST | +| Operations | Deployments<br>Pipelines<br>Runners | + +You can use Group DevOps Adoption to: + +- Identify specific subgroups that are lagging in their adoption of GitLab features, so you can guide them on +their DevOps journey. +- Find subgroups that have adopted certain features, and provide guidance to other subgroups on +how to use those features. +- Verify if you are getting the return on investment that you expected from GitLab. + +## Add or remove a group + +To add or remove a subgroup from the DevOps Adoption report: + +1. Select **Add or remove groups**. +1. Select the subgroup you want to add or remove and select **Save changes**.  diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 06995069215..7901d30c3ea 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -16,8 +16,11 @@ WARNING: This feature might not be available to you. Check the **version history** note above for details. Usage Trends gives you an overview of how much data your instance contains, and how quickly this volume is changing over time. +Usage Trends data refreshes daily. -To see Usage Trends: +## View Usage Trends + +To view Usage Trends: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Analytics > Usage Trends**. diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md deleted file mode 100644 index fdf0c7edfc7..00000000000 --- a/doc/user/admin_area/approving_users.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'moderate_users.md' -remove_date: '2021-10-20' ---- - -This document was moved to [another location](moderate_users.md). - -<!-- 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/index.md b/doc/user/admin_area/index.md index 4de2397706b..b0f38e8cfb9 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -107,15 +107,16 @@ You can combine the filter options. For example, to list only public projects wi 1. Click the **Public** tab. 1. Enter `score` in the **Filter by name...** input box. -#### Deleted projects **(PREMIUM SELF)** +#### Projects pending deletion **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3. +> - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.7. -When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-removal), +When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-deletion), projects within that group are not deleted immediately, but only after a delay. To access a list of all projects that are pending deletion: 1. On the top bar, select **Menu > Projects > Explore projects**. -1. Select the **Deleted projects** tab. +1. Select the **Pending deletion** tab (in GitLab 14.7 and later) or the **Deleted projects** tab (GitLab 14.6 and earlier). Listed for each project is: @@ -199,6 +200,7 @@ The following data is included in the export: - Type - Path - Access level ([Project](../permissions.md#project-members-permissions) and [Group](../permissions.md#group-members-permissions)) +- Date of last activity ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345388) in GitLab 14.6). For a list of activities that populate this column, see the [Users API documentation](../../api/users.md#get-user-activities-admin-only).  @@ -257,7 +259,7 @@ To [Create a new group](../group/index.md#create-a-group) click **New group**. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. -You can administer all [topics](../project/working_with_projects.md#explore-topics) in the +You can administer all [topics](../project/working_with_projects.md#explore-topics) in the GitLab instance from the Admin Area's Topics page. To access the Topics page: diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index a98250dfc56..3f15bd5b4e6 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -53,7 +53,7 @@ To approve or reject a user sign up: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. -1. (Optional) Select a user. +1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Approve** or **Reject**. @@ -77,7 +77,7 @@ by removing them in LDAP, or directly from the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. -1. (Optional) Select a user. +1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Block**. @@ -101,7 +101,7 @@ A blocked user can be unblocked from the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select on the **Blocked** tab. -1. (Optional) Select a user. +1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Unblock**. @@ -145,7 +145,7 @@ A user can be deactivated from the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. -1. (Optional) Select a user. +1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Deactivate**. @@ -185,7 +185,7 @@ To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Deactivated** tab. -1. (Optional) Select a user. +1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Activate**. @@ -211,7 +211,7 @@ Users can be banned using the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. -1. (Optional) Select a user. +1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Ban user**. @@ -224,7 +224,7 @@ A banned user can be unbanned using the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Banned** tab. -1. (Optional) Select a user. +1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Unban user**. 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 c511e85f3ce..5868f20d0d8 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -9,7 +9,12 @@ type: reference ## Default projects limit -You can change the default maximum number of projects that users can create in their personal namespace: +You can configure the default maximum number of projects new users can create in their +personal namespace. This limit affects only new user accounts created after you change +the setting. This setting is not retroactive for existing users, but you can separately edit +the [project limits for existing users](#projects-limit-for-a-user). + +To configure the maximum number of projects in personal namespaces for new users: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. @@ -18,6 +23,17 @@ You can change the default maximum number of projects that users can create in t If you set **Default projects limit** to 0, users are not allowed to create projects in their users personal namespace. However, projects can still be created in a group. +### Projects limit for a user + +You can edit a specific user, and change the maximum number of projects this user +can create in their personal namespace: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview** > **Users**. +1. From the list of users, select a user. +1. Select **Edit**. +1. Increase or decrease the **Projects limit** value. + ## Max attachment size You can change the maximum file size for attachments in comments and replies in GitLab: @@ -59,21 +75,21 @@ If you choose a size larger than the configured value for the web server, you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. -## Personal Access Token prefix +## Personal access token prefix -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20968) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5, a default prefix. -You can set a global prefix for all generated Personal Access Tokens. +You can specify a prefix for personal access tokens. You might use a prefix +to find tokens more quickly, or for use with automation tools. -A prefix can help you identify PATs visually, as well as with automation tools. +The default prefix is `glpat-` but administrators can change it. -NOTE: -For GitLab.com and self-managed instances, the default prefix is `glpat-`. +[Project access tokens](../../project/settings/project_access_tokens.md) also inherit this prefix. ### Set a prefix -Only a GitLab administrator can set the prefix, which is a global setting applied -to any PAT generated in the system by any user: +To change the default global prefix: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. @@ -81,8 +97,8 @@ to any PAT generated in the system by any user: 1. Fill in the **Personal Access Token prefix** field. 1. Click **Save changes**. -It is also possible to configure the prefix via the [settings API](../../../api/settings.md) -using the `personal_access_token_prefix` field. +You can also configure the prefix by using the +[settings API](../../../api/settings.md). ## Repository size limit **(PREMIUM SELF)** @@ -176,38 +192,46 @@ To set a limit on how long these sessions are valid: 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. 1. Click **Save changes**. -## Limit the lifetime of personal access tokens **(ULTIMATE SELF)** +## Limit the lifetime of SSH keys **(ULTIMATE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `ff_limit_ssh_key_lifetime`. Disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346753) in GitLab 14.6. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `ff_limit_ssh_key_lifetime`. +On GitLab.com, this feature is not available. Users can optionally specify a lifetime for -[personal access tokens](../../profile/personal_access_tokens.md). +[SSH keys](../../../ssh/index.md). This lifetime is not a requirement, and can be set to any arbitrary number of days. -Personal access tokens are the only tokens needed for programmatic access to GitLab. +SSH keys are user credentials to access GitLab. However, organizations with security requirements may want to enforce more protection by -requiring the regular rotation of these tokens. +requiring the regular rotation of these keys. ### Set a lifetime Only a GitLab administrator can set a lifetime. Leaving it empty means there are no restrictions. -To set a lifetime on how long personal access tokens are valid: +To set a lifetime on how long SSH keys are valid: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. -1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. +1. Fill in the **Maximum allowable lifetime for SSH keys (days)** field. 1. Click **Save changes**. -Once a lifetime for personal access tokens is set, GitLab: +Once a lifetime for SSH keys is set, GitLab: -- Applies the lifetime for new personal access tokens, and require users to set an expiration date - and a date no later than the allowed lifetime. -- After three hours, revoke old tokens with no expiration date or with a lifetime longer than the - allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, - or remove it, before revocation takes place. +- Requires users to set an expiration date that is no later than the allowed lifetime on new + SSH keys. +- Applies the lifetime restriction to existing SSH keys. Keys with no expiry or a lifetime + greater than the maximum immediately become invalid. + +NOTE: +When a user's SSH key becomes invalid they can delete and re-add the same key again. ## Allow expired SSH keys to be used **(ULTIMATE SELF)** @@ -225,6 +249,39 @@ To allow the use of expired SSH keys: Disabling SSH key expiration immediately enables all expired SSH keys. +## Limit the lifetime of personal access tokens **(ULTIMATE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. + +Users can optionally specify a lifetime for +[personal access tokens](../../profile/personal_access_tokens.md). +This lifetime is not a requirement, and can be set to any arbitrary number of days. + +Personal access tokens are the only tokens needed for programmatic access to GitLab. +However, organizations with security requirements may want to enforce more protection by +requiring the regular rotation of these tokens. + +### Set a lifetime + +Only a GitLab administrator can set a lifetime. Leaving it empty means +there are no restrictions. + +To set a lifetime on how long personal access tokens are valid: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Account and limit** section. +1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. +1. Click **Save changes**. + +Once a lifetime for personal access tokens is set, GitLab: + +- Applies the lifetime for new personal access tokens, and require users to set an expiration date + and a date no later than the allowed lifetime. +- After three hours, revoke old tokens with no expiration date or with a lifetime longer than the + allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, + or remove it, before revocation takes place. + ## Allow expired Personal Access Tokens to be used **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab 13.1. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 565e905d732..c6ebce03b06 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -232,11 +232,10 @@ To enable or disable the banner: ## Required pipeline configuration **(PREMIUM SELF)** -WARNING: -This feature is being re-evaluated in favor of a different -[compliance solution](https://gitlab.com/groups/gitlab-org/-/epics/3156). -We recommend that users who haven't yet implemented this feature wait for -the new solution. +NOTE: +An alternative [compliance solution](../../project/settings/index.md#compliance-pipeline-configuration) +is available. We recommend this alternative solution because it provides greater flexibility, +allowing required pipelines to be assigned to specific compliance framework labels. You can set a [CI/CD template](../../../ci/examples/index.md#cicd-templates) as a required pipeline configuration for all projects on a GitLab instance. You can diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md index 4f0f50dbcd2..675561ce9cf 100644 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ b/doc/user/admin_area/settings/files_api_rate_limits.md @@ -7,13 +7,8 @@ type: reference # Files API rate limits **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it -available, ask an administrator to [enable the `files_api_throttling` flag](../../../administration/feature_flags.md). -On GitLab.com, this feature is available but can be configured by GitLab.com -administrators only. The feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75918) in GitLab 14.6. [Feature flag files_api_throttling](https://gitlab.com/gitlab-org/gitlab/-/issues/338903) removed. The [Repository files API](../../../api/repository_files.md) enables you to fetch, create, update, and delete files in your repository. To improve the security @@ -29,10 +24,9 @@ the general user and IP rate limits for requests to the and IP rate limits already in place, and increase or decrease the rate limits for the Files API. No other new features are provided by this override. -Prerequisites: +Prerequisite: - You must have the Administrator role for your instance. -- The `files_api_throttling` feature flag must be enabled. To override the general user and IP rate limits for requests to the Repository files API: diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 5da43935052..fac23cb48af 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -22,6 +22,6 @@ The following timeouts are available. | Timeout | Default | Description | |:--------|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the worker timeout that can be configured for [Puma](../../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | +| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../../../administration/operations/puma.md#worker-timeout) that can be configured for [Puma](../../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | | Fast | 10 seconds | Timeout for fast Gitaly operations used within requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | | Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly within requests) but preferably not used multiple times within a request. For example, loading blobs. Timeout that should be set between Default and Fast. | diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index fd44d6445cf..1087f50b215 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -97,8 +97,8 @@ delete a project. To allow only users with the Administrator role to delete proj > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2 for groups created after August 12, 2021. -Projects in a group (but not a personal namespace) can be deleted after a delayed period. -You can [configure it in group settings](../../group/index.md#enable-delayed-project-removal). +[Delayed project deletion](../../project/settings/index.md#delayed-project-deletion) allows projects in a group (not a personal namespace) +to be deleted after a period of delay. To enable delayed project deletion by default in new groups: @@ -110,14 +110,13 @@ To enable delayed project deletion by default in new groups: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. By default, a project marked for deletion is permanently removed with immediate effect. +See [delayed project deletion](../../project/settings/index.md#delayed-project-deletion) to learn more. By default, a group marked for deletion is permanently removed after seven days. WARNING: The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -Projects 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). The default period is seven days, and can be changed. Setting this period to `0` enables immediate removal of projects or groups. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index e949f968c2b..f083f886924 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline -ran. To view this information, go to **Analytics > CI/CD Analytics**. +ran. To view this information for a project, go to **Analytics > CI/CD Analytics**. View successful pipelines: diff --git a/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png b/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png Binary files differindex 649416c02c0..2bfde7beead 100644 --- a/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png +++ b/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png diff --git a/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png b/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png Binary files differindex b5d0dd4d2ea..0b30aff2c7a 100644 --- a/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png +++ b/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png diff --git a/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png b/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png Binary files differindex da5d3aec957..e0b3c54dee2 100644 --- a/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png +++ b/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 0cc21e3f390..6a157dbb5ae 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -100,29 +100,29 @@ We use the following terms to describe GitLab analytics: - All incidents are related to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is related to only one production deployment, and any production deployment is related to no more than one incident). -- **Lead time:** The duration of your value stream, from start to finish. Different to -[Lead time for changes](#lead-time-for-changes). Often displayed in combination with "cycle time," -which is shorter. GitLab measures lead time from issue creation to issue close. GitLab displays lead +- **Lead time:** The duration of your value stream, from start to finish. Different to +[Lead time for changes](#lead-time-for-changes). Often displayed in combination with "cycle time," +which is shorter. GitLab measures lead time from issue creation to issue close. GitLab displays lead time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). -- **Mean Time to Change (MTTC):** The average duration between idea and delivery. GitLab measures +- **Mean Time to Change (MTTC):** The average duration between idea and delivery. GitLab measures MTTC from issue creation to the issue's latest related merge request's deployment to production. -- **Mean Time to Detect (MTTD):** The average duration that a bug goes undetected in production. +- **Mean Time to Detect (MTTD):** The average duration that a bug goes undetected in production. GitLab measures MTTD from deployment of bug to issue creation. -- **Mean Time To Merge (MTTM):** The average lifespan of a merge request. GitLab measures MTTM from -merge request creation to merge request merge (and closed/un-merged merge requests are excluded). +- **Mean Time To Merge (MTTM):** The average lifespan of a merge request. GitLab measures MTTM from +merge request creation to merge request merge (and closed/un-merged merge requests are excluded). For more information, see [Merge Request Analytics](merge_request_analytics.md). -- **Mean Time to Recover/Repair/Resolution/Resolve/Restore (MTTR):** The average duration that a bug +- **Mean Time to Recover/Repair/Resolution/Resolve/Restore (MTTR):** The average duration that a bug is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. -- **Throughput:** The number of issues closed or merge requests merged (not closed) in a period of +- **Throughput:** The number of issues closed or merge requests merged (not closed) in a period of time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). -- **Value Stream:** The entire work process that is followed to deliver value to customers. For example, -the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts +- **Value Stream:** The entire work process that is followed to deliver value to customers. For example, +the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). -- **Velocity:** The total issue burden completed in some period of time. The burden is usually measured -in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab +- **Velocity:** The total issue burden completed in some period of time. The burden is usually measured +in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points or weight of issues closed in a given period of time. ## Lead time for changes -"Lead Time for Changes" differs from "Lead Time" because it "focuses on measuring only the time to +"Lead Time for Changes" differs from "Lead Time" because it "focuses on measuring only the time to deliver a feature once it has been developed", as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index da55a0f093c..e1ba2f5565e 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -34,14 +34,14 @@ Metrics and visualizations of **merged** merge requests are available on a proje ### Time to merge -The **Time to merge** histogram shows the number of merge requests and the number +The **Time to merge** histogram shows the number of merge requests and the number of days it took to merge after creation. Select a column to filter subsequent charts.  ### Trendline -The **Trendline** scatterplot shows all merge requests on a certain date, +The **Trendline** scatterplot shows all merge requests on a certain date, and the days it took to complete the action and a 30 day rolling median. Select the dropdown to view: - Time from first commit to first comment. @@ -55,15 +55,15 @@ and the days it took to complete the action and a 30 day rolling median. Select ### Commits and merge request size -Under the **Trendline** scatterplot, the left-side histogram shows -the time taken (in hours) between commits and comments until the merge +Under the **Trendline** scatterplot, the left-side histogram shows +the time taken (in hours) between commits and comments until the merge request is merged. Select the dropdown to view: - Time from first commit to first comment. - Time from first comment until last commit. - Time from last commit to merge. -The right-side histogram shows the size or complexity of a merge request. +The right-side histogram shows the size or complexity of a merge request. Select the dropdown to view: - Number of commits per merge request. @@ -74,7 +74,7 @@ Select the dropdown to view: ### Merge request list -The **List** table shows a list of merge requests with their respective time duration metrics. +The **List** table shows a list of merge requests with their respective time duration metrics. Sort metrics by: @@ -83,7 +83,7 @@ Sort metrics by: - Time from last commit to merge. Filter metrics by: - + - Number of commits per merge request. - Number of lines of code per commit. - Number of files touched. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 9c1a8893f95..cb6b2e49f60 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -102,6 +102,20 @@ The **Time** metrics near the top of the page are measured as follows: - **Lead time**: Median time from issue created to issue closed. - **Cycle time**: Median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages).) +- **Lead Time for Changes**: median duration between merge request merge and deployment to a production environment for all MRs deployed in the given time period. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5 (Ultimate only). + +## Deployment metrics (**PREMIUM**) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) in GitLab 11.3. + +Value Stream Analytics exposes two deployment related metrics near the top of the page: + +- **Deploys:** The number of successful deployments in the date range. +- **Deployment Frequency:** The average number of successful deployments. + +The deployment metrics calculation uses the same method as the +[group-level Value Stream Analytics](../group/value_stream_analytics/index.md#how-metrics-are-measured). +Both of them are based on the [DORA API](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). ## How the stages are measured diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 5cef0040ac3..a0f14ea59a1 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -12,6 +12,10 @@ parameters to unexpected values in an effort to cause unexpected behavior and er backend. This helps you discover bugs and potential security issues that other QA processes may miss. +INFO: +Try fuzz testing in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-api-fuzzing-docs). + We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run fuzz tests as part your CI/CD workflow. @@ -1181,7 +1185,7 @@ A bug exists in versions of the API Fuzzing analyzer prior to v1.6.196 that can The version information can be found in the job details for the `apifuzzer_fuzz` job. -If the issue is occuring with versions v1.6.196 or greater, please contact Support and provide the following information: +If the issue is occurring with versions v1.6.196 or greater, please contact Support and provide the following information: 1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. 1. The full console output of the job. @@ -1289,6 +1293,25 @@ The API Fuzzing template supports launching a docker container containing an API TODO --> +## Get support or request an improvement + +To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). + +The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and API Fuzzing. +Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding API fuzzing to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](../../../development/code_review.md#review-response-slo) to understand when you should receive a response. + +[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. + +When experiencing a behavior not working as expected, consider providing contextual information: + +- GitLab version if using a self-managed instance. +- `.gitlab-ci.yml` job definition. +- Full job console output. +- Scanner log file available as a job artifact named `gl-api-security-scanner.log`. + +WARNING: +**Sanitize data attached to a support issue**. Please remove sensitive information, including: credentials, passwords, tokens, keys, and secrets. + ## Glossary - Assert: Assertions are detection modules used by checks to trigger a fault. Many assertions have diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index 790b428bac9..c3a2c179590 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -29,7 +29,7 @@ To integrate GitLab with security scanners other than those listed here, see You can use cluster image scanning through the following methods: - [The cluster image scanning analyzer](#use-the-cluster-image-scanning-analyzer) -- [The GitLab Kubernetes agent](#cluster-image-scanning-with-the-gitlab-kubernetes-agent) +- [The GitLab Agent](#cluster-image-scanning-with-the-gitlab-agent) ## Use the cluster image scanning analyzer @@ -153,7 +153,7 @@ The included template: fetches vulnerabilities found by [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/). GitLab saves the results as a -[Cluster Image Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscluster_image_scanning) +[Cluster Image Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscluster_image_scanning) that you can download and analyze later. When downloading, you always receive the most recent artifact. @@ -177,6 +177,7 @@ You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by | `CIS_RESOURCE_NAMESPACE` | `""` | Namespace of the Kubernetes resource you want to filter vulnerabilities for. For example, `production`. | | `CIS_RESOURCE_KIND` | `""` | Kind of the Kubernetes resource you want to filter vulnerabilities for. For example, `deployment`. | | `CIS_CLUSTER_IDENTIFIER` | `""` | ID of the Kubernetes cluster integrated with GitLab. This is used to map vulnerabilities to the cluster so they can be filtered in the Vulnerability Report page. | +| `CIS_CLUSTER_AGENT_IDENTIFIER` | `""` | ID of the Kubernetes cluster agent integrated with GitLab. This maps vulnerabilities to the agent so they can be filtered in the Vulnerability Report page. | #### Override the cluster image scanning template @@ -274,26 +275,22 @@ Here's an example cluster image scanning report: } ``` -## Cluster image scanning with the GitLab Kubernetes Agent +## Cluster image scanning with the GitLab Agent -You can use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to +You can use the [GitLab Agent](../../clusters/agent/index.md) to scan images from within your Kubernetes cluster and record the vulnerabilities in GitLab. ### Prerequisites - [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) installed and configured in your cluster. -- [GitLab Kubernetes Agent](../../clusters/agent/install/index.md) +- [GitLab Agent](../../clusters/agent/install/index.md) set up in GitLab, installed in your cluster, and configured using a configuration repository. ### Configuration -The GitLab Kubernetes agent begins to run cluster image scanning once the `cluster_image_scanning` -directive is added to your Kubernetes Agent configuration repository. - -See the [Kubernetes agent configuration repository](../../clusters/agent/repository.md#scan-your-container-images-for-vulnerabilities) -reference to learn more about the cluster image scanning configuration options for the -GitLab Kubernetes agent. +The Agent runs the cluster image scanning once the `cluster_image_scanning` +directive is added to your [Agent's configuration repository](../../clusters/agent/repository.md#scan-your-container-images-for-vulnerabilities). ## Security Dashboard diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index a913d5fba92..cdcd334dba6 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -46,14 +46,14 @@ You can configure the following security controls: - Select **Manage scans** to manage the saved DAST scans, site profiles, and scanner profiles. For more details, read [DAST on-demand scans](../dast/index.md#on-demand-scans). - [Dependency Scanning](../dependency_scanning/index.md) - - Select **Configure via Merge Request** to create a merge request with the changes required to + - Select **Configure with a merge request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). - [Container Scanning](../container_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). - [Cluster Image Scanning](../cluster_image_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). - [Secret Detection](../secret_detection/index.md) - - Select **Configure via Merge Request** to create a merge request with the changes required to + - Select **Configure with a merge request** to create a merge request with the changes required to enable Secret Detection. For more details, read [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - [API Fuzzing](../api_fuzzing/index.md) - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index da2816ab6ed..bea9284873c 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,11 +9,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. +INFO: +Try out Container Scanning in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-container-scanning-docs). + Your application's Docker image may itself be based on Docker images that contain known -vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and -displays them in a merge request, you can use GitLab to audit your Docker-based apps. +vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those +vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based +apps. + +Container Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain +aspects of inspecting the items your code uses. These items typically include application and system +dependencies that are almost always imported from external sources, rather than sourced from items +you wrote yourself. + +GitLab offers both Container Scanning and [Dependency Scanning](../dependency_scanning/) +to ensure coverage for all of these dependency types. To cover as much of your risk area as +possible, we encourage you to use all of our security scanners. -GitLab provides integration with open-source tools for vulnerability static analysis in containers: +## Overview + +GitLab integrates with open-source tools for vulnerability static analysis in containers: - [Trivy](https://github.com/aquasecurity/trivy) - [Grype](https://github.com/anchore/grype) @@ -43,19 +59,9 @@ To enable container scanning in your pipeline, you need the following: - An image matching the [supported distributions](#supported-distributions). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) the Docker image to your project's container registry. -- The name of the Docker image to scan, in the `DOCKER_IMAGE` [configuration variable](#available-cicd-variables). - If you're using a third-party container registry, you might need to provide authentication credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). - For example, if you are connecting to AWS ECR, you might use the following: - -```yaml -export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) - -include: - - template: Security/Container-Scanning.gitlab-ci.yml - DOCKER_USER: AWS - DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" -``` + For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). ## Configuration @@ -75,31 +81,29 @@ The included template: (see [requirements](#requirements)) and scans it for possible vulnerabilities. GitLab saves the results as a -[Container Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscontainer_scanning) +[Container Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscontainer_scanning) that you can download and analyze later. When downloading, you always receive the most-recent -artifact. +artifact. If [dependency scan is enabled](#dependency-list), +a [Dependency Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsdependency_scanning) +is also created. The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container registry, and scans the image: ```yaml -build: - image: docker:latest - stage: build - services: - - docker:dind - variables: - IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA - script: - - docker info - - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - - docker build -t $IMAGE . - - docker push $IMAGE - include: + - template: Jobs/Build.gitlab-ci.yml - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DEFAULT_BRANCH_IMAGE: $CI_REGISTRY_IMAGE/$CI_DEFAULT_BRANCH:$CI_COMMIT_SHA ``` +Setting `CS_DEFAULT_BRANCH_IMAGE` avoids duplicate vulnerability findings when an image name differs across branches. +The value of `CS_DEFAULT_BRANCH_IMAGE` indicates the name of the scanned image as it appears on the default branch. +For more details on how this deduplication is achieved, see [Setting the default branch image](#setting-the-default-branch-image). + ### Customizing the container scanning settings There may be cases where you want to customize how GitLab scans your containers. For example, you @@ -120,6 +124,92 @@ variables: SECURE_LOG_LEVEL: 'debug' ``` +#### Scan an image in a remote registry + +To scan images located in a registry other than the project's, use the following `.gitlab-ci.yml`: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + DOCKER_IMAGE: example.com/user/image:tag +``` + +##### Authenticate to a remote registry + +Scanning an image in a private registry requires authentication. Provide the username in the `DOCKER_USER` +variable, and the password in the `DOCKER_PASSWORD` configuration variable. + +For example, to scan an image from AWS Elastic Container Registry: + +```yaml +container_scanning: + before_script: + - curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" --output "awscliv2.zip" + - unzip awscliv2.zip + - ./aws/install + - aws --version + - export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) + +include: + - template: Security/Container-Scanning.gitlab-ci.yml + DOCKER_IMAGE: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<image>:<tag> + DOCKER_USER: AWS + DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" +``` + +#### Dependency list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. + +The `CS_DISABLE_DEPENDENCY_LIST` CI/CD variable controls whether the scan creates a +[Dependency List](../dependency_list/) +report. The variable's default setting of `false` causes the scan to create the report. To disable +the report, set the variable to `true`: + +For example: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DISABLE_DEPENDENCY_LIST: "true" +``` + +#### Report language-specific findings + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7277) in GitLab 14.6. + +The `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` CI/CD variable controls whether the scan reports +findings related to programming languages. The languages supported depend on the +[scanner used](#change-scanners): + +- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/language/). +- [Grype](https://github.com/anchore/grype#features). + +By default, the report only includes packages managed by the Operating System (OS) package manager +(for example, `yum`, `apt`, `apk`, `tdnf`). To report security findings in non-OS packages, set +`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` to `"false"`: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN: "false" +``` + +When you enable this feature, you may see [duplicate findings](../terminology/#duplicate-finding) +in the [Vulnerability Report](../vulnerability_report/) +if [Dependency Scanning](../dependency_scanning/) +is enabled for your project. This happens because GitLab can't automatically deduplicate the +findings reported by the two different analyzers. + #### Available CI/CD variables You can [configure](#customizing-the-container-scanning-settings) analyzers by using the following CI/CD variables: @@ -130,6 +220,9 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | All | | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | | `CS_ANALYZER_IMAGE` | `registry.gitlab.com/security-products/container-scanning:4` | Docker image of the analyzer. | All | +| `CS_DEFAULT_BRANCH_IMAGE` | `""` | The name of the `DOCKER_IMAGE` on the default branch. See [Setting the default branch image](#setting-the-default-branch-image) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. | All | +| `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | +| `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | | `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | @@ -225,6 +318,51 @@ Prior to the GitLab 14.0 release, any variable defined under the scope `containe considered for scanners other than Clair. In GitLab 14.0 and later, all variables can be defined either as a global variable or under `container_scanning`. +### Setting the default branch image + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. + +By default, container scanning assumes that the image naming convention stores any branch-specific +identifiers in the image tag rather than the image name. When the image name differs between the +default branch and the non-default branch, previously-detected vulnerabilities show up as newly +detected in merge requests. + +When the same image has different names on the default branch and a non-default branch, you can use +the `CS_DEFAULT_BRANCH_IMAGE` variable to indicate what that image's name is on the default branch. +GitLab then correctly determines if a vulnerability already exists when running scans on non-default +branches. + +As an example, suppose the following: + +- Non-default branches publish images with the naming convention + `$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA`. +- The default branch publishes images with the naming convention + `$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA`. + +In this example, you can use the following CI/CD configuration to ensure that vulnerabilities aren't +duplicated: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DEFAULT_BRANCH_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + before_script: + - export DOCKER_IMAGE="$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA" + - | + if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then + export DOCKER_IMAGE="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" + fi +``` + +`CS_DEFAULT_BRANCH_IMAGE` should remain the same for a given `DOCKER_IMAGE`. If it changes, then a +duplicate set of vulnerabilities are created, which must be manually dismissed. + +When using [Auto DevOps](../../../topics/autodevops/index.md), `CS_DEFAULT_BRANCH_IMAGE` is +automatically set to `$CI_REGISTRY_IMAGE/$CI_DEFAULT_BRANCH:$CI_APPLICATION_TAG`. + ### Using a custom SSL CA certificate authority You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: @@ -496,7 +634,7 @@ Here's an example container scanning report: ```json-doc { - "version": "3.0.0", + "version": "14.0.0", "vulnerabilities": [ { "id": "df52bc8ce9a2ae56bbcb0c4ecda62123fbd6f69b", @@ -518,7 +656,8 @@ Here's an example container scanning report: "version": "1.4.8" }, "operating_system": "debian:9.4", - "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e" + "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e", + "default_branch_image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0:latest" }, "identifiers": [ { diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 9bb13d26d90..b35c2ed79cf 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -213,7 +213,7 @@ is a good way to balance the needs of letting a developer's per-commit pipeline and also giving the fuzzer a large amount of time to fully explore and test the app. Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs -in your latest codebase. THe following is an example of what `.gitlab-ci.yml` looks like in this +in your latest codebase. The following is an example of what `.gitlab-ci.yml` looks like in this workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): ```yaml diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 10ca3430b48..5d1e57553f4 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -61,14 +61,15 @@ The browser-based crawler can be configured using CI/CD variables. | `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 are likely to 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. | +| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://pkg.go.dev/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://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action. | +| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/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://pkg.go.dev/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://pkg.go.dev/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://pkg.go.dev/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://pkg.go.dev/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://pkg.go.dev/time#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis. | +| `DAST_BROWSER_PAGE_READY_SELECTOR` | selector | `css:#page-is-ready` | Selector that when detected as visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Note: When this selector is set, but the element is not found, the scanner waits for the period defined in `DAST_BROWSER_STABILITY_TIMEOUT` before continuing the scan. This can significantly increase scanning time if the element is not present on multiple pages within the site. | 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`, @@ -99,7 +100,7 @@ You can manage the trade-off between coverage and scan time with the following m 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. +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://pkg.go.dev/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 because 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. diff --git a/doc/user/application_security/dast/checks/1004.1.md b/doc/user/application_security/dast/checks/1004.1.md index cbbcea1d34d..dfbc600b05b 100644 --- a/doc/user/application_security/dast/checks/1004.1.md +++ b/doc/user/application_security/dast/checks/1004.1.md @@ -36,6 +36,6 @@ Set-Cookie: {cookie_name}=<random secure value>; HttpOnly ## Links -- [owasp](https://owasp.org/www-community/HttpOnly) -- [cwe](https://cwe.mitre.org/data/definitions/1004.html) +- [OWASP](https://owasp.org/www-community/HttpOnly) +- [CWE](https://cwe.mitre.org/data/definitions/1004.html) - [Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) diff --git a/doc/user/application_security/dast/checks/16.1.md b/doc/user/application_security/dast/checks/16.1.md index bb030d2f9c4..157b2b96ed4 100644 --- a/doc/user/application_security/dast/checks/16.1.md +++ b/doc/user/application_security/dast/checks/16.1.md @@ -29,5 +29,5 @@ header to disable user agents from mis-interpreting resources. ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) - [Mozilla Blog on MIME Confusion attacks](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) diff --git a/doc/user/application_security/dast/checks/16.3.md b/doc/user/application_security/dast/checks/16.3.md index e4dcf3ece4b..6f80a2a32c6 100644 --- a/doc/user/application_security/dast/checks/16.3.md +++ b/doc/user/application_security/dast/checks/16.3.md @@ -31,5 +31,5 @@ information from the `X-Powered-By` header. ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) -- [PHP expose_php](https://www.php.net/manual/en/ini.core.php#ini.expose-php) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) +- [PHP `expose_php`](https://www.php.net/manual/en/ini.core.php#ini.expose-php) diff --git a/doc/user/application_security/dast/checks/16.4.md b/doc/user/application_security/dast/checks/16.4.md index c0161c910b0..1f72a80cb29 100644 --- a/doc/user/application_security/dast/checks/16.4.md +++ b/doc/user/application_security/dast/checks/16.4.md @@ -25,4 +25,4 @@ Consult your proxy/load balancer documentation or provider on how to disable rev ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) diff --git a/doc/user/application_security/dast/checks/16.5.md b/doc/user/application_security/dast/checks/16.5.md index 8a6f3cd8b6a..28bb9f7ee4b 100644 --- a/doc/user/application_security/dast/checks/16.5.md +++ b/doc/user/application_security/dast/checks/16.5.md @@ -4,7 +4,7 @@ group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# AspNet Header(s) exposes version information +# AspNet header exposes version information ## Description @@ -26,5 +26,5 @@ section of the `Web.config` file. ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) - [IIS Remove Unwanted Headers](https://techcommunity.microsoft.com/t5/iis-support-blog/remove-unwanted-http-response-headers/ba-p/369710) diff --git a/doc/user/application_security/dast/checks/16.6.md b/doc/user/application_security/dast/checks/16.6.md new file mode 100644 index 00000000000..ddd3a10c5f8 --- /dev/null +++ b/doc/user/application_security/dast/checks/16.6.md @@ -0,0 +1,37 @@ +--- +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 +--- + +# AspNetMvc header exposes version information + +## Description + +The target website returns AspNet header(s) along with version information of this website. By +exposing these values attackers may attempt to identify if the target software is vulnerable to known +vulnerabilities. Or catalog known sites running particular versions to exploit in the future when a +vulnerability is identified in the particular version. + +## Remediation + +To remove the `X-AspNetMvc-Version` information set `MvcHandler.DisableMvcResponseHeader = true;` in the +`Global.asax.cs` file in the `Application_Start()` method. + +```cs +protected void Application_Start() +{ + MvcHandler.DisableMvcResponseHeader = true; +} +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.6 | true | 16 | Passive | Low | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/16.html) +- [IIS Remove Unwanted Headers](https://techcommunity.microsoft.com/t5/iis-support-blog/remove-unwanted-http-response-headers/ba-p/369710) diff --git a/doc/user/application_security/dast/checks/614.1.md b/doc/user/application_security/dast/checks/614.1.md index 74ac73935f1..46f7f61b0c7 100644 --- a/doc/user/application_security/dast/checks/614.1.md +++ b/doc/user/application_security/dast/checks/614.1.md @@ -36,5 +36,5 @@ Set-Cookie: {cookie_name}=<random secure value>; Secure ## Links - [owasp](https://owasp.org/www-community/controls/SecureCookieAttribute) -- [cwe](https://cwe.mitre.org/data/definitions/614.html) +- [CWE](https://cwe.mitre.org/data/definitions/614.html) - [Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) diff --git a/doc/user/application_security/dast/checks/693.1.md b/doc/user/application_security/dast/checks/693.1.md index 07cb368b39a..d3f4c72c676 100644 --- a/doc/user/application_security/dast/checks/693.1.md +++ b/doc/user/application_security/dast/checks/693.1.md @@ -30,7 +30,7 @@ misinterpreted. ## Links -- [owasp](https://owasp.org/www-project-secure-headers/#x-content-type-options) -- [cwe](https://cwe.mitre.org/data/definitions/693.html) +- [OWASP](https://owasp.org/www-project-secure-headers/#x-content-type-options) +- [CWE](https://cwe.mitre.org/data/definitions/693.html) - [Mozilla Blog on MIME Confusion attacks](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) - [Mozilla MDN on X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index f1a68387eb1..a3b89e09751 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -15,6 +15,7 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [16.2](16.2.md) | Server header exposes version information | Low | Passive | | [16.3](16.3.md) | X-Powered-By header exposes version information | Low | Passive | | [16.4](16.4.md) | X-Backend-Server header exposes server information | Info | Passive | -| [16.5](16.5.md) | AspNet Header(s) exposes version information | Low | Passive | +| [16.5](16.5.md) | AspNet header exposes version information | Low | Passive | +| [16.6](16.6.md) | AspNetMvc header exposes version information | Low | Passive | | [614.1](614.1.md) | Sensitive cookie without `Secure` attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 0d8b55a92a9..4de7a566769 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -16,6 +16,10 @@ Dynamic Application Security Testing (DAST) examines applications for vulnerabilities like these in deployed environments. DAST uses the open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. +INFO: +Want to try out security scanning? +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dast-docs). + After DAST creates its report, GitLab evaluates it for discovered vulnerabilities between the source and target branches. Relevant findings are noted in the merge request. @@ -254,7 +258,7 @@ The included template creates a `dast` job in your CI/CD pipeline and scans your project's running application for possible vulnerabilities. The results are saved as a -[DAST report artifact](../../../ci/yaml/index.md#artifactsreportsdast) +[DAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/security-products/dast) @@ -956,9 +960,34 @@ An on-demand scan can be run in active or passive mode: ### View on-demand DAST scans -To view running and completed on-demand DAST scans for a project, go to +To view running completed and scheduled on-demand DAST scans for a project, go to **Security & Compliance > On-demand Scans** in the left sidebar. +- To view both running and completed scans, select **All**. +- To view running scans only, select **Running**. +- To view finished scans, select **Finished**. A finished scan is a scan that either succeeded, + failed, or was canceled. +- To view scheduled scans, select **Scheduled**. It shows on-demand scans that have a schedule + set up. Those are _not_ included in the **All** tab. + +#### Cancel an on-demand scan + +To cancel a pending or running on-demand scan, select **Cancel** (**{cancel}**) in the +on-demand scans list. + +#### Retry an on-demand scan + +To retry a scan that failed or succeeded with warnings, select **Retry** (**{retry}**) in the +on-demand scans list. + +#### View an on-demand scan's results + +To view a finished scan's results, select **View results** in the on-demand scans list. + +#### Edit an on-demand scan + +To edit an on-demand scan's settings, select **Edit** (**{pencil}**) in the **Scheduled** tab. + ### Run an on-demand DAST scan Prerequisites: @@ -1023,7 +1052,7 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. -> - [Feature flag dast_on_demand_scans_scheduler removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. +> - [Feature flag `dast_on_demand_scans_scheduler` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. To schedule a scan: @@ -1344,27 +1373,6 @@ The DAST tool always emits a JSON report file called `gl-dast-report.json` and sample reports can be found in the [DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect). -### Other formats - -Reports can also be generated in Markdown, HTML, and XML. These can be published as artifacts using the following configuration: - -```yaml -include: - template: DAST.gitlab-ci.yml - -dast: - variables: - DAST_HTML_REPORT: report.html - DAST_MARKDOWN_REPORT: report.md - DAST_XML_REPORT: report.xml - artifacts: - paths: - - $DAST_HTML_REPORT - - $DAST_MARKDOWN_REPORT - - $DAST_XML_REPORT - - gl-dast-report.json -``` - ## Optimizing DAST By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index f3ab25ccffa..0db5fb2d868 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -1138,7 +1138,7 @@ A bug exists in versions of the DAST API analyzer prior to v1.6.196 that can cau The version information can be found in the job details for the `dast_api` job. -If the issue is occuring with versions v1.6.196 or greater, please contact Support and provide the following information: +If the issue is occurring with versions v1.6.196 or greater, please contact Support and provide the following information: 1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. 1. The full console output of the job. @@ -1209,6 +1209,25 @@ deploy-test-target: - environment_url.txt ``` +## Get support or request an improvement + +To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). + +The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and DAST API. +Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](../../../development/code_review.md#review-response-slo) to understand when you should receive a response. + +[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. + +When experiencing a behavior not working as expected, consider providing contextual information: + +- GitLab version if using a self-managed instance. +- `.gitlab-ci.yml` job definition. +- Full job console output. +- Scanner log file available as a job artifact named `gl-api-security-scanner.log`. + +WARNING: +**Sanitize data attached to a support issue**. Please remove sensitive information, including: credentials, passwords, tokens, keys, and secrets. + ## Glossary - Assert: Assertions are detection modules used by checks to trigger a vulnerability. Many assertions have diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index b0d8af2606f..baafdcda6e0 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency list **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab 12.0. +> - Application dependencies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab 12.0. +> - System dependencies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6698) in GitLab 14.6. 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. @@ -22,8 +23,9 @@ The dependency list only shows the results of the last successful pipeline to ru To view your project's dependencies, ensure you meet the following requirements: -- The [Dependency Scanning](../dependency_scanning/index.md) CI job must be - configured for your project. +- The [Dependency Scanning](../dependency_scanning/index.md) + or [Container Scanning](../container_scanning/index.md) + CI job must be configured for your project. - Your project uses at least one of the [languages and package managers](../dependency_scanning/index.md#supported-languages-and-package-managers) supported by Gemnasium. @@ -38,7 +40,7 @@ GitLab displays dependencies with the following information: |-----------|-------------| | Component | The dependency's name and version. | | Packager | The packager used to install the dependency. | -| Location | A link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | +| Location | For system dependencies, this lists the image that was scanned. For application dependencies, this shows a link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | | License | Links to dependency's software licenses. | Displayed dependencies are initially sorted by the severity of their known vulnerabilities, if any. They @@ -63,6 +65,7 @@ Dependency paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) - [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) +- [sbt](https://www.scala-sbt.org) ## Licenses @@ -82,4 +85,4 @@ You can download your project's list of dependencies and their details in JSON f ### 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). +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/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 8559d5af02e..1b502b306bb 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -32,6 +32,9 @@ to launch dedicated containers for each analysis. Dependency Scanning is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. +WARNING: +The `bundler-audit` analyzer is deprecated and will be removed in GitLab 15.0 since it duplicates the functionality of the `gemnasium` analyzer. For more information, read the [deprecation announcement](../../../update/deprecations.md#deprecation-of-bundler-audit-dependency-scanning-tool). + ## Official default analyzers Any custom change to the official analyzers can be achieved by using a @@ -118,12 +121,12 @@ The following table lists the data available for each official analyzer. | File | ✓ | ⚠ | ✓ | | Start line | 𐄂 | 𐄂 | 𐄂 | | End line | 𐄂 | 𐄂 | 𐄂 | -| External ID (e.g., CVE) | ✓ | ✓ | ⚠ | +| External ID (for example, CVE) | ✓ | ✓ | ⚠ | | URLs | ✓ | ✓ | ✓ | | Internal doc/explanation | ✓ | 𐄂 | 𐄂 | | Solution | ✓ | ✓ | 𐄂 | | Confidence | 𐄂 | 𐄂 | 𐄂 | -| Affected item (e.g. class or package) | ✓ | ✓ | ✓ | +| Affected item (for example, class or package) | ✓ | ✓ | ✓ | | Source code extract | 𐄂 | 𐄂 | 𐄂 | | Internal ID | ✓ | 𐄂 | 𐄂 | | Date | ✓ | 𐄂 | 𐄂 | @@ -134,4 +137,4 @@ The following table lists the data available for each official analyzer. - 𐄂 => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it. The values provided by these tools are heterogeneous, so they are sometimes -normalized into common values (e.g., `severity`, `confidence`, etc). +normalized into common values (for example, `severity`, `confidence`, etc). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 3c6db8c3ee9..192d8449297 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -7,10 +7,43 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning **(ULTIMATE)** +INFO: +Try out Dependency Scanning in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dependency-scanning-docs). + The Dependency Scanning feature can automatically find security vulnerabilities in your -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 -vulnerable. You can then take action to protect your application. +software dependencies while you're developing and testing your applications. For example, +dependency scanning lets you know if your application uses an external (open source) +library that is known to be vulnerable. You can then take action to protect your application. + +Dependency Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain +aspects of inspecting the items your code uses. These items typically include application and system +dependencies that are almost always imported from external sources, rather than sourced from items +you wrote yourself. + +GitLab offers both Dependency Scanning and Container Scanning +to ensure coverage for all of these dependency types. To cover as much of your risk area as +possible, we encourage you to use all of our security scanners: + +- Dependency Scanning analyzes your project and tells you which software dependencies, + including upstream dependencies, have been included in your project, and what known + risks the dependencies contain. Dependency Scanning modifies its behavior based + on the language and package manager of the project. It typically looks for a lock file + then performs a build to fetch upstream dependency information. In the case of + containers, Dependency Scanning uses the compatible manifest and reports only these + declared software dependencies (and those installed as a sub-dependency). + Dependency Scanning can not detect software dependencies that are pre-bundled + into the container's base image. To identify pre-bundled dependencies, enable + [Container Scanning](../container_scanning/) language scanning using the + [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/#report-language-specific-findings). +- [Container Scanning](../container_scanning/) analyzes your containers and tells + you about known risks in the operating system's (OS) packages. You can configure it + to also report on software and language dependencies, if you enable it and use + the [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/#report-language-specific-findings). + Turning this variable on can result in some duplicate findings, as we do not yet + de-duplicate results between Container Scanning and Dependency Scanning. For more details, + efforts to de-duplicate these findings can be tracked in + [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348655). ## Overview @@ -142,7 +175,7 @@ table.supported-languages ul { <tr> <td>Go</td> <td>N/A</td> - <td><a href="https://golang.org/">Go</a></td> + <td><a href="https://go.dev/">Go</a></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> @@ -279,10 +312,10 @@ table.supported-languages ul { GitLab analyzers obtain dependency information using one of the following two methods: -1. [Parsing lockfiles directly.](#obtaining-dependendency-information-by-parsing-lockfiles) -1. [Running a package manager or build tool to generate a dependency information file which is then parsed.](#obtaining-dependendency-information-by-running-a-package-manager-to-generate-a-parsable-file) +1. [Parsing lockfiles directly.](#obtaining-dependency-information-by-parsing-lockfiles) +1. [Running a package manager or build tool to generate a dependency information file which is then parsed.](#obtaining-dependency-information-by-running-a-package-manager-to-generate-a-parsable-file) -#### Obtaining dependendency information by parsing lockfiles +#### Obtaining dependency information by parsing lockfiles The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: @@ -296,7 +329,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/master/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/lockfile-v2-FREEZE/package-lock.json#L4) | | yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/js-yarn/-/blob/master/yarn.lock) | -#### Obtaining dependendency information by running a package manager to generate a parsable file +#### Obtaining dependency information by running a package manager to generate a parsable file To support the following package managers, the GitLab analyzers proceed in two steps: @@ -309,7 +342,7 @@ To support the following package managers, the GitLab analyzers proceed in two s | sbt | [1.3.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L263), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L272), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L281), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L290), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L299) | | Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | | Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5) | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3) | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | | pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | | Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | @@ -370,7 +403,7 @@ We only execute one build in the directory where a build file has been detected, Please note, we support the following types of Java project structures: - [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-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 @@ -425,7 +458,7 @@ include: The included template creates dependency scanning jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[dependency scanning report artifact](../../../ci/yaml/index.md#artifactsreportsdependency_scanning) +[dependency scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsdependency_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest dependency scanning artifact available. @@ -440,7 +473,7 @@ from the Security Configuration page. 1. In the project where you want to enable Dependency Scanning, navigate to **Security & Compliance > Configuration**. -1. In the **Dependency Scanning** row, select **Configure via Merge Request**. +1. In the **Dependency Scanning** row, select **Configure with a merge request**. This automatically creates a merge request with the changes necessary to enable Dependency Scanning that you can review and merge to complete the configuration. @@ -506,7 +539,7 @@ The following variables allow configuration of global dependency scanning settin | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | | `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_DEFAULT_ANALYZERS` | ([**DEPRECATED - use `DS_EXCLUDED_ANALYZERS` instead**](https://gitlab.com/gitlab-org/gitlab/-/issues/287691)) Override the names of the official default images. For more information, see [Dependency Scanning Analyzers](analyzers.md). | -| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | +| `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SECURE_LOG_LEVEL` | 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. Default: `info`. | @@ -596,7 +629,7 @@ The dependency scanning tool emits a JSON report file. For more information, see Here's an example dependency scanning report: -```json-doc +```json { "version": "2.0", "vulnerabilities": [ @@ -709,7 +742,7 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s ## Contributing to the vulnerability database -You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project +You can search the [`gemnasium-db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project to find a vulnerability in the Gemnasium database. You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). @@ -781,7 +814,7 @@ Support for custom certificate authorities was introduced in the following versi Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry. You must also change the value of `GEMNASIUM_DB_REMOTE_URL` to the location of your offline Git copy of the -[gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/): +[`gemnasium-db` advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/): ```yaml include: @@ -1033,3 +1066,19 @@ scan occurs. Because the cache is downloaded before the analyzer run occurs, the file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. We recommend committing the lock files, which prevents this warning. + +### I no longer get the latest Docker image after setting `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` + +If you have manually set `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` for specific reasons, +and now must update your configuration to again get the latest patched versions of our +analyzers, edit your `gitlab-ci.yml` file and either: + +- Set your `DS_MAJOR_VERSION` to match the latest version as seen in + [our current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml#L18). +- If you hardcoded the `DS_ANALYZER_IMAGE` variable directly, change it to match the latest + line as found in our [current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml). + The line number will vary depending on which scanning job you edited. + + For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest + `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to + `"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"`. diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index a58a00a869b..c17ebc68b4d 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -32,14 +32,14 @@ GitLab IaC scanning supports a variety of IaC configuration files. Our IaC secur | Configuration File Type | Scan tool | Introduced in GitLab Version | |------------------------------------------|----------------------------------|-------------------------------| -| Ansible | [kics](https://kics.io/) | 14.5 | -| AWS CloudFormation | [kics](https://kics.io/) | 14.5 | -| Kubernetes | [kics](https://kics.io/) | 14.5 | -| Terraform | [kics](https://kics.io/) | 14.5 | +| Ansible | [KICS](https://kics.io/) | 14.5 | +| AWS CloudFormation | [KICS](https://kics.io/) | 14.5 | +| Kubernetes | [KICS](https://kics.io/) | 14.5 | +| Terraform | [KICS](https://kics.io/) | 14.5 | ### Making IaC analyzers available to all GitLab tiers -All open source (OSS) analyzers are availibile with the GitLab Free tier. Future propietary analyzers may be restricted to higher tiers. +All open source (OSS) analyzers are available with the GitLab Free tier. Future proprietary analyzers may be restricted to higher tiers. #### Summary of features per tier @@ -74,7 +74,7 @@ The included template creates IaC scanning jobs in your CI/CD pipeline and scans your project's configuration files for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/yaml/index.md#artifactsreportssast) +[SAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssast) that you can download and analyze. ### Enable IaC Scanning via an automatic merge request @@ -84,7 +84,7 @@ from the Security Configuration page: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. -1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure via Merge Request**. +1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. This automatically creates a merge request with the changes necessary to enable IaC Scanning that you can review and merge to complete the configuration. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index d5e801ced9c..5500f5a10c4 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -16,6 +16,10 @@ GitLab can check your application for security vulnerabilities including: Statistics and details on vulnerabilities are included in the merge request. Providing actionable information _before_ changes are merged enables you to be proactive. +INFO: +Want to try out security scanning? +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-application-security-docs). + GitLab also provides high-level statistics of vulnerabilities across projects and groups: - The [Security Dashboard](security_dashboard/index.md) provides a @@ -42,7 +46,7 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | -| [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) | Analyze your IaC coniguration files for known vulnerabilities. | +| [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) | Analyze your IaC configuration files for known vulnerabilities. | | [Coverage fuzzing](coverage_fuzzing/index.md) | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | | [Cluster Image Scanning](cluster_image_scanning/index.md) | Scan Kubernetes clusters for known vulnerabilities. | diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_3.png b/doc/user/application_security/policies/img/security_policy_project_v14_3.png Binary files differdeleted file mode 100644 index 5e3aefaeb81..00000000000 --- a/doc/user/application_security/policies/img/security_policy_project_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_6.png b/doc/user/application_security/policies/img/security_policy_project_v14_6.png Binary files differnew file mode 100644 index 00000000000..feea1b1b01c --- /dev/null +++ b/doc/user/application_security/policies/img/security_policy_project_v14_6.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 4d8be411dc5..e6dbd96537f 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -159,8 +159,8 @@ at the bottom of the editor. You can use policy alerts to track your policy's impact. Alerts are only available if you've [installed](../../clusters/agent/repository.md) -and [configured](../../clusters/agent/install/index.md#create-an-agent-record-in-gitlab) -a Kubernetes Agent for this project. +and [configured](../../clusters/agent/install/index.md#register-an-agent-with-gitlab) +an agent for this project. There are two ways to create policy alerts: @@ -228,7 +228,13 @@ must create an association between that project and the project you want to appl project you would like to link from the dropdown menu. 1. Select **Save**. -  +  + +### Unlink Security Policy projects + +Project owners can unlink Security Policy projects from development projects. To do this, follow +the steps described in [Security Policy project selection](#security-policy-project-selection), +but select the trash can icon in the modal. ### Scan Execution Policy editor @@ -237,9 +243,9 @@ Only project Owners have the [permissions](../../permissions.md#project-members- to select Security Policy Project. Once your policy is complete, save it by selecting **Create merge request** -at the bottom of the editor. You will be redirected to the merge request on the project's +at the bottom of the editor. You are redirected to the merge request on the project's configured security policy project. If one does not link to your project, a security -policy project will be automatically created. Existing policies can also be +policy project is automatically created. Existing policies can also be removed from the editor interface by selecting **Delete policy** at the bottom of the editor. @@ -287,7 +293,7 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | -| `clusters` | `object` | | The cluster where the given policy will enforce running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that will be scanned. | +| `clusters` | `object` | | The cluster where the given policy enforces running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. | #### `cluster` schema @@ -295,10 +301,10 @@ Use this schema to define `clusters` objects in the [`schedule` rule type](#sche | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | -| `resources` | `array` of `string` | | The resource name that will be scanned (only the first value is currently supported). | -| `namespaces` | `array` of `string` | | The namespace that will be scanned (only the first value is currently supported). | -| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | +| `containers` | `array` of `string` | | The container name to be scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name to be scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace to be scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind to be scanned (only the first value is currently supported). | ### `scan` action type @@ -307,9 +313,10 @@ rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `dast`, `secret_detection` | The action's type. | +| `scan` | `string` | `dast`, `secret_detection`, `sast`, `container_scanning`, `cluster_image_scanning` | The action's type. | | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | | `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| +| `variables` | `object` | | Set of variables applied and enforced for the selected scan. The object's key is the variable name with a value provided as a string. | Note the following: @@ -327,9 +334,10 @@ Note the following: - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-detection) mode when executed as part of a scheduled scan. -- A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. - They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. +- A container scanning and cluster image scanning scans configured for the `pipeline` rule type ignores the cluster defined in the `clusters` object. + They use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). +- The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/parent_child_pipelines.md). ### Example security policies project @@ -357,7 +365,7 @@ scan_execution_policy: - type: schedule branches: - main - cadence: */10 * * * * + cadence: "*/10 * * * *" actions: - scan: dast scanner_profile: Scanner Profile C @@ -372,13 +380,16 @@ scan_execution_policy: - main actions: - scan: secret_detection + - scan: sast + variables: + SAST_EXCLUDED_ANALYZERS: brakeman - scan: container_scanning - name: Enforce Cluster Image Scanning on production-cluster every 24h description: This policy enforces Cluster Image Scanning scan to run every 24 hours enabled: true rules: - type: schedule - cadence: '15 3 * * *' + cadence: "15 3 * * * clusters: production-cluster: containers: @@ -399,7 +410,8 @@ In this example: `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 and container scanning scans run for every pipeline executed on the `main` branch. +- Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` + branch. The SAST scan runs with the `SAST_EXCLUDED_ANALYZER` variable set to `"brakeman"`. - Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 06c57e68121..8c7e03f69fd 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -59,7 +59,7 @@ support the following features: ## Official default analyzers Any custom change to the official analyzers can be achieved by using a -[CI/CD variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). +[CI/CD variable in your `.gitlab-ci.yml`](index.md#available-cicd-variables). ### Using a custom Docker mirror diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index af8585c6a18..fd05ecad8f2 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -144,7 +144,7 @@ as shown in the following table: | Capability | In Free | In Ultimate | |:---------------------------------------------------------------------------------------|:--------------------|:-------------------| | [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -184,7 +184,7 @@ The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/yaml/index.md#artifactsreportssast) +[SAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssast) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. @@ -242,25 +242,6 @@ The configuration tool works best with no existing `.gitlab-ci.yml` file, or wit configuration file. If you have a complex GitLab configuration file it may not be parsed successfully, and an error may occur. -### Customizing the SAST settings - -The SAST settings can be changed through [CI/CD variables](#available-cicd-variables) -by using the -[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. -In the following example, we include the SAST template and at the same time we -set the `SAST_GOSEC_LEVEL` variable to `2`: - -```yaml -include: - - template: Security/SAST.gitlab-ci.yml - -variables: - SAST_GOSEC_LEVEL: 2 -``` - -Because the template is [evaluated before](../../../ci/yaml/index.md#include) -the pipeline configuration, the last mention of the variable takes precedence. - ### Overriding SAST jobs WARNING: @@ -305,16 +286,16 @@ spotbugs-sast: ### Customize rulesets **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for +> passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. You can customize the default scanning rules provided by our SAST analyzers. +Ruleset customization supports two capabilities that can be used +simultaneously: -Ruleset customization supports two capabilities: - -1. Disabling predefined rules (available for all analyzers). -1. Modifying the default behavior of a given analyzer (only available for `nodejs-scan` and `gosec`). - -These capabilities can be used simultaneously. +- [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). Available for all analyzers. +- Modifying the default behavior of a given analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`. To customize the default scanning rules, create a file containing custom rules. These rules are passed through to the analyzer's underlying scanner tools. @@ -323,81 +304,303 @@ To create a custom ruleset: 1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. 1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. -1. In the `sast-ruleset.toml` file, do one of the following: - - - Disable predefined rules belonging to SAST analyzers. In this example, the three disabled rules - belong to `eslint` and `sobelow` by matching the corresponding identifiers' `type` and `value`: - - ```toml - [eslint] - [[eslint.ruleset]] - disable = true - [eslint.ruleset.identifier] - type = "eslint_rule_id" - value = "security/detect-object-injection" - - [[eslint.ruleset]] - disable = true - [eslint.ruleset.identifier] - type = "cwe" - value = "185" - - [sobelow] - [[sobelow.ruleset]] - disable = true - [sobelow.ruleset.identifier] - type = "sobelow_rule_id" - value = "sql_injection" - ``` - - - Define a custom analyzer configuration. In this example, customized rules are defined for the - `nodejs-scan` scanner: - - ```toml - [nodejs-scan] - description = 'custom ruleset for nodejs-scan' - - [[nodejs-scan.passthrough]] - type = "raw" - value = ''' - - nodejs-extensions: - - .js - - template-extensions: - - .new - - .hbs - - '' - - ignore-filenames: - - skip.js - - ignore-paths: - - __MACOSX - - skip_dir - - node_modules - - ignore-extensions: - - .hbs - - ignore-rules: - - regex_injection_dos - - pug_jade_template - - express_xss - - ''' - ``` - - - Provide the name of the file containing a custom analyzer configuration. In this example, - customized rules for the `gosec` scanner are contained in the file `gosec-config.json`: - - ```toml - [gosec] - description = 'custom ruleset for gosec' - - [[gosec.passthrough]] - type = "file" - value = "gosec-config.json" - ``` + +#### Disable predefined analyzer rules + +To disable analyzer rules: + +1. Set the `disabled` flag to `true` in the context of a `ruleset` section + +1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: + +- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. + +- a `value` field, to name the rule to be disabled. + +##### Example: Disable predefined rules of SAST analyzers + +In the following example, the disabled rules are assigned to `eslint` +and `sobelow` by matching the `type` and `value` of identifiers: + +```toml +[eslint] + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "eslint_rule_id" + value = "security/detect-object-injection" + + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "cwe" + value = "185" + +[sobelow] + [[sobelow.ruleset]] + disable = true + [sobelow.ruleset.identifier] + type = "sobelow_rule_id" + value = "sql_injection" +``` + +#### Synthesize a custom configuration + +To create a custom configuration, you can use passthrough chains. + +A passthrough is a single step in a passthrough chain. The passthrough is evaluated +in a sequence to incrementally build a configuration. The configuration is then +passed to the target analyzer. + +A configuration section for an analyzer has the following +parameters: + +| Parameter | Explanation | +| ------------- | ------ | +| `description` | Description about the analyzer configuration section. | +| `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. | +| `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. | +| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | +| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | + +A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20. +There are several types of passthroughs: + +| Type | Description | +| ------ | ------ | +| `file` | Use a file that is already available in the Git repository. | +| `raw` | Provide the configuration inline. | +| `git` | Pull the configuration from a remote Git repository. | +| `url` | Fetch the analyzer configuration through HTTP. | + +If multiple passthrough sections are defined in a passthrough chain, their +position in the chain defines the order in which they are evaluated. + +- Passthroughs listed later in the chain sequence have a higher precedence. +- Passthroughs with a higher precedence overwrite (default) and append data + yielded by previous passthroughs. This is useful for cases where you need to + use or modify an existing configuration. + +Configure a passthrough these parameters: + +| Parameter | Explanation | +| ------------ | ----------- | +| `type` | One of `file`, `raw`, `git` or `url`. | +| `target` | The target file that contains the data written by the passthrough evaluation. If no value is provided, a random target file is generated. | +| `mode` | `overwrite`: if `target` exists, overwrites the file; `append`: append to file instead. The default is `overwrite`. | +| `ref` | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. | +| `subdir` | This option only applies to the `git` passthrough type and can be used to only consider a certain subdirectory of the source Git repository. | +| `value` | For the `file` `url` and `git` types, `value` defines the source location of the file/Git repository; for the `raw` type, `value` carries the raw content to be passed through. | +| `validator` | Can be used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target files after the application of a passthrough. Per default, no validator is set. | + +The amount of data generated by a single passthrough is limited to 1MB. + +#### Passthrough configuration examples + +##### Raw passthrough for nodejs-scan + +Define a custom analyzer configuration. In this example, customized rules are +defined for the `nodejs-scan` scanner: + +```toml +[nodejs-scan] + description = 'custom ruleset for nodejs-scan' + + [[nodejs-scan.passthrough]] + type = "raw" + value = ''' +- nodejs-extensions: + - .js + + template-extensions: + - .new + - .hbs + - '' + + ignore-filenames: +- skip.js + + ignore-paths: + - __MACOSX + - skip_dir + - node_modules + + ignore-extensions: + - .hbs + + ignore-rules: + - regex_injection_dos + - pug_jade_template + - express_xss + +''' +``` + +##### File passthrough for gosec + +Provide the name of the file containing a custom analyzer configuration. In +this example, customized rules for the `gosec` scanner are contained in the +file `gosec-config.json`: + +```toml +[gosec] + description = 'custom ruleset for gosec' + + [[gosec.passthrough]] + type = "file" + value = "gosec-config.json" +``` + +##### Passthrough chain for semgrep + +In the below example, we generate a custom configuration under the `/sgrules` +target directory with a total `timeout` of 60 seconds. + +Several passthrouh types generate a configuration for the target analyzer: + +- Two `git` passthrough sections pull the head of branch + `refs/remotes/origin/test` from the `myrules` Git repository, and revision + `97f7686` from the `sast-rules` Git repostory. From the `sast-rules` Git + repository, only data from the `go` subdirectory is considered. + - The `sast-rules` entry has a higher precedence because it appears later in + the configuration. + - If there is a filename collision between files in both repositories, files + from the `sast` repository overwrite files from the `myrules` repository, + as `sast-rules` has higher precedence. +- The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The + full path is `/sgrules/insecure.yml`. +- The `url` entry fetches a configuration made available through a URL and + stores it in the `/sgrules/gosec.yml` file. + +Afterwards, semgrep is invoked with the final configuration located under +`/sgrules`. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + timeout = 60 + + [[semgrep.passthrough]] + type = "git" + value = "https://gitlab.com/user/myrules.git" + ref = "refs/remotes/origin/test" + + [[semgrep.passthrough]] + type = "git" + value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git" + ref = "97f7686db058e2141c0806a477c1e04835c4f395" + subdir = "go" + + [[semgrep.passthrough]] + type = "raw" + target = "insecure.yml" + value = """ +rules: +- id: "insecure" + patterns: + - pattern: "func insecure() {...}" + message: | + Insecure function insecure detected + metadata: + cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor" + severity: "ERROR" + languages: + - "go" + """ + + [[semgrep.passthrough]] + type = "url" + value = "https://semgrep.dev/c/p/gosec" + target = "gosec.yml" +``` + +##### Interpolation + +The code snippet below shows an example configuration that uses an environment +variable `$GITURL` to access a private repositories with a Git URL. The variable contains +a username and token in the `value` field (for example `https://user:token@url`). +It does not explicitly store credentials in the configuration file. To reduce the risk of leaking secrets through created paths and files, use this feature with caution. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + interpolate = true + + [[semgrep.passthrough]] + type = "git" + value = "$GITURL" + ref = "refs/remotes/origin/main" +``` + +##### Configure the append mode for passthroughs + +To append data to previous passthroughs, use the `append` mode for the +passthrough types `file`, `url`, and `raw`. + +Passthroughs in `override` mode overwrite files +created when preceding passthroughs in the chain find a naming +collision. If `mode` is set to `append`, a passthrough appends data to the +files created by its predecessors instead of overwriting. + +In the below semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: + +- `insecure` +- `secret` + +These rules add a search pattern to the analyzer and extends semgrep capabilities. + +For passthrough chains we recommend that you enable validation. To enable validation, +you can either: + +- set `validate` to `true` + +- set a passthrough `validator` to `xml`, `json`, `yaml`, or `toml`. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + validate = true + + [[semgrep.passthrough]] + type = "raw" + target = "insecure.yml" + value = """ +rules: +- id: "insecure" + patterns: + - pattern: "func insecure() {...}" + message: | + Insecure function insecure detected + metadata: + cwe: "... + severity: "ERROR" + languages: + - "go" +""" + + [[semgrep.passthrough]] + type = "raw" + mode = "append" + target = "insecure.yml" + value = """ +- id: "secret" + patterns: + - pattern-either: + - pattern: "$MASK = \"...\"" + - metavariable-regex: + metavariable: "$MASK" + regex: "(password|pass|passwd|pwd|secret|token)" + message: | + Use of Hard-coded Password + cwe: "..." + severity: "ERROR" + languages: + - "go" +""" +``` ### False Positive Detection **(ULTIMATE)** @@ -483,7 +686,20 @@ can use `MAVEN_REPO_PATH`. See ### Available CI/CD variables -SAST can be [configured](#customizing-the-sast-settings) using CI/CD variables. +SAST can be configured using the [`variables`](../../../ci/yaml/index.md#variables) parameter in +`.gitlab-ci.yml`. + +The following example includes the SAST template to override the `SAST_GOSEC_LEVEL` +variable to `2`. The template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline +configuration, so the last mention of the variable takes precedence. + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml + +variables: + SAST_GOSEC_LEVEL: 2 +``` #### Logging level diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 140f660d729..b5e54e35e58 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -34,33 +34,8 @@ GitLab displays identified secrets visibly in a few places: ## Supported secrets Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). - -The [default ruleset provided by TruffleHog and 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) - - Google Cloud Platform (GCP) - - Heroku API -- Encryption keys: - - PKCS8 - - RSA - - SSH - - PGP - - DSA - - EC -- Social media platforms: - - Facebook API - - Twitter API -- Cloud SaaS vendors: - - GitHub API - - Shopify API - - Slack Token - - Slack Webhook - - Stripe API - - Twilio API - - Generic API key strings starting with `api-` -- Password in URL -- U.S. Social Security Number +The [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes **90+ secret detection patterns**. +You can contribute "well-identifiable" secrets by follow the steps detailed in the [community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). WARNING: Gitleaks does not support scanning binary files. @@ -134,7 +109,7 @@ The included template creates Secret Detection jobs in your CI/CD pipeline and s your project's source code for secrets. The results are saved as a -[Secret Detection report artifact](../../../ci/yaml/index.md#artifactsreportssecret_detection) +[Secret Detection report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssecret_detection) that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. @@ -148,10 +123,10 @@ from the Security Configuration page. 1. In the project where you want to enable Secret Detection, go to **Security & Compliance > Configuration**. -1. In the **Secret Detection** row, select **Configure via Merge Request**. +1. In the **Secret Detection** row, select **Configure with a merge request**. This automatically creates a merge request with the changes necessary to enable Secret Detection -that you can review and merge to complete the configuration. +that you can review and merge to complete the configuration. NOTE: The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal @@ -210,10 +185,12 @@ Secret Detection can be customized by defining available CI/CD variables: ### Custom rulesets **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for +> passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. You can customize the default secret detection rules provided with GitLab. -Customization allows replace the default secret detection rules with rules that you define. +Customization allows replacing the default secret detection rules with rules that you define. To create a custom ruleset: @@ -251,6 +228,9 @@ To create a custom ruleset: value = "config/gitleaks.toml" ``` +Passthroughs can also be chained to build more complex configurations. +For more details, see [SAST Customize ruleset section](../sast/index.md#customize-rulesets). + ### Logging level To control the verbosity of logs set the `SECURE_LOG_LEVEL` CI/CD variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png Binary files differindex ac123d2b528..ad9122ee23c 100644 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 87875ec15ba..5afbe1ca54e 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -7,6 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboards and Security Center **(ULTIMATE)** +INFO: +Want to try out security scanning? +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-security-dashboard-docs). + GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: - Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [groups](#group-security-dashboard), and diff --git a/doc/user/application_security/vulnerability_report/img/operational_vulnerability_tab_v14_6.png b/doc/user/application_security/vulnerability_report/img/operational_vulnerability_tab_v14_6.png Binary files differnew file mode 100644 index 00000000000..52a298584dd --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/operational_vulnerability_tab_v14_6.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index d13647937a2..3773bb59c5a 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -7,8 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** -The Vulnerability Report provides information about vulnerabilities from scans of the branch most -recently merged into the default branch. It is available for groups, projects, and the Security Center. +The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It is available for projects, groups, and the Security Center. At all levels, the Vulnerability Report contains: @@ -215,3 +214,12 @@ You can dismiss a vulnerability for the entire project: 1. Optional. Add a reason for the dismissal and select **Save comment**. To undo this action, select a different status from the same menu. + +## Operational vulnerabilities + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6345) in GitLab 14.6. + +The **Operational vulnerabilities** tab lists vulnerabilities found by the `cluster_image_scanner`. +This tab appears on the project, group, and Security Center vulnerability reports. + + diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index cd166666ad6..da75c008ed1 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -492,10 +492,13 @@ image::screenshot.png[block image,800,450] Press image:reload.svg[reload,16,opts=interactive] to reload the page. video::movie.mp4[width=640,start=60,end=140,options=autoplay] +``` -video::aHjpOzsQ9YI[youtube] +GitLab does not support embedding YouTube and Vimeo videos in AsciiDoc content. +Use a standard AsciiDoc link: -video::300817511[vimeo] +```plaintext +https://www.youtube.com/watch?v=BlaZ65-b7y0[Link text for the video] ``` ### Breaks diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 88651688779..e4fcdcd4653 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -10,7 +10,7 @@ When you're collaborating online, you get fewer opportunities for high-fives and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md), [snippets](snippets.md), and anywhere you can have a thread. - + Award emoji make it much easier to give and receive feedback without a long comment thread. @@ -34,11 +34,9 @@ downvotes. Award emoji can also be applied to individual comments when you want to celebrate an accomplishment or agree with an opinion. -To: +To add an award emoji: -- Add an award emoji, click the smile in the top right of the comment and pick an emoji from the dropdown. -- Remove an award emoji, click the emoji again. +1. In the top right of the comment, select the smile (**{slight-smile}**). +1. Select an emoji from the dropdown list. - - - +To remove an award emoji, select the emoji again. diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 0dfdb37dc1f..93768164df2 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -19,11 +19,11 @@ Only CI/CD jobs set in the configuration project can access one of the configure ## Prerequisites -- A running [`kas` instance](install/index.md#set-up-the-kubernetes-agent-server). -- A [configuration repository](install/index.md#define-a-configuration-repository) with an Agent config file +- A running [`kas` instance](install/index.md#set-up-the-agent-server). +- A [configuration repository](install/index.md#define-a-configuration-repository) with an agent config file installed (`.gitlab/agents/<agent-name>/config.yaml`). -- An [Agent record](install/index.md#create-an-agent-record-in-gitlab). -- The Agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster). +- A [registered agent](install/index.md#register-an-agent-with-gitlab). +- The agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster). ## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 80b9f3f17f5..c950a4f0dc0 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,19 +4,24 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Kubernetes Agent **(FREE)** +# GitLab Agent for Kubernetes **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in GitLab 13.4. > - Support for `grpcs` [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) in GitLab 13.10, KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. -> - Introduced in GitLab 13.11, the GitLab Kubernetes Agent became available to every project on GitLab.com. -> - The GitLab Kubernetes Agent was [moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. +> - Introduced in GitLab 13.11, the GitLab Agent became available to every project on GitLab.com. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. +> - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab Agent for Kubernetes" in GitLab 14.6. -The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) ("Agent", for short) +The [GitLab Agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) ("Agent", for short) is an active in-cluster component for connecting Kubernetes clusters to GitLab safely to support cloud-native deployment, management, and monitoring. The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution. +INFO: +Get Network Security Alerts in GitLab by upgrading to Ultimate. +[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-cluster-agent-docs). + With GitOps, you can manage containerized clusters and applications from a Git repository that: - Is the single source of truth of your system. @@ -34,7 +39,7 @@ the all-in-one DevOps platform for your product and your team. ## Agent's features -By using the GitLab Kubernetes Agent, you can: +By using the Agent, you can: - Connect GitLab with a Kubernetes cluster behind a firewall or a Network Address Translation (NAT). @@ -49,7 +54,7 @@ from GitLab CI/CD jobs while keeping the cluster's APIs safe and unexposed to the internet. - [Deploy the GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html). -See the [GitLab Kubernetes Agent roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) to track its development. +See the [Agent roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) to track its development. To contribute to the Agent, see the [Agent's development documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc). @@ -64,7 +69,7 @@ sequenceDiagram participant D as Developer participant A as Application code repository participant M as Manifest repository - participant K as Kubernetes Agent + participant K as GitLab Agent participant C as Agent configuration repository loop Regularly K-->>C: Grab the configuration @@ -81,7 +86,7 @@ For more details, refer to our [architecture documentation](https://gitlab.com/g ## Install the Agent in your cluster -See how to [install the GitLab Kubernetes Agent in your cluster](install/index.md). +See how to [install the Agent in your cluster](install/index.md). ## GitOps deployments **(PREMIUM)** @@ -129,7 +134,28 @@ with the following differences: - When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). - You do not need to specify the `gitops` configuration section. -## Remove the GitLab Kubernetes Agent +## Remove an agent + +1. Get the `<cluster-agent-id>` and the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. +For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. +For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your own instance's URL. + + ```graphql + query{ + project(fullPath: "<full-path-to-agent-configuration-project>") { + clusterAgent(name: "<agent-name>") { + id + tokens { + edges { + node { + id + } + } + } + } + } + } + ``` 1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. @@ -158,7 +184,7 @@ with the following differences: } ``` -1. Delete the GitLab Kubernetes Agent in your cluster: +1. Delete the Agent in your cluster: ```shell kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml @@ -166,14 +192,14 @@ with the following differences: ## Troubleshooting -If you face any issues while using GitLab Kubernetes Agent, you can read the -service logs with the following command +If you face any issues while using the Agent, read the +service logs with the following command: ```shell kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent ``` -GitLab administrators can additionally view the [Kubernetes Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). +GitLab administrators can additionally view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). ### Agent logs diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index fad9d4f08f1..cf8467a8d28 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -4,11 +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 --- -# Install the GitLab Kubernetes Agent **(FREE)** +# Install the GitLab Agent **(FREE)** -> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. +> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. -To get started with the GitLab Kubernetes Agent, install it in your cluster. +To get started with the Agent, install it in your cluster. Pre-requisites: @@ -17,24 +17,24 @@ Pre-requisites: ## Installation steps -To install the [GitLab Kubernetes Agent](../index.md) in your cluster: +To install the [Agent](../index.md) in your cluster: -1. [Set up the Kubernetes Agent Server](#set-up-the-kubernetes-agent-server) for your GitLab instance. +1. [Set up the Agent Server](#set-up-the-agent-server) for your GitLab instance. 1. [Define a configuration repository](#define-a-configuration-repository). -1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). -1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). -1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). +1. [Register an agent with GitLab](#register-an-agent-with-gitlab). +1. [Install the agent into the cluster](#install-the-agent-into-the-cluster). +1. [Generate and copy a Secret token used to connect to the agent](#create-the-kubernetes-secret). 1. [Create manifest files](#create-manifest-files). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. -### Set up the Kubernetes Agent Server +### Set up the Agent Server -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Kubernetes Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. To use the KAS: -- If you are a self-managed user, follow the instructions to [install the Kubernetes Agent Server](../../../../administration/clusters/kas.md). +- If you are a self-managed user, follow the instructions to [install the Agent Server](../../../../administration/clusters/kas.md). - If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. ### Define a configuration repository @@ -42,7 +42,7 @@ To use the KAS: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -To configure an Agent, you need: +To create an agent, you need: 1. A GitLab repository to hold the configuration file. 1. Install the Agent in a cluster. @@ -58,27 +58,24 @@ In your repository, add the Agent configuration file under: Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). -Your `config.yaml` file specifies all configurations of the Agent, such as: +WARNING: +The agent is only recognized if you use `.yaml` extension for the `config.yaml` file. The extension `.yml` is **not** recognized. -- The manifest projects to synchronize. -- The groups that can access this Agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). -- The address of the `hubble-relay` for the Network Security policy integrations. +You **don't have to add any content** to this file when you create it. The fact that the file exists +tells GitLab that this is an agent configuration file. It doesn't do anything so far, but, later on, you can use this +file to [configure the agent](../repository.md) by setting up parameters such as: -As an example, a minimal Agent configuration that sets up only the manifest -synchronizations is: +- Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). +- [Manifest projects to synchronize](../repository.md#synchronize-manifest-projects). +- The address of the `hubble-relay` for the [Network Security policy integrations](../../../project/clusters/protect/index.md). -```yaml -gitops: - manifest_projects: - # The `id` is the path to the Git repository holding your manifest files - - id: "path/to/your-manifest-project-1" - paths: - - glob: '/**/*.{yaml,yml,json}' -``` +To see all the settings available, read the [Agent configuration repository documentation](../repository.md). -All the options for the [Kubernetes Agent configuration repository](../repository.md) are documented separately. +### Access your cluster from GitLab CI/CD -### Create an Agent record in GitLab +Use the [CI/CD Tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel) to access your cluster from GitLab CI/CD. + +### Register an agent with GitLab > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI. @@ -91,7 +88,7 @@ In GitLab: 1. Ensure that [GitLab CI/CD is enabled in your project](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). 1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select **Actions**. -1. From the **Select an Agent** dropdown, select the Agent you want to connect and select **Register Agent** to access the installation form. +1. From the **Select an agent** dropdown, select the agent you want to connect and select **Register an agent** to access the installation form. 1. The form reveals your registration token. Securely store this secret token as you cannot view it again. 1. Copy the command under **Recommended installation method**. @@ -100,7 +97,7 @@ In your computer: 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 +### Install the agent into the cluster To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, for example, `gitlab-kubernetes-agent`, run: @@ -113,7 +110,7 @@ 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 (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`. +- `wss://kas.gitlab.example.com` with the configured access of the Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. - `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. ```shell @@ -151,7 +148,7 @@ Kubernetes resources required for the Agent to be installed. You can modify this example [`resources.yml` file](#example-resourcesyml-file) in the following ways: - Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. -- You can configure `kas-address` (Kubernetes Agent Server) in several ways. +- You can configure `kas-address` (Agent Server) in several ways. The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. Select the option appropriate for your cluster configuration and GitLab architecture: - The `wss` scheme (an encrypted WebSockets connection) is specified by default @@ -334,7 +331,7 @@ data: ## Example projects -The following example projects can help you get started with the Kubernetes Agent. +The following example projects can help you get started with the Agent. - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) - This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) @@ -342,18 +339,44 @@ The following example projects can help you get started with the Kubernetes Agen ## View installed Agents Users with at least the [Developer](../../../permissions.md) can access the user interface -for the GitLab Kubernetes Agent at **Infrastructure > Kubernetes clusters**, under the +for the Agent at **Infrastructure > Kubernetes clusters**, under the **Agent** tab. This page lists all registered agents for the current project, and the configuration directory for each agent: - + -Additional management interfaces are planned for the GitLab Kubernetes Agent. +Additional management interfaces are planned for the GitLab Agent. [Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). +## View Agent activity information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6. + +Users with at least the [Developer](../../../permissions.md) can view the Agent's activity events. +The activity logs help you to identify problems and get the information you need for troubleshooting. +You can see events from a week before the current date. +To access an agent's activity: + +1. Go to your agent's configuration repository. +1. From the sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select the **Agent** tab. +1. Select the agent you want to see the activity. + +You can see the following events on the activity list: + +- Agent registration: + - When a new token is **created**. +- Connection events: + - When an agent is successfully **connected** to a cluster. + +Note that the connection status is logged when you connect an agent for the first time +or after more than an hour of inactivity. + + + ## Upgrades and version compatibility -The GitLab Kubernetes Agent is comprised of two major components: `agentk` and `kas`. +The Agent is comprised of two major components: `agentk` and `kas`. As we provide `kas` installers built into the various GitLab installation methods, the required `kas` version corresponds to the GitLab `major.minor` (X.Y) versions. At the same time, `agentk` and `kas` can differ by 1 minor version in either direction. For example, diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 6ceb2766cc9..c8ab037118e 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -4,20 +4,20 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Kubernetes Agent configuration repository **(FREE)** +# Agent configuration repository **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab Agent became available on GitLab.com. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. -> - The `ci_access` attribute was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -> - The GitLab Kubernetes Agent was [moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. WARNING: This feature might not be available to you. Check the **version history** note above for details. -The [GitLab Kubernetes Agent integration](index.md) supports hosting your configuration for -multiple GitLab Kubernetes Agents in a single repository. These agents can be running -in the same cluster or in multiple clusters, and potentially with more than one Agent per cluster. +The [GitLab Agent](index.md) supports hosting your configuration for +multiple agents in a single repository. These agents can be running +in the same cluster or in multiple clusters, and potentially with more than one agent per cluster. The Agent bootstraps with the GitLab installation URL and an authentication token, and you provide the rest of the configuration in your repository, following @@ -128,7 +128,7 @@ operations. If such functionality is needed, you may use multiple agents reading manifests from the same repository. Ensure not to specify "overlapping" globs to avoid synchronizing the same files more than once. -This is detected by the GitLab Kubernetes Agent and leads to an error. +This is detected by the Agent and leads to an error. INCORRECT - both globs match `*.yaml` files in the root directory: @@ -299,7 +299,7 @@ cilium: hubble_relay_address: "hubble-relay.gitlab-managed-apps.svc.cluster.local:80" ``` -## Scan your container images for vulnerabilities +## Scan your container images for vulnerabilities **(ULTIMATE)** You can use [cluster image scanning](../../application_security/cluster_image_scanning/index.md) to scan container images in your cluster for security vulnerabilities. @@ -385,7 +385,7 @@ In this example, the following resources are scanned: ## Debugging -To debug the cluster-side component (`agentk`) of the GitLab Kubernetes Agent, set the log +To debug the cluster-side component (`agentk`) of the Agent, set the log level according to the available options: - `off` diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 3ad994ecd7e..14850ca85b3 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -22,8 +22,7 @@ insights within GitLab: ## Configure cluster cost management -To get started with cluster cost management, you need [Maintainer](../permissions.md) -permissions in a project or group. +To get started with cluster cost management, you need the [Maintainer role](../permissions.md) in a project or group. 1. Clone the [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) example repository, which contains minor modifications to the upstream Kubecost diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 72bc7b398dc..71eb08ee640 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cluster Environments (DEPRECATED) **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 for group-level clusters. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4 for instance-level clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in GitLab 12.3 for group-level clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in GitLab 12.4 for instance-level clusters. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: diff --git a/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png b/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png Binary files differnew file mode 100644 index 00000000000..90b41ee849c --- /dev/null +++ b/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index d04cf64d93a..ee7452537fd 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -32,9 +32,9 @@ to automate this step. Prometheus and Elastic Stack cluster integrations can only be enabled for clusters [connected through cluster certificates](../project/clusters/add_existing_cluster.md). -To enable Prometheus for your cluster connected through the [GitLab Kubernetes Agent](agent/index.md), you can [integrate it manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). +To enable Prometheus for your cluster connected through the [GitLab Agent](agent/index.md), you can [integrate it manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). -There is no option to enable Elastic Stack for your cluster if it is connected with the GitLab Kubernetes Agent. +There is no option to enable Elastic Stack for your cluster if it is connected with the GitLab Agent. Follow this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300230) for updates. ## Prometheus cluster integration @@ -44,7 +44,7 @@ Follow this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300230) for up WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. However, you can **still use** Prometheus for Kubernetes clusters connected to GitLab through the -[GitLab Kubernetes Agent](agent/index.md) by [enabling Prometheus manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). +[Agent](agent/index.md) by [enabling Prometheus manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). You can integrate your Kubernetes cluster with [Prometheus](https://prometheus.io/) for monitoring key metrics of your diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 1332310b850..e28f9275b50 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The cluster management project was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To manage cluster applications, use the [GitLab Kubernetes Agent](agent/index.md) +To manage cluster applications, use the [GitLab Agent](agent/index.md) with the [Cluster Management Project Template](management_project_template.md). A project can be designated as the management project for a cluster. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index c663246cdd8..2d7e89ef765 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. > - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead. -> - [Migrated](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/24) to the GitLab Kubernetes Agent in GitLab 14.5. +> - [Migrated](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/24) to the GitLab Agent in GitLab 14.5. Use a repository to install, manage, and deploy clusters applications through code. @@ -31,10 +31,10 @@ you can manage cluster applications with [Helm v3](https://helm.sh/). - An `applications` directory with a `helmfile.yaml` configured for each application available in the template. -## Use the Kubernetes Agent with the Cluster Management Project Template +## Use the Agent with the Cluster Management Project Template To use a new project created from the Cluster Management Project Template -with a cluster connected to GitLab through the [GitLab Kubernetes Agent](agent/index.md), +with a cluster connected to GitLab through the [GitLab Agent](agent/index.md), you have two options: - [Use one single project](#single-project) to configure the Agent and manage cluster applications. diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index 2da058fb5bc..20c4408d57e 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrate from GitLab Managed Apps to Cluster Management Projects +# Migrate from GitLab Managed Apps to Cluster Management Projects **(FREE)** The [GitLab Managed Apps](applications.md) were deprecated in GitLab 14.0 in favor of [Cluster Management Projects](management_project.md). diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md deleted file mode 100644 index e7f6f908860..00000000000 --- a/doc/user/compliance/compliance_dashboard/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../compliance_report/index.md' -remove_date: '2021-10-23' ---- - -This file was moved to [another location](../compliance_report/index.md). - -<!-- 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/license_compliance/img/policies_maintainer_edit_v14_3.png b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png Binary files differindex 85b2a52e04b..256c66bf7d8 100644 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png +++ b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 319c1ca6278..f89165e7e2d 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -14,6 +14,10 @@ project's dependencies for their licenses. You can then decide whether to allow each license. For example, if your application uses an external (open source) library whose license is incompatible with yours, then you can deny the use of that license. +INFO: +Try License Compliance scanning to search project dependencies in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-compliance-docs). + You can take advantage of License Compliance by either: - [Including the job](#configuration) @@ -22,8 +26,9 @@ You can take advantage of License Compliance by either: [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance), provided by [Auto DevOps](../../../topics/autodevops/index.md). -The [License Finder](https://github.com/pivotal/LicenseFinder) scan tool runs as part of the CI/CD -pipeline, and detects the licenses in use. GitLab checks the License Compliance report, compares the +To detect the licenses in use, License Compliance uses the [License Finder](https://github.com/pivotal/LicenseFinder) scan tool that runs as part of the CI/CD pipeline. +For the job to activate, License Finder needs to find a compatible package definition in the project directory. For details, see the [Activation on License Finder documentation](https://github.com/pivotal/LicenseFinder#activation). +GitLab checks the License Compliance report, compares the licenses between the source and target branches, and shows the information right on the merge request. Denied licenses are indicated by a `x` red icon next to them as well as new licenses that need a decision from you. In addition, you can [manually allow or deny](#policies) licenses in your @@ -47,6 +52,7 @@ When GitLab detects a **Denied** license, you can view it in the [license list](  You can view and modify existing policies from the [policies](#policies) tab. +  ## License expressions @@ -126,7 +132,7 @@ the `license_management` job, so you must migrate to the `license_scanning` job `License-Scanning.gitlab-ci.yml` template. The results are saved as a -[License Compliance report artifact](../../../ci/yaml/index.md#artifactsreportslicense_scanning) +[License Compliance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder) @@ -172,7 +178,7 @@ For that, a `SETUP_CMD` CI/CD variable can be passed to the container, with the required commands to run before the license detection. If present, this variable overrides the setup step necessary to install all the packages -of your application (e.g.: for a project with a `Gemfile`, the setup step could be +of your application (for example: for a project with a `Gemfile`, the setup step could be `bundle install`). For example: @@ -190,8 +196,8 @@ directory of your project. ### Working with Monorepos -Depending on your language, you may need to specify the path to the individual -projects of a monorepo using the `LICENSE_FINDER_CLI_OPTS` variable. Passing in +Depending on your language, you may need to specify the path to the individual +projects of a monorepo using the `LICENSE_FINDER_CLI_OPTS` variable. Passing in the project paths can significantly speed up builds over using the `--recursive` license_finder option. @@ -540,24 +546,24 @@ configured to use this as the default `CA_CERT_PATH`. ### Configuring Go projects To configure [Go modules](https://github.com/golang/go/wiki/Modules) -based projects, specify [CI/CD variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +based projects, specify [CI/CD variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables) in the `license_scanning` job's [variables](#available-cicd-variables) section in `.gitlab-ci.yml`. -If a project has [vendored](https://golang.org/pkg/cmd/go/#hdr-Vendor_Directories) its modules, +If a project has [vendored](https://pkg.go.dev/cmd/go#hdr-Vendor_Directories) its modules, then the combination of the `vendor` directory and `mod.sum` file are used to detect the software licenses associated with the Go module dependencies. #### Using private Go registries -You can use the [`GOPRIVATE`](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) -and [`GOPROXY`](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +You can use the [`GOPRIVATE`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) +and [`GOPROXY`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) environment variables to control where modules are sourced from. Alternatively, you can use -[`go mod vendor`](https://golang.org/ref/mod#tmp_28) to vendor a project's modules. +[`go mod vendor`](https://go.dev/ref/mod#tmp_28) to vendor a project's modules. #### Custom root certificates for Go -You can specify the [`-insecure`](https://golang.org/pkg/cmd/go/internal/get/) flag by exporting the -[`GOFLAGS`](https://golang.org/cmd/go/#hdr-Environment_variables) +You can specify the [`-insecure`](https://pkg.go.dev/cmd/go/internal/get) flag by exporting the +[`GOFLAGS`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) environment variable. For example: ```yaml diff --git a/doc/user/crm/crm_contacts_v14_6.png b/doc/user/crm/crm_contacts_v14_6.png Binary files differnew file mode 100644 index 00000000000..37a615f3926 --- /dev/null +++ b/doc/user/crm/crm_contacts_v14_6.png diff --git a/doc/user/crm/crm_organizations_v14_6.png b/doc/user/crm/crm_organizations_v14_6.png Binary files differnew file mode 100644 index 00000000000..2bde3823cc7 --- /dev/null +++ b/doc/user/crm/crm_organizations_v14_6.png diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md new file mode 100644 index 00000000000..d68ce0a4f7a --- /dev/null +++ b/doc/user/crm/index.md @@ -0,0 +1,141 @@ +--- +stage: Plan +group: Product Planning +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Customer relations management (CRM) **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `customer_relations`. +On GitLab.com, this feature is not available. +You should not use this feature for production environments. + +With customer relations management (CRM) you can create a record of contacts +(individuals) and organizations (companies) and relate them to issues. + +You can use contacts and organizations to tie work to customers for billing and reporting purposes. +To read more about what is planned for the future, see [issue 2256](https://gitlab.com/gitlab-org/gitlab/-/issues/2256). + +## Contacts + +### View contacts linked to a group + +To view a group's contacts: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Contacts**. + + + +### Create a contact + +To create a contact: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Contacts**. +1. Select **New contact**. +1. Complete all required fields. +1. Select **Create new contact**. + +You can also [create](../../api/graphql/reference/index.md#mutationcustomerrelationscontactcreate) +contacts using the GraphQL API. + +### Edit a contact + +To edit an existing contact: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Contacts**. +1. Next to the contact you wish to edit, select **Edit** (**{pencil}**). +1. Edit the required fields. +1. Select **Save changes**. + +You can also [edit](../../api/graphql/reference/index.md#mutationcustomerrelationscontactupdate) +contacts using the GraphQL API. + +## Organizations + +### View organizations + +To view a group's organizations: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Organizations**. + + + +### Create an organization + +To create an organization: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Organizations**. +1. Select **New organization**. +1. Complete all required fields. +1. Select **Create new organization**. + +You can also [create](../../api/graphql/reference/index.md#mutationcustomerrelationsorganizationcreate) +organizations using the GraphQL API. + +### Edit an organization + +You can only [edit](../../api/graphql/reference/index.md#mutationcustomerrelationsorganizationupdate) +organizations using the GraphQL API. + +## Issues + +### View issues linked to a contact + +To view a contact's issues: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Contacts**. +1. Next to the contact whose issues you wish to view, select **View issues** (**{issues}**). + +### View issues linked to an organization + +To view an organization's issues: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Organizations**. +1. Next to the organization whose issues you wish to view, select **View issues** (**{issues}**). + +### View contacts linked to an issue + +You can view contacts associated with an issue in the right sidebar. + +To view a contact's details, hover over the contact's name. + + + +You can also view issue contacts using the +[GraphQL](../../api/graphql/reference/index.md#mutationcustomerrelationsorganizationcreate) +API. + +### Add or remove issue contacts + +Prerequisites: + +- You must have at least the [Developer role](../permissions.md#project-members-permissions) for a group. + +### Add contacts to an issue + +To add contacts to an issue use the `/add_contacts` +[quick action](../project/quick_actions.md). + +You can also add, remove, or replace issue contacts using the +[GraphQL](../../api/graphql/reference/index.md#mutationissuesetcrmcontacts) +API. + +### Remove contacts from an issue + +To remove contacts from an issue use the `/remove_contacts` +[quick action](../project/quick_actions.md). + +You can also add, remove, or replace issue contacts using the +[GraphQL](../../api/graphql/reference/index.md#mutationissuesetcrmcontacts) +API. diff --git a/doc/user/crm/issue_crm_contacts_v14_6.png b/doc/user/crm/issue_crm_contacts_v14_6.png Binary files differnew file mode 100644 index 00000000000..9c18b1a8cdb --- /dev/null +++ b/doc/user/crm/issue_crm_contacts_v14_6.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 4d6cff96169..7831fdff249 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -34,6 +34,20 @@ You can create comments in places like: Each object can have as many as 5,000 comments. +## Mentions + +You can mention a user or a group present in your GitLab instance with `@username` or +`@groupname`. All mentioned users are notified with to-do items and emails. +Users can change this setting for themselves in the +[notification settings](../profile/notifications.md). + +You can quickly see which comments involve you, because +mentions for yourself (the user currently signed in) are highlighted +in a different color. + +Avoid mentioning `@all` in issues and merge requests, because it sends an email notification +to all the members of that project's group. This might be interpreted as spam. + ## Add a comment to a merge request diff You can add comments to a merge request diff. These comments @@ -90,8 +104,10 @@ An icon is displayed on the image and a comment field is displayed. If you have ["reply by email"](../../administration/reply_by_email.md) configured, you can reply to comments by sending an email. -- When you reply to a standard comment, another standard comment is created. +- When you reply to a standard comment, it creates another standard comment. - When you reply to a threaded comment, it creates a reply in the thread. +- When you [send an email to an issue email address](../project/issues/managing_issues.md#copy-issue-email-address), + it creates a standard comment. You can use [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md) in your email replies. @@ -145,7 +161,7 @@ For issues and merge requests with many comments, you can filter the page to sho 1. Open a merge request's **Discussion** tab, or epic or issue's **Overview** tab. 1. On the right side of the page, select from the filter: - - **Show all activity**: Display all user comments and system notes + - **Show all activity**: Display all user comments and system notes. (issue updates, mentions from other issues, changes to the description, and so on). - **Show comments only**: Display only user comments. - **Show history only**: Display only activity notes. @@ -155,6 +171,27 @@ For issues and merge requests with many comments, you can filter the page to sho GitLab saves your preference, so it persists when you visit the same page again from any device you're logged into. +## View description change history **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) in GitLab 12.6. + +You can see changes to the description listed in the history. + +To compare the changes, select **Compare with previous version**. + +## Change activity sort order + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14588) in GitLab 12.10. + +You can reverse the default order and interact with the activity feed sorted by most recent items +at the top. Your preference is saved in local storage and automatically applies to every issue, +merge request, or epic you view. + +To change the activity sort order: + +1. Select the **Oldest first** (or **Newest first**) dropdown list. +1. Select either oldest or newest items to be shown first. + ## Assign an issue to the commenting user > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index a3aecff6f73..8d858a282dd 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -85,7 +85,7 @@ are included when cloning. Top-level groups created after August 12, 2021 have delayed project deletion enabled by default. Projects are permanently deleted after a seven-day delay. -You can disable this by changing the [group setting](../group/index.md#enable-delayed-project-removal). +You can disable this by changing the [group setting](../group/index.md#enable-delayed-project-deletion). ## Alternative SSH port @@ -141,7 +141,24 @@ the related documentation. | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | | [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | Free tier: `50` per-group / `50` per-project <br/> All paid tiers: `1_000` per-group / `1_000` per-project | `1_000` per-group / `1_000` per-project | -| [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables) | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | Unlimited | +| [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables) | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | 150 | + +## Package registry limits + +The [maximum file size](../../administration/instance_limits.md#file-size-limits) +for a package uploaded to the [GitLab Package Registry](../../user/packages/package_registry/index.md) +varies by format: + +| Package type | GitLab.com | +|--------------|------------| +| Conan | 5 GB | +| Generic | 5 GB | +| Helm | 5 MB | +| Maven | 5 GB | +| npm: | 5 GB | +| NuGet | 5 GB | +| PyPI | 5 GB | +| Terraform | 1 GB | ## Account and limit settings @@ -200,11 +217,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 Runner Cloud runners +## Runner SaaS -GitLab has shared runners on GitLab.com that you can use to run your CI jobs. +Runner SaaS is the hosted, secure, and managed build environment you can use to run CI/CD jobs for your GitLab.com hosted project. -For more information, see [GitLab Runner Cloud runners](../../ci/runners/index.md). +For more information, see [Runner SaaS](../../ci/runners/index.md). ## Sidekiq diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 9c95b2b21a4..b2b16321488 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, -use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +use the [GitLab Agent](../../clusters/agent/index.md). Similar to [project-level](../../project/clusters/index.md) and [instance-level](../../instance/clusters/index.md) Kubernetes clusters, diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 9378b3922b5..2214a18475a 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -9,49 +9,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in GitLab 11.6. -[Group owners](../permissions.md#group-members-permissions) can set a subgroup to -be the source of project templates that are selectable when a new project is created -in the group. These templates can be selected when you go to **New project > Create from template** -in the group and select the **Group** tab. +When you create a project, you can [choose from a list of templates](../project/working_with_projects.md#create-a-project). +These templates, for things like GitLab Pages or Ruby, populate the new project with a copy of the files contained in the +template. This information is identical to the information used by [GitLab project import/export](../project/settings/import_export.md) +and can help you start a new project more quickly. -Every project in the subgroup, but not nested subgroups, can be selected by members -of the group when a new project is created. +You can [customize the list](../project/working_with_projects.md#create-a-project) of available templates, so +that all projects in your group have the same list. To do this, you populate a subgroup with the projects you want to +use as templates. -- 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** 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. +You can also configure [custom templates for the instance](../admin_area/custom_project_templates.md). -Repository and database information that is copied over to each new project is identical to the -data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). +## Set up group-level project templates -To set custom project templates at the instance level, see [Custom instance-level project templates](../admin_area/custom_project_templates.md). +Prerequisite: -## Set up group-level project templates +- You must have the [Owner role for the group](../permissions.md#group-members-permissions). To set up custom project templates in a group, add the subgroup that contains the project templates to the group settings: 1. In the group, create a [subgroup](subgroups/index.md). 1. [Add projects to the new subgroup](index.md#add-projects-to-a-group) as your templates. -1. In the left menu for the group, go to **Settings > General**. +1. In the left menu for the group, select **Settings > General**. 1. Expand **Custom project templates** and select the subgroup. -If all enabled [project features](../project/settings/index.md#sharing-and-permissions) -(except for GitLab Pages) are set to **Everyone With Access**, then every project -template in the subgroup is available to every member of the group. +The next time a group member creates a project, they can select any of the projects in the subgroup. -Any projects added to the subgroup later can be selected the next time a group member -creates a new project. +Projects in nested subgroups are not included in the template list. + +## Which projects are available as templates + +- Public and internal projects can be selected by any signed-in user as a template for a new project, + if all [project features](../project/settings/index.md#sharing-and-permissions) + except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. +- Private projects can be selected only by users who are members of the projects. -### Example structure +## Example structure -Here's a sample group/project structure for project templates, for a hypothetical _Acme Co_: +Here's a sample group and project structure for project templates, for `myorganization`: ```plaintext # GitLab instance and group -gitlab.com/acmeco/ +gitlab.com/myorganization/ # Subgroups internal tools @@ -61,7 +61,7 @@ gitlab.com/acmeco/ # Project templates client-site-django client-site-gatsby - client-site-hTML + client-site-html # Other projects client-site-a diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 36ccfc1031f..4151745189d 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -16,94 +16,81 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. > - Adoption over time chart [added](https://gitlab.com/gitlab-org/gitlab/-/issues/337561) in GitLab 14.4. -Prerequisites: +DevOps Adoption shows you how groups in your organization adopt and use the most essential features of GitLab. -- You must have at least the [Reporter role](../../permissions.md) for the group. +You can use Group DevOps Adoption to: -To access Group DevOps Adoption, go to your group and select **Analytics > DevOps Adoption**. +- Identify specific subgroups that are lagging in their adoption of GitLab features, so you can guide them on +their DevOps journey. +- Find subgroups that have adopted certain features, and provide guidance to other subgroups on +how to use those features. +- Verify if you are getting the return on investment that you expected from GitLab. -Group DevOps Adoption shows you how individual groups and subgroups within your organization use the following features: + -- Dev - - Approvals - - Code owners - - Issues - - Merge requests -- Sec - - DAST - - Dependency Scanning - - Fuzz Testing - - SAST -- Ops - - Deployments - - Pipelines - - Runners +## View DevOps Adoption -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. +Prerequisite: -With DevOps Adoption you can: +- You must have at least the [Reporter role](../../permissions.md) for the group. -- Verify whether you are getting the return on investment that you expected from GitLab. -- 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. +To view DevOps Adoption: - +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > DevOps adoption** + +## DevOps Adoption categories + +DevOps Adoption shows feature adoption for development, security, and operations. + +| Category | Feature | +| --- | --- | +| Development | Approvals<br>Code owners<br>Issues<br>Merge requests | +| Security | DAST<br>Dependency Scanning<br>Fuzz Testing<br>SAST | +| Operations | Deployments<br>Pipelines<br>Runners | + +## Feature adoption -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. +DevOps Adoption shows feature adoption data for groups and subgroups for the previous calendar month. -## Enable data processing +A feature shows as **adopted** when a group has used the feature in a project during the time period. +This includes projects in any subgroups of the group. For example, if an issue was created in a project in a group, the group has adopted issues in that time. -Group DevOps Adoption relies on data that has been gathered by a weekly data processing task. -This task is disabled by default. +### Exceptions to feature adoption data -To begin using Group DevOps Adoption, access the feature for the first time. GitLab automatically -enables the data processing for that group. The group data doesn't appear immediately, because -GitLab requires around a minute to process it. +When GitLab measures DevOps Adoption, some common DevOps information is not included: -## What is displayed +- Dormant projects. It doesn't matter how many projects in the group use a feature. Even if you have many dormant projects, it doesn't lower the adoption. +- New GitLab features. Adoption is the total number of features adopted, not the percent of features. -DevOps Adoption displays feature adoption data for the given group -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 subgroups of the given group). +## When DevOps Adoption data is gathered -## Adoption over time +A weekly task processes data for DevOps Adoption. This task is disabled until you access +DevOps Adoption for a group for the first time. -The **Adoption over time** chart in the **Overview** tab displays DevOps Adoption over time. The chart displays the total number of adopted features from the previous twelve months, -from when you enabled DevOps Adoption for the group. +The data processing task updates the data on the first day of each month. If the monthly update +fails, the task tries daily until it succeeds. -The tooltip displays information about the features tracked for individual months. +DevOps Adoption data may take up to a minute to appear while GitLab processes the group's data. -## When is a feature considered adopted +## View feature adoption over time -A feature is considered "adopted" if it has been used anywhere in the group in the specified time. -For example, if an issue was created in one project in a group, the group is considered to have -"adopted" issues in that time. +The **Adoption over time** chart shows the total number of adopted features from the previous +twelve months. The chart only shows data from when you enabled DevOps Adoption for the group. -## No penalties for common adoption patterns +To view feature adoption over time: -DevOps Adoption is designed not to penalize for any circumstances or practices that are common in DevOps. -Following this guideline, GitLab doesn't penalize for: +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > DevOps adoption**. +1. Select the **Overview** tab. -1. Having dormant projects. It's common for groups to have a mix of active and dormant projects, - so we should not consider adoption to be low if there are relatively many dormant projects. - This means we should not measure adoption by how many projects in the group have used a feature, - only by whether a feature was used anywhere in the group. -1. GitLab adding new features over time. It's common for group feature usage to be consistent - 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. +Tooltips display information about the features tracked for individual months. -## Add a subgroup +## Add or remove a subgroup -DevOps Adoption can also display data for subgroups within the given group, -to show you differences in adoption across the group. -To add subgroups to your Group DevOps Adoption report: +To add or remove a subgroup from the DevOps Adoption report: 1. Select **Add or remove subgroups**. -1. Select the subgroups you want to add and select **Save changes**. +1. Select the subgroup you want to add or remove and select **Save changes**. -The subgroup data might not appear immediately, because GitLab requires around a minute to collect -the data. +It may take up to a minute for subgroup data to appear while GitLab collects the data. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index d184030718a..1bc1e4d703b 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -9,6 +9,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. +INFO: +Try epic boards and more with a +[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-boards-docs). + Epic boards build on the existing [epic tracking functionality](index.md) and [labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned labels. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 65e0f31324b..3889398e2f8 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Plan group: Product Planning info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -7,8 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Epics **(PREMIUM)** -> - Introduced in GitLab 10.2. -> - Single-level epics were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. +> Single-level epics were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. + +INFO: +Check out [multi-level child epics](manage_epics.md#multi-level-child-epics) with a +[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-docs). When [issues](../../project/issues/index.md) share a theme across projects and milestones, you can manage them by using epics. @@ -37,9 +39,9 @@ graph TD Child_epic --> Issue2 ``` -## Roadmap in epics **(ULTIMATE)** +Also, read more about possible [planning hierarchies](../planning_hierarchy/index.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in GitLab 11.10. +## Roadmap in epics **(ULTIMATE)** If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that have a start or due date, a visual diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 72fa9e1e310..f5b1a2a6ee6 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -332,7 +332,7 @@ Only issues from projects that are in groups can be promoted. When you attempt t issue, a warning is displayed. Promoting a confidential issue to an epic makes all information related to the issue public as epics are public to group members. -When the quick action is executed: +When an issue is promoted to an epic: - An epic is created in the same group as the project of the issue. - Subscribers of the issue are notified that the epic was created. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index f0e08301a1b..db6ed02f405 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -321,7 +321,7 @@ To share a group after enabling this feature: 1. Go to your group's page. 1. On the left sidebar, go to **Group information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. -1. (Optional) Select an **Access expiration date**. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. ## Manage group memberships via LDAP **(PREMIUM SELF)** @@ -508,7 +508,7 @@ To prevent a project from being shared with other groups: This setting applies to all subgroups unless overridden by a group owner. Groups already added to a project lose access when the setting is enabled. -## Prevent members from being added to a group **(PREMIUM)** +## Prevent members from being added to projects in a group **(PREMIUM)** As a group owner, you can prevent any new project membership for all projects in a group, allowing tighter control over project membership. @@ -516,7 +516,11 @@ projects in a group, allowing tighter control over project membership. For example, if you want to lock the group for an [Audit Event](../../administration/audit_events.md), you can guarantee that project membership cannot be modified during the audit. -To prevent members from being added to a group: +You can still invite groups or to add members to groups, implicitly giving members access to projects in the **locked** group. + +The setting does not cascade. Projects in subgroups observe the subgroup configuration, ignoring the parent group. + +To prevent members from being added to projects in a group: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. @@ -557,12 +561,15 @@ You should consider these security implications before configuring IP address re - **Administrators and group owners**: Users with these permission levels can always access the group settings, regardless of IP restriction, but they cannot access projects belonging to the group when accessing from a disallowed IP address. -- **GitLab API and runner activities**: Only the [Groups](../../api/groups.md) - and [Projects](../../api/projects.md) APIs are protected by IP address restrictions. +- **GitLab API and runner activities**: Only the [group](../../api/groups.md) (including all + [group resources](../../api/api_resources.md#group-resources)) APIs and [project](../../api/api_resources.md#project-resources) + (including all [project resources](../../api/api_resources.md#project-resources)) APIs are protected by IP address restrictions. When you register a runner, it is not bound by the IP restrictions. When the runner requests a new job or an update to a job's state, it is also not bound by the IP restrictions. But when the running CI/CD job sends Git requests from a restricted IP address, the IP restriction prevents code from being cloned. +- **User dashboard activity**: Users may still see some events from the IP restricted groups and projects + on their dashboard. Activity may include push, merge, issue, or comment events. To restrict group access by IP address: @@ -660,18 +667,15 @@ To disable group mentions: 1. Select **Disable group mentions**. 1. Select **Save changes**. -## Enable delayed project removal **(PREMIUM)** +## Enable delayed project deletion **(PREMIUM)** > - [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. -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. The default interval period is seven days but - [is configurable](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +[Delayed project deletion](../project/settings/index.md#delayed-project-deletion) can be enabled for groups. When enabled, projects in +the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. The default +period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). On self-managed GitLab, projects are deleted immediately by default. In GitLab 14.2 and later, an administrator can @@ -685,12 +689,12 @@ To enable delayed deletion of projects in a group: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. -1. Check **Enable delayed project removal**. +1. Check **Enable delayed project deletion**. 1. Optional. To prevent subgroups from changing this setting, select **Enforce for all subgroups**. 1. Select **Save changes**. NOTE: -In GitLab 13.11 and above the group setting for delayed project removal is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. +In GitLab 13.11 and above the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. ## Prevent project forking outside group **(PREMIUM)** @@ -799,13 +803,5 @@ the following checks when creating or updating namespaces or groups: - Namespaces must not have parents. - Group parents must be groups and not namespaces. -You can disable the validation if GitLab shows the following errors: - -- `A user namespace cannot have a parent`. -- `A group cannot have a user namespace as its parent`. - -To disable the validation, -[disable the `validate_namespace_parent_type` flag](../../administration/feature_flags.md). - -In the unlikely event that you had to disable this feature flag to prevent errors, +In the unlikely event that you see these errors in your GitLab installation, [contact Support](https://about.gitlab.com/support/) so that we can improve this validation. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 7a1cbe86d58..8a79effba15 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -7,14 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Iterations **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in GitLab 13.1. -> - Deployed behind a feature flag, disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 13.2. -> - Enabled on GitLab.com. -> - Can be enabled or disabled per-group. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-iterations). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in GitLab 13.1 [with a flag](../../../administration/feature_flags.md) named `group_iterations`. Disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 13.2. > - Moved to GitLab Premium in 13.9. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 14.6. [Feature flag `group_iterations`](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) removed. Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) @@ -169,31 +165,7 @@ To group issues by label: 1. Select the **Filter by label** dropdown. 1. Select the labels you want to group by in the labels dropdown. You can also search for labels by typing in the search input. -1. Select or tap outside of the label dropdown. The page is now grouped by the selected labels. - -## Enable or disable iterations **(PREMIUM SELF)** - -GitLab Iterations feature is deployed with a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance. `:group_iterations` can be enabled or disabled per-group. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:group_iterations) -# or by group -Feature.enable(:group_iterations, Group.find(<group ID>)) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:group_iterations) -# or by group -Feature.disable(:group_iterations, Group.find(<group ID>)) -``` +1. Select any area outside the label dropdown list. The page is now grouped by the selected labels. ### Enable or disable iteration cadences **(PREMIUM SELF)** diff --git a/doc/user/group/planning_hierarchy/img/epic-view-ancestors-in-sidebar_v14_6.png b/doc/user/group/planning_hierarchy/img/epic-view-ancestors-in-sidebar_v14_6.png Binary files differnew file mode 100644 index 00000000000..373b861239b --- /dev/null +++ b/doc/user/group/planning_hierarchy/img/epic-view-ancestors-in-sidebar_v14_6.png diff --git a/doc/user/group/planning_hierarchy/img/hierarchy_with_multi_level_epics.png b/doc/user/group/planning_hierarchy/img/hierarchy_with_multi_level_epics.png Binary files differnew file mode 100644 index 00000000000..d264ebf10d7 --- /dev/null +++ b/doc/user/group/planning_hierarchy/img/hierarchy_with_multi_level_epics.png diff --git a/doc/user/group/planning_hierarchy/img/issue-view-parent-epic-in-sidebar_v14_6.png b/doc/user/group/planning_hierarchy/img/issue-view-parent-epic-in-sidebar_v14_6.png Binary files differnew file mode 100644 index 00000000000..95a5777674a --- /dev/null +++ b/doc/user/group/planning_hierarchy/img/issue-view-parent-epic-in-sidebar_v14_6.png diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md new file mode 100644 index 00000000000..5887328abe4 --- /dev/null +++ b/doc/user/group/planning_hierarchy/index.md @@ -0,0 +1,67 @@ +--- +type: reference +stage: Plan +group: Product Planning +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Planning hierarchies **(PREMIUM)** + +Planning hierarchies are an integral part of breaking down your work in GitLab. +To understand how you can use epics and issues together in hierarchies, remember the following: + +- [Epics](../epics/index.md) exist in groups. +- [Issues](../../project/issues/index.md) exist in projects. + +GitLab is not opinionated on how you structure your work and the hierarchy you can build with multi-level +epics. For example, you can use the hierarchy as a folder of issues for bigger initiatives. + +To learn about hierarchies in general, common frameworks, and using GitLab for +portfolio management, see +[How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/). + +## Hierarchies with epics + +With epics, you can achieve the following hierarchy: + +```mermaid +graph TD + Group_epic --> Project1_Issue1 + Group_epic --> Project1_Issue2 + Group_epic --> Project2_Issue1 +``` + +### Hierarchies with multi-level epics **(ULTIMATE)** + +With the addition of [multi-level epics](../epics/manage_epics.md#multi-level-child-epics) and up to +seven levels of nested epics, you can achieve the following hierarchy: + +<!-- +Image below was generated with the following Mermaid code. +Attached as an image because a rendered diagram doesn't look clear on the docs page. + +```mermaid +classDiagram + direction TD + class Epic + class Issue + + Epic *-- "0..7" Epic +Epic "1"*-- "0..*" Issue +``` + + --> + + + +## View ancestry of an epic + +In an epic, you can view the ancestors as parents in the right sidebar under **Ancestors**. + + + +## View ancestry of an issue + +In an issue, you can view the parented epic above the issue in the right sidebar under **Epic**. + + diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 206f3172170..7d489bc5b2d 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -19,7 +19,7 @@ Epics and milestones in a group containing a start date or due date can be visua of a timeline (that is, a Gantt chart). The Roadmap page shows the epics and milestones in a group, one of its subgroups, or a project in one of the groups. -On the epic bars, you can see the each epic's title, progress, and completed weight percentage. +On the epic bars, you can see each epic's title, progress, and completed weight percentage. When you hover over an epic bar, a popover appears with the epic's title, start date, due date, and weight completed. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 402007b85b2..7443be250bb 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -14,6 +14,10 @@ This page describes SAML for groups. For instance-wide SAML on self-managed GitL SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. +INFO: +Use your own SAML authentication to log in to [GitLab.com](http://gitlab.com/). +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-saml-sso-docs). + User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group automatically. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. @@ -29,14 +33,16 @@ If required, you can find [a glossary of common terms](../../../integration/saml Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [specific identity provider documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. -1. Configure [required assertions](#assertions) at minimum containing - the user's email address. +1. Configure the required [user attributes](#user-attributes), ensuring you include the user's email address. 1. While the default is enabled for most SAML providers, please ensure the app is set to have service provider initiated calls in order to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab).  +If your account is the only owner in the group after SAML is set up, you can't unlink the account. To [unlink the account](#unlinking-accounts), +set up another user as a group owner. + ### NameID GitLab.com uses the SAML NameID to identify users. The NameID element: @@ -60,15 +66,16 @@ Once users have signed into GitLab using the SSO SAML setup, changing the `NameI We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format. Most NameID formats can be used, except `Transient` due to the temporary nature of this format. -### Assertions +### User attributes + +To create users with the correct information for improved [user access and management](#user-access-and-management), +the user's details must be passed to GitLab as attributes in the SAML assertion. At a minimum, the user's email address +must be specified as an attribute named `email` or `mail`. -For users to be created with the right information with the improved [user access and management](#user-access-and-management), -the user details need to be passed to GitLab as SAML assertions. +GitLab.com supports the following attributes: -At a minimum, the user's email address *must* be specified as an assertion named `email` or `mail`. -See [the assertions list](../../../integration/saml.md#assertions) for other available claims. -In addition to the attributes in the linked assertions list, GitLab.com supports `username` -and `nickname` attributes. +- `username` or `nickname`. We recommend you configure only one of these. +- The [attributes also available](../../../integration/saml.md#assertions) to self-managed GitLab instances. ### Metadata configuration @@ -104,7 +111,7 @@ The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-co > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. -With this option enabled, users (except owners) must go through your group's GitLab single sign-on URL if they wish to access group resources through the UI. Users can't be manually added as members. +With this option enabled, users (except users with the Owner role) must access GitLab using your group GitLab single sign-on URL to access group resources. Users added manually as members can't access group resources. SSO enforcement does not affect sign in or access to any resources outside of the group. Users can view which groups and projects they are a member of without SSO sign in. @@ -119,7 +126,7 @@ SSO has the following effects when enabled: - For groups, users can't share a project in the group outside the top-level group, even if the project is forked. - For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or - pull from a GitLab repository. + pull from a GitLab repository. - Credentials that are not tied to regular users (for example, access tokens and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> @@ -342,6 +349,11 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o </saml:AttributeStatement> ``` +Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` +are not accepted as a source of groups. +See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) +for examples on configuring the required attribute name in the SAML identity provider's settings. + NOTE: The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools). @@ -362,7 +374,7 @@ To link the SAML groups from the `saml:AttributeStatement` example above: If a user is a member of multiple SAML groups mapped to the same GitLab group, the user gets the highest access level from the groups. For example, if one group is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` -access. +access. Users granted: @@ -374,7 +386,10 @@ Users granted: ### Automatic member removal After a group sync, users who are not members of a mapped SAML group are removed from -the GitLab group. +the GitLab group. Even if SSO authentication is successful, if an existing user is not a member of any of the configured groups: + +- They get an "unauthorized" message if they try to view the group. +- All of their permissions to subgroups and projects are also removed. For example, in the following diagram: @@ -475,6 +490,24 @@ Specific attention should be paid to: - The presence of a `X509Certificate`, which we require to verify the response signature. - The `SubjectConfirmation` and `Conditions`, which can cause errors if misconfigured. +#### Generate a SAML Response + +SAML Responses can be used to preview the attribute names and values sent in the assertions list while attempting to sign in using an IdP. + +To generate a SAML Response: + +1. Install either: + - [SAML Chrome Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace) for Chrome. + - [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. +1. Open a new browser tab. +1. Open the SAML tracer console: + - Chrome: Right click on the page, select **Inspect**, then click on the SAML tab in the opened developer console. + - Firefox: Select the SAML-tracer icon located on the browser toolbar. +1. Go to the GitLab single sign-on URL for the group in the same browser tab with the SAML tracer open. +1. Select **Authorize** or attempt to log in. A SAML response is displayed in the tracer console that resembles this + [example SAML response](#example-saml-response). +1. Within the SAML tracer, select the **Export** icon to save the response in JSON format. + ### Verifying configuration For convenience, we've included some [example resources](../../../administration/troubleshooting/group_saml_scim.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index dd4558b4a3e..2651bcb9e12 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -115,12 +115,7 @@ configuration. Otherwise, the Okta SCIM app may not work properly. 1. Sign in to Okta. 1. Ensure you are in the Admin section by selecting the **Admin** button located in the top right. The admin button is not visible from the admin page. - - NOTE: - If you're using the Developer Console, select **Developer Console** in the top - bar and then select **Classic UI**. Otherwise, you may not see the buttons described in the following steps: - -1. In the **Application** tab, select **Add Application**. +1. In the **Application** tab, select **Browse App Catalog**. 1. Search for **GitLab**, find and select on the 'GitLab' application. 1. On the GitLab application overview page, select **Add**. 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. @@ -170,14 +165,11 @@ During provisioning: - Duplicate usernames are also handled, by adding suffix `1` upon user creation. For example, due to already existing `test_user` username, `test_user1` is used. -As long as [Group SAML](index.md) has been configured, existing GitLab.com users can link to their accounts in one of the following ways: - -- By updating their *primary* email address in their GitLab.com user account to match their identity provider's user profile email address. -- By following these steps: +If [Group SAML](index.md) has been configured and you have an existing GitLab.com account, you can link your SCIM and SAML identities: - 1. Sign in to GitLab.com if needed. - 1. In the identity provider's dashboard select the GitLab app or visit the **GitLab single sign-on URL**. - 1. Select the **Authorize**. +1. Update the [primary email](../../profile/index.md#change-your-primary-email) address in your GitLab.com user account to match the + user profile email address in your identity provider. +1. [Link your SAML identity](index.md#linking-saml-to-your-existing-gitlabcom-account). We recommend users do this prior to turning on sync, because while synchronization is active, there may be provisioning errors for existing users. @@ -303,3 +295,12 @@ As a workaround, try an alternate mapping: 1. Follow the Azure mapping instructions from above. 1. Delete the `name.formatted` target attribute entry. 1. Change the `displayName` source attribute to have `name.formatted` target attribute. + +#### Failed to match an entry in the source and target systems Group 'Group-Name' + +Group provisioning in Azure can fail with the `Failed to match an entry in the source and target systems Group 'Group-Name'` error message, +and the error response can include a HTML result of the GitLab URL `https://gitlab.com/users/sign_in`. + +This error is harmless and occurs because Group provisioning was turned on but GitLab SCIM integration does not support it nor require it. To +remove the error, follow the instructions in the Azure configuration guide to disable the option +[`Synchronize Azure Active Directory Groups to AppName`](#azure-configuration-steps). diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 3692a2636ab..5745c499c5c 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -9,19 +9,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. -Existing groups running on any GitLab instance or GitLab.com can be exported with all their related data and moved to a -new GitLab instance. +You can export groups, with all their related data, from one GitLab instance to another. +You can also [export projects](../../project/settings/import_export.md). -The **GitLab import/export** button is displayed if the group import option in enabled. +## Enable export for a group -See also: +Prerequisite: -- [Group Import/Export API](../../../api/group_import_export.md) -- [Project Import/Export](../../project/settings/import_export.md) -- [Project Import/Export API](../../../api/project_import_export.md) +- You must have the [Owner role](../../permissions.md) for the group. -Users with the [Owner role](../../permissions.md) for a group can enable -import and export for that group: +To enable import and export for a group: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. @@ -70,8 +67,11 @@ WARNING: This feature will be [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6 and replaced by [GitLab Migration](../import/). -Users with the [Owner role](../../permissions.md) for a group can export the -contents of that group: +Prerequisites: + +- You must have the [Owner role](../../permissions.md) for the group. + +To export the contents of a group: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. @@ -88,6 +88,8 @@ NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. +You can also use the [group import/export API](../../../api/group_import_export.md). + ### Between CE and EE You can export groups from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. @@ -96,6 +98,10 @@ The Enterprise Edition retains some group data that isn't part of the Community ## Importing the group +WARNING: +This feature will be [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) +in GitLab 14.8 and replaced by [GitLab Migration](../import/). + 1. Create a new group: - On the top bar, select **New** (**{plus}**) and then **New group**. - On an existing group's page, select the **New subgroup** button. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index a0a13c71d95..b91e258b04a 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -86,8 +86,8 @@ the date filter behavior to filter the end event time of the currently selected The change makes it possible to get a much better picture about the completed items within the stage and helps uncover long-running items. -For example, an issue was created a year ago and the current stage was finished in the current month. -If you were to look at the metrics for the last three months, this issue would not be included in the calculation of +For example, an issue was created a year ago and the current stage was finished in the current month. +If you were to look at the metrics for the last three months, this issue would not be included in the calculation of the stage metrics. With the new date filter, this item would be included. DISCLAIMER: @@ -100,7 +100,7 @@ sole discretion of GitLab Inc. ## How metrics are measured -> DORA API-based deployment metrics for group-level Value Stream Analytics were +> DORA API-based deployment metrics for group-level Value Stream Analytics were > [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. The "Time" metrics near the top of the page are measured as follows: diff --git a/doc/user/img/award_emoji_comment_awarded.png b/doc/user/img/award_emoji_comment_awarded.png Binary files differdeleted file mode 100644 index 111793ebf8a..00000000000 --- a/doc/user/img/award_emoji_comment_awarded.png +++ /dev/null diff --git a/doc/user/img/award_emoji_comment_picker.png b/doc/user/img/award_emoji_comment_picker.png Binary files differdeleted file mode 100644 index 07f90c898ed..00000000000 --- a/doc/user/img/award_emoji_comment_picker.png +++ /dev/null diff --git a/doc/user/img/award_emoji_select.png b/doc/user/img/award_emoji_select.png Binary files differdeleted file mode 100644 index 269282b94b0..00000000000 --- a/doc/user/img/award_emoji_select.png +++ /dev/null diff --git a/doc/user/img/award_emoji_select_v14_6.png b/doc/user/img/award_emoji_select_v14_6.png Binary files differnew file mode 100644 index 00000000000..c8185a1b4cb --- /dev/null +++ b/doc/user/img/award_emoji_select_v14_6.png diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 21387998a17..9e57622875d 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [certificate-based Kubernetes integration with GitLab](../index.md) was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) -in GitLab 14.5. To connect your clusters, use the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). +in GitLab 14.5. To connect your clusters, use the [GitLab Agent](../../../clusters/agent/index.md). <!-- TBA: (We need to resolve https://gitlab.com/gitlab-org/gitlab/-/issues/343660 before adding this line) If you don't have a cluster yet, create one and connect it to GitLab through the Agent. diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index d5840641aab..47063dcae96 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -9,10 +9,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. An inventory object is a `ConfigMap` object for keeping track of the set of objects applied to a cluster. -When you remove objects from a manifest repository, GitLab Kubernetes Agent uses a corresponding inventory object to +When you remove objects from a manifest repository, the Agent uses a corresponding inventory object to prune (delete) objects from the cluster. -The GitLab Kubernetes Agent creates an inventory object for each manifest project specified in the +The Agent creates an inventory object for each manifest project specified in the `gitops.manifest_projects` configuration section. The inventory object has to be stored somewhere in the cluster. The default behavior is: @@ -20,10 +20,10 @@ The default behavior is: explicitly, the inventory object is stored in the `default` namespace. - The `name` is generated from the numeric project ID of the manifest project and the numeric agent ID. - This way the GitLab Kubernetes Agent constructs the name and local where the inventory object is + This way the Agent constructs the name and local where the inventory object is stored in the cluster. -The GitLab Kubernetes Agent cannot locate the existing inventory object if you: +The Agent cannot locate the existing inventory object if you: - Change `gitops.manifest_projects[].default_namespace` parameter. - Move manifests into another project. @@ -57,13 +57,13 @@ metadata: ## Using GitOps with pre-existing Kubernetes objects -The GitLab Kubernetes Agent treats manifest files in the manifest repository as the source of truth. When it applies +The Agent treats manifest files in the manifest repository as the source of truth. When it applies objects from the files to the cluster, it tracks them in an inventory object. If an object already exists, -GitLab Kubernetes Agent behaves differently based on the `gitops.manifest_projects[].inventory_policy` configuration. +The Agent behaves differently based on the `gitops.manifest_projects[].inventory_policy` configuration. Check the table below with the available options and when to use them. `inventory_policy` value | Description | ------------------------ | ------------------------------------------------------------------------------------------- | `must_match` | This is the default policy. A live object must have the `config.k8s.io/owning-inventory` annotation set to the same value as the `cli-utils.sigs.k8s.io/inventory-id` label on the corresponding inventory object to be updated. Object is not updated and an error is reported if the values don't match or the object doesn't have the annotation. | `adopt_if_no_inventory` | This mode allows to "adopt" an object if it doesn't have the `config.k8s.io/owning-inventory` annotation. Use this mode if you want to start managing existing objects using the GitOps feature. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. | -`adopt_all` | This mode allows to "adopt" an object even if it has the `config.k8s.io/owning-inventory` annotation set to a different value. This mode can be useful if you want to migrate a set of objects from one agent to another one or from some other tool to the GitLab Kubernetes Agent. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. | +`adopt_all` | This mode allows to "adopt" an object even if it has the `config.k8s.io/owning-inventory` annotation set to a different value. This mode can be useful if you want to migrate a set of objects from one agent to another one or from some other tool to the Agent. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. | diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index 06a77912876..144a8cd2d31 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes clusters **(FREE)** -To connect clusters to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +To connect clusters to GitLab, use the [GitLab Agent](../../clusters/agent/index.md). ## Certificate-based Kubernetes integration (DEPRECATED) @@ -24,7 +24,7 @@ It had the following issues: - Users were constantly reporting issues with features based on this model. For this reason, we started to build features based on a new model, the -[GitLab Kubernetes Agent](../../clusters/agent/index.md). +[GitLab Agent](../../clusters/agent/index.md). Maintaining both methods in parallel caused a lot of confusion and significantly increased the complexity to use, develop, maintain, and document them. For this reason, we decided to deprecate them to focus on the @@ -38,7 +38,7 @@ Follow this [epic](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) for updates. You can find technical information about why we moved away from cluster certificates into -the Kubernetes Agent model on the [Agent's blueprint documentation](../../../architecture/blueprints/gitlab_to_kubernetes_communication/index.md). +the GitLab Agent model on the [Agent's blueprint documentation](../../../architecture/blueprints/gitlab_to_kubernetes_communication/index.md). ## Deprecated features @@ -52,13 +52,12 @@ the Kubernetes Agent model on the [Agent's blueprint documentation](../../../arc - [Cluster integrations](../../clusters/integrations.md) - [Cluster cost management](../../clusters/cost_management.md) - [Cluster environments](../../clusters/environments.md) -- [Canary Deployments](../../project/canary_deployments.md) +- [Advanced traffic control with Canary Ingress](../../project/canary_deployments.md#advanced-traffic-control-with-canary-ingress-deprecated) - [Serverless](../../project/clusters/serverless/index.md) - [Deploy Boards](../../project/deploy_boards.md) - [Pod logs](../../project/clusters/kubernetes_pod_logs.md) - [Clusters health](manage/clusters_health.md) - [Crossplane integration](../../clusters/crossplane.md) -- [Auto Deploy](../../../topics/autodevops/stages.md#auto-deploy) - [Web terminals](../../../administration/integration/terminal.md) ### Cluster levels diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 89df9c1d18f..15a680e2193 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -96,10 +96,17 @@ 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 +## Create a new cluster through IaC (DEPRECATED) Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). +NOTE: +The linked tutorial connects the cluster to GitLab through cluster certificates, +and this method was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) +in GitLab 14.5. You can still create a cluster through IaC and then connect it to GitLab +through the [Agent](../../clusters/agent/index.md), the default and fully supported +method to connect clusters to GitLab. + ## Troubleshooting ### `gitlab_group_share_group` resources not detected when subgroup state is refreshed diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index e92b2d919ae..ab59f8ad64b 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -10,7 +10,7 @@ Collaborating around Infrastructure as Code (IaC) changes requires both code cha ## Output Terraform Plan information into a merge request -Using the [GitLab Terraform Report artifact](../../../ci/yaml/index.md#artifactsreportsterraform), +Using the [GitLab Terraform Report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsterraform), you can expose details from `terraform plan` runs directly into a merge request widget, enabling you to see statistics about the resources that Terraform creates, modifies, or destroys. @@ -62,7 +62,7 @@ To manually configure a GitLab Terraform Report artifact: 1. Define a `script` that runs `terraform plan` and `terraform show`. These commands pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. This JSON is used to create a - [GitLab Terraform Report artifact](../../../ci/yaml/index.md#artifactsreportsterraform). + [GitLab Terraform Report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsterraform). The Terraform report obtains a Terraform `tfplan.json` file. The collected Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 84d1edbe2f7..a45ef02622f 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -17,7 +17,7 @@ to securely store the state files in local storage (the default) or 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. +You are highly advised to use a remote storage resource in that case. The GitLab managed Terraform state backend can store your Terraform state easily and securely, and spares you from setting up additional remote resources like @@ -28,7 +28,7 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -A GitLab **administrator** must [setup the Terraform state storage configuration](../../../administration/terraform_state.md) +A GitLab **administrator** must [set up the Terraform state storage configuration](../../../administration/terraform_state.md) before using this feature. ## Permissions for using Terraform @@ -89,7 +89,7 @@ local machine, this is a simple way to get started: ``` If you already have a GitLab-managed Terraform state, you can use the `terraform init` command -with the prepopulated parameters values: +with the pre-populated parameters values: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Terraform**. @@ -300,7 +300,7 @@ any changes that are required for your infrastructure. All Terraform commands should now work. If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other +re-run this command to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary. ``` diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 3bb518596cc..d8e75928675 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -30,11 +30,11 @@ Learn more about how GitLab can help you run [Infrastructure as Code](iac/index. ## Integrated Kubernetes management The GitLab integration with Kubernetes helps you to install, configure, manage, deploy, and troubleshoot -cluster applications. With the GitLab Kubernetes Agent, you can connect clusters behind a firewall, +cluster applications. With the GitLab Agent, you can connect clusters behind a firewall, have real-time access to API endpoints, perform pull-based or push-based deployments for production and non-production environments, and much more. -Learn more about the [GitLab Kubernetes Agent](../clusters/agent/index.md). +Learn more about the [GitLab Agent](../clusters/agent/index.md). ## Runbooks in GitLab diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md deleted file mode 100644 index 81e8f7cbd33..00000000000 --- a/doc/user/infrastructure/mr_integration.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'iac/mr_integration.md' -remove_date: '2021-11-26' ---- - -This document was moved to [another location](iac/mr_integration.md). - -<!-- This redirect file can be deleted after <2021-11-26>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md deleted file mode 100644 index e71291d502e..00000000000 --- a/doc/user/infrastructure/terraform_state.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'iac/terraform_state.md' -remove_date: '2021-11-26' ---- - -This document was moved to [another location](iac/terraform_state.md). - -<!-- This redirect file can be deleted after <2021-11-26>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 4bbd82d01a8..a184f00f6f6 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, -use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +use the [GitLab Agent](../../clusters/agent/index.md). Similar to [project-level](../../project/clusters/index.md) and [group-level](../../group/clusters/index.md) Kubernetes clusters, diff --git a/doc/user/markdown.md b/doc/user/markdown.md index d20e9c7a30e..1b3cd5d4478 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -11,7 +11,7 @@ GitLab automatically renders Markdown content. For example, when you add a comme you type the text in the Markdown language. When you save the issue, the text is rendered with a set of styles. These styles are described on this page. -For example, in Markdown, an ordered list looks like this: +For example, in Markdown, an unordered list looks like this: ```markdown - Cat @@ -249,7 +249,7 @@ the content. This data can be used by static site generators like [Jekyll](https When you view a Markdown file rendered by GitLab, front matter is displayed as-is, in a box at the top of the document. The HTML content displays after the front matter. To view an example, you can toggle between the source and rendered version of a -[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md). +[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/index.md). In GitLab, front matter is used only in Markdown files and wiki pages, not the other places where Markdown formatting is supported. It must be at the very top of the document @@ -516,30 +516,30 @@ version to reference other projects from the same namespace. GitLab Flavored Markdown recognizes the following: -| references | input | cross-project reference | shortcut inside same namespace | -| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | -| specific user | `@user_name` | | | -| specific group | `@group_name` | | | -| entire team | `@all` | | | -| project | `namespace/project>` | | | -| issue | ``#123`` | `namespace/project#123` | `project#123` | -| merge request | `!123` | `namespace/project!123` | `project!123` | -| snippet | `$123` | `namespace/project$123` | `project$123` | -| epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | -| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | -| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | -| label by ID | `~123` | `namespace/project~123` | `project~123` | -| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | -| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | -| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | -| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | -| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | -| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | -| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | -| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README.md)` | | | -| repository file line references | `[README](doc/README.md#L13)` | | | -| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | +| references | input | cross-project reference | shortcut inside same namespace | +| :--------------------------------------------------- | :---------------------------- | :----------------------------------------- | :------------------------------- | +| specific user | `@user_name` | | | +| specific group | `@group_name` | | | +| entire team | `@all` | | | +| project | `namespace/project>` | | | +| issue | ``#123`` | `namespace/project#123` | `project#123` | +| merge request | `!123` | `namespace/project!123` | `project!123` | +| snippet | `$123` | `namespace/project$123` | `project$123` | +| [epic](group/epics/index.md) | `&123` | `group1/subgroup&123` | | +| vulnerability **(ULTIMATE)** <sup>1</sup> | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | +| label by ID | `~123` | `namespace/project~123` | `project~123` | +| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | +| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | +| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| repository file references | `[README](doc/README.md)` | | | +| repository file line references | `[README](doc/README.md#L13)` | | | +| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | 1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. @@ -554,6 +554,16 @@ In addition to this, links to some objects are also recognized and formatted. So - The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. - Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. +### Show the issue, merge request, or epic title in the reference + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15694) in GitLab 14.6. + +To include the title in the rendered link of an issue, merge request, or epic, add a plus (`+`) +at the end of the reference. For example, a reference like `#123+` is rendered as +`The issue title (#123)`. + +URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+` are also expanded. + ### Embedding metrics in GitLab Flavored Markdown Metric charts can be embedded in GitLab Flavored Markdown. Read @@ -988,6 +998,8 @@ Here's a sample audio clip: ### Inline HTML +> Allowing `rel="license"` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20857) in GitLab 14.6. + To see the second example of Markdown rendered in HTML, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-html). @@ -996,6 +1008,7 @@ You can also use raw HTML in your Markdown, and it usually works pretty well. See the documentation for HTML::Pipeline's [SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` allowlist, GitLab allows `span`, `abbr`, `details` and `summary` elements. +`rel="license"` is allowed on links to support the [Rel-License microformat](https://microformats.org/wiki/rel-license) and license attribution. ```html <dl> diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 29ca3a48e70..47c41e85345 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Operations Dashboard **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in GitLab 11.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) from GitLab Ultimate to GitLab Premium in 11.10. The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 7861258e23f..23bd140d4b7 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -9,6 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab 13.2. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. > - Support for Composer 2.0 [added](https://gitlab.com/gitlab-org/gitlab/-/issues/259840) in GitLab 13.10. +> - Deploy token support [added](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) in GitLab 14.6. WARNING: The Composer package registry for GitLab is under development and isn't ready for production use due to @@ -88,13 +89,12 @@ Prerequisites: - A valid `composer.json` file. - The Packages feature is enabled in a GitLab repository. - The project ID, which is on the project's home page. -- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. +- One of the following token types: + - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. + - A [deploy token](../../project/deploy_tokens/index.md) + with the scope set to `write_package_registry`. - NOTE: - [Deploy tokens](../../project/deploy_tokens/index.md) are - [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. - -To publish the package: +To publish the package with a personal access token: - Send a `POST` request to the [Packages API](../../../api/packages.md). @@ -109,6 +109,21 @@ To publish the package: - `<tag>` is the Git tag name of the version you want to publish. To publish a branch, use `branch=<branch>` instead of `tag=<tag>`. +To publish the package with a deploy token: + +- Send a `POST` request to the [Packages API](../../../api/packages.md). + + For example, you can use `curl`: + + ```shell + curl --data tag=<tag> --header "Deploy-Token: <deploy-token>" "https://gitlab.example.com/api/v4/projects/<project_id>/packages/composer" + ``` + + - `<deploy-token>` is your deploy token + - `<project_id>` is your project ID. + - `<tag>` is the Git tag name of the version you want to publish. + To publish a branch, use `branch=<branch>` instead of `tag=<tag>`. + You can view the published package by going to **Packages & Registries > Package Registry** and selecting the **Composer** tab. @@ -159,11 +174,11 @@ Prerequisites: - A package in the Package Registry. - The group ID, which is on the group's home page. -- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to, at minimum, `read_api`. - - NOTE: - [Deploy tokens](../../project/deploy_tokens/index.md) are - [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. +- One of the following token types: + - A [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to, at minimum, `api`. + - A [deploy token](../../project/deploy_tokens/index.md) + with the scope set to `read_package_registry`, `write_package_registry`, or both. To install a package: @@ -213,6 +228,8 @@ To install a package: 1. Create an `auth.json` file with your GitLab credentials: + Using a personal access token: + ```shell composer config gitlab-token.<DOMAIN-NAME> <personal_access_token> ``` @@ -229,6 +246,26 @@ To install a package: } ``` + Using a deploy token: + + ```shell + composer config gitlab-token.<DOMAIN-NAME> <deploy_token_username> <deploy_token> + ``` + + Result in the `auth.json` file: + + ```json + { + ... + "gitlab-token": { + "<DOMAIN-NAME>": { + "username": "<deploy_token_username>", + "token": "<deploy_token>", + ... + } + } + ``` + You can unset this with the command: ```shell @@ -236,7 +273,8 @@ To install a package: ``` - `<DOMAIN-NAME>` is the GitLab instance URL `gitlab.com` or `gitlab.example.com`. - - `<personal_access_token>` with the scope set to `read_api`. + - `<personal_access_token>` with the scope set to `api`, or `<deploy_token>` with the scope set + to `read_package_registry` and/or `write_package_registry`. 1. If you are on a GitLab self-managed instance, add `gitlab-domains` to `composer.json`. @@ -298,10 +336,19 @@ To install a package: WARNING: Never commit the `auth.json` file to your repository. To install packages from a CI/CD job, -consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your personal access token +consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your access token stored in a [GitLab CI/CD variable](../../../ci/variables/index.md) or in [HashiCorp Vault](../../../ci/secrets/index.md). +### Working with Deploy Tokens + +Although Composer packages are accessed at the group level, a group or project deploy token can be +used to access them: + +- A group deploy token has access to all packages published to projects in that group or its + subgroups. +- A project deploy token only has access to packages published to that particular project. + ## Supported CLI commands The GitLab Composer repository supports the following Composer CLI commands: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 0f32f68d250..731ba04a9f7 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -103,6 +103,29 @@ A package with the recipe `Hello/0.1@mycompany/beta` is created. For more details about creating and managing Conan packages, see the [Conan documentation](https://docs.conan.io/en/latest/creating_packages.html). +#### Package without a username and a channel + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345055) in GitLab 14.6. + +Even though they are [recommended](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#user-channel) +to distinguish your package from a similarly named existing package, +the username and channel are not mandatory fields for a Conan package. + +You can create a package without a username and channel by removing them from +the `create` command: + +```shell +conan create . +``` + +The username _and_ the channel must be blank. If only one of these fields is +blank, the request is rejected. + +NOTE: +Empty usernames and channels can only be used if you use a [project remote](#add-a-remote-for-your-project). +If you use an [instance remote](#add-a-remote-for-your-instance), the username +and the channel must be set. + ## Add the Package Registry as a Conan remote To run `conan` commands, you must add the Package Registry as a Conan remote for diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index c9cdc8643f4..9497dd1625b 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -370,10 +370,17 @@ WARNING: Deleting images is a destructive action and can't be undone. To restore a deleted image, you must rebuild and re-upload it. -NOTE: -Administrators should review how to -[garbage collect](../../../administration/packages/container_registry.md#container-registry-garbage-collection) -the deleted images. +On self-managed instances, deleting an image doesn't free up storage space - it only marks the image +as eligible for deletion. To actually delete images and recover storage space, in case they're +unreferenced, administrators must run [garbage collection](../../../administration/packages/container_registry.md#container-registry-garbage-collection). + +On GitLab.com, the latest version of the Container Registry includes an automatic online garbage +collector. For more information, see [this blog post](https://about.gitlab.com/blog/2021/10/25/gitlab-com-container-registry-update/). +This is an instance-wide feature, rolling out gradually to a subset of the user base, so some new image repositories created +from GitLab 14.5 onwards are served by this new version of the Container Registry. In this new +version of the Container Registry, layers that aren't referenced by any image manifest, and image +manifests that have no tags and aren't referenced by another manifest (such as multi-architecture +images), are automatically scheduled for deletion after 24 hours if left unreferenced. ### Delete images from within GitLab diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index fbd1cb84580..8b34634318c 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -89,6 +89,10 @@ You can authenticate using: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. - A [group deploy token](../../../user/project/deploy_tokens/index.md#group-deploy-token) with the scope set to `read_registry` and `write_registry`. +Users accessing the Dependency Proxy with a personal access token or username and password require +at least [Guest membership](../../permissions.md#group-members-permissions) +to the group they pull images from. + #### SAML SSO When [SSO enforcement](../../group/saml_sso/index.md#sso-enforcement) @@ -200,7 +204,7 @@ on the GitLab server. The next time you pull the same image, GitLab gets the lat information about the image from Docker Hub, but serves the existing blobs from the GitLab server. -## Clear the Dependency Proxy cache +## Reduce storage usage Blobs are kept forever on the GitLab server, and there is no hard limit on how much data can be stored. @@ -215,6 +219,16 @@ If you clear the cache, the next time a pipeline runs it must pull an image or t ### Cleanup policies +#### Enable cleanup policies from within GitLab + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340777) in GitLab 14.6 + +You can enable an automatic time-to-live (TTL) policy for the Dependency Proxy from the user +interface. To do this, navigate to your group's **Settings > Packages & Registries > Dependency Proxy** +and enable the setting to automatically clear items from the cache after 90 days. + +#### Enable cleanup policies with GraphQL + > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab 14.4. The cleanup policy is a scheduled job you can use to clear cached images that are no longer used, @@ -245,8 +259,7 @@ mutation { ``` See the [Getting started with GraphQL](../../../api/graphql/getting_started.md) -guide to learn how to make GraphQL queries. Support for enabling and configuring cleanup policies in -the UI is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340777). +guide to learn how to make GraphQL queries. When the policy is initially enabled, the default TTL setting is 90 days. Once enabled, stale dependency proxy files are queued for deletion each day. Deletion may not occur right away due to diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 1cf3132489a..29455fdbb35 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -144,8 +144,8 @@ If you're unfamiliar with managing dependencies in Go, or Go in general, review the following documentation: - [Dependency Management in Go](../../../development/go_guide/dependencies.md) -- [Go Modules Reference](https://golang.org/ref/mod) -- [Documentation (`golang.org`)](https://golang.org/doc/) +- [Go Modules Reference](https://go.dev/ref/mod) +- [Documentation (`golang.org`)](https://go.dev/doc/) - [Learn (`go.dev/learn`)](https://go.dev/learn/) ### Set environment variables diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index c88fba83dc7..488345965f9 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -36,15 +36,11 @@ To authenticate to the Helm repository, you need either: ## Publish a package -WARNING: -The `helm-push` command is broken in Helm 3.7. For more information, see the [open issue](https://github.com/chartmuseum/helm-push/issues/109) -in the Chart Museum project. - 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 desired channel with `curl` or `helm-push`: +Once built, a chart can be uploaded to the desired channel with `curl` or `helm cm-push`: - With `curl`: @@ -61,11 +57,11 @@ Once built, a chart can be uploaded to the desired channel with `curl` or `helm- [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`). - `<channel>`: the name of the channel (like `stable`). -- With the [`helm-push`](https://github.com/chartmuseum/helm-push/#readme) plugin: +- With the [`helm cm-push`](https://github.com/chartmuseum/helm-push/#readme) plugin: ```shell helm repo add --username <username> --password <access_token> project-1 https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel> - helm push mychart-0.1.0.tgz project-1 + helm cm-push mychart-0.1.0.tgz project-1 ``` - `<username>`: the GitLab username or the deploy token username. @@ -135,12 +131,6 @@ To fix the error, use the correct version syntax and upload the chart again. ### `helm push` results in an error -The `helm push` plugin is not yet supported in Helm 3.7. If you try to push a chart using -`helm push`, it produces the following error: - -```plaintext -Error: this feature has been marked as experimental and is not enabled by default. Please set HELM_EXPERIMENTAL_OCI=1 in your environment to use this feature -``` - -To continue to use the plugin, you can push an image using [curl](#use-cicd-to-publish-a-helm-package) -or downgrade your version of Helm. +Helm 3.7 introduced a breaking change for the `helm-push` plugin. You can update the +[Chart Museum plugin](https://github.com/chartmuseum/helm-push/#readme) +to use `helm cm-push`. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 03209da7ac8..1086de1fa92 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -17,6 +17,10 @@ Only [scoped](https://docs.npmjs.com/misc/scope/) packages are supported. For documentation of the specific API endpoints that the npm package manager client uses, see the [npm API documentation](../../../api/packages/npm.md). +WARNING: +Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can +be committed to a repository. + ## Build an npm package This section covers how to install npm or Yarn and build a package for your @@ -430,14 +434,16 @@ You can route package requests to organizations and users outside of GitLab. To do this, add lines to your `.npmrc` file. Replace `my-org` with the namespace or group that owns your project's repository, and use your organization's URL. The name is case-sensitive and must match the name of your group or namespace exactly. +Use environment variables to set up your tokens: `export MY_TOKEN="<your token>"`. + ```shell @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken=${MY_TOKEN} +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=${MY_TOKEN} @my-other-org:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken=${MY_TOKEN} +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=${MY_TOKEN} ``` ### npm metadata diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 98cccd72425..37b6404d487 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -107,6 +107,7 @@ You can now add a new source to NuGet with: - [NuGet CLI](#add-a-source-with-the-nuget-cli) - [Visual Studio](#add-a-source-with-visual-studio) - [.NET CLI](#add-a-source-with-the-net-cli) +- [Configuration file](#add-a-source-with-a-configuration-file) ### Add a source with the NuGet CLI @@ -215,6 +216,51 @@ If you get a warning, ensure that the **Location**, **Username**, and A project-level endpoint is required to publish NuGet packages to the Package Registry. A project-level endpoint is also required to install NuGet packages from a project. +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) +NuGet endpoint, add the Package Registry as a source with `nuget`: + +```shell +dotnet nuget add source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token> +``` + +- `<source_name>` is the desired source name. +- `--store-password-in-clear-text` might be necessary depending on your operating system. + +For example: + +```shell +dotnet nuget add source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" --name gitlab --username carol --password 12345678asdf +``` + +#### Group-level endpoint + +To install a NuGet package from a group, use a group-level endpoint. + +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) +NuGet endpoint, add the Package Registry as a source with `nuget`: + +```shell +dotnet nuget add source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token> +``` + +- `<source_name>` is the desired source name. +- `--store-password-in-clear-text` might be necessary depending on your operating system. + +For example: + +```shell +dotnet nuget add source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" --name gitlab --username carol --password 12345678asdf +``` + +### Add a source with a configuration file + +#### Project-level endpoint + +A project-level endpoint is required to: + +- Publish NuGet packages to the Package Registry. +- Install NuGet packages from a project. + To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. @@ -229,13 +275,20 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package </packageSources> <packageSourceCredentials> <gitlab> - <add key="Username" value="<gitlab_username or deploy_token_username>" /> - <add key="ClearTextPassword" value="<gitlab_personal_access_token or deploy_token>" /> + <add key="Username" value="%GITLAB_PACKAGE_REGISTRY_USERNAME%" /> + <add key="ClearTextPassword" value="%GITLAB_PACKAGE_REGISTRY_PASSWORD%" /> </gitlab> </packageSourceCredentials> </configuration> ``` +1. Configure the necessary environment variables: + + ```shell + export GITLAB_PACKAGE_REGISTRY_USERNAME=<gitlab_username or deploy_token_username> + export GITLAB_PACKAGE_REGISTRY_PASSWORD=<gitlab_personal_access_token or deploy_token> + ``` + #### Group-level endpoint To install a package from a group, use a group-level endpoint. @@ -254,13 +307,20 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Re </packageSources> <packageSourceCredentials> <gitlab> - <add key="Username" value="<gitlab_username or deploy_token_username>" /> - <add key="ClearTextPassword" value="<gitlab_personal_access_token or deploy_token>" /> + <add key="Username" value="%GITLAB_PACKAGE_REGISTRY_USERNAME%" /> + <add key="ClearTextPassword" value="%GITLAB_PACKAGE_REGISTRY_PASSWORD%" /> </gitlab> </packageSourceCredentials> </configuration> ``` +1. Configure the necessary environment variables: + + ```shell + export GITLAB_PACKAGE_REGISTRY_USERNAME=<gitlab_username or deploy_token_username> + export GITLAB_PACKAGE_REGISTRY_PASSWORD=<gitlab_personal_access_token or deploy_token> + ``` + ## Publish a NuGet package Prerequisite: diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 3204ac07d6a..28e1571b4f8 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -147,7 +147,7 @@ The Package Registry supports the following formats: | [Go](../go_proxy/index.md) | 13.1+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3043) | | [Ruby gems](../rubygems_registry/index.md) | 13.10+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3200) | -[Status](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga): +[Status](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga): - Alpha: behind a feature flag and not officially supported. - Beta: several known issues that may prevent expected use. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 7f101adccad..b8dc071fc30 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -29,15 +29,15 @@ 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. ```plaintext -PUT /projects/:id/packages/terraform/modules/:module_name/:module_system/:module_version/file +PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file ``` | 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 (`-`) 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/). +| `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. @@ -97,7 +97,7 @@ You can then reference your Terraform Module from a downstream Terraform project ```plaintext module "<module>" { - source = "gitlab.com/<namespace>/<module_name>/<module_system>" + source = "gitlab.com/<namespace>/<module-name>/<module-system>" } ``` diff --git a/doc/user/permissions.md b/doc/user/permissions.md index eb79d5099eb..4336c58b56c 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -103,6 +103,7 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Close / reopen | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | @@ -119,7 +120,7 @@ The following table lists project permissions available for each role: | [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>Create (*18*) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | @@ -233,6 +234,7 @@ The following table lists project permissions available for each role: 1. Guest users can only set metadata (for example, labels, assignees, or milestones) when creating an issue. They cannot change the metadata on existing issues. 1. In GitLab 14.5 or later, Guests are not allowed to [create incidents](../operations/incident_management/incidents.md#incident-creation). +1. In projects that accept contributions from external members, users can create, edit, and close their own merge requests. ## Project features permissions diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index c555f5ca8cc..96415279de4 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.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 --- -# Deleting a User account +# Deleting a User account **(FREE)** Users can be deleted from a GitLab instance, either by: @@ -24,7 +24,7 @@ As a user, to delete your own account: 1. On the left sidebar, select **Account**. 1. Select **Delete account**. -## As an administrator +## As an administrator **(FREE SELF)** As an administrator, to delete a user account: @@ -42,11 +42,12 @@ Using the **Delete user and contributions** option may result in removing more data than intended. Please see [associated records](#associated-records) below for additional details. -## Associated Records +### Associated records -> - Introduced for issues in [GitLab 9.0](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7393). -> - Introduced for merge requests, award emoji, notes, and abuse reports in [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10467). -> - Hard deletion from abuse reports and spam logs was introduced in [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10273), and from the API in [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11853). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7393) for issues in GitLab 9.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10467) for merge requests, award emoji, notes, and abuse reports in GitLab 9.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10273) hard deletion from abuse reports and spam logs in GitLab 9.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11853) hard deletion from the API in GitLab 9.3. There are two options for deleting users: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index e4e7e7b9c1a..343f8e328ba 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -20,8 +20,7 @@ password secret. NOTE: When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)! -In addition to time-based one time passwords (TOTP), GitLab supports U2F -(universal 2nd factor) and WebAuthn (experimental) devices as the second factor +In addition to time-based one time passwords (TOTP), GitLab supports WebAuthn devices as the second factor of authentication. After being enabled, in addition to supplying your username and password to sign in, you're prompted to activate your U2F / WebAuthn device (usually by pressing a button on it) which performs secure authentication on @@ -80,11 +79,11 @@ in a safe place. ### One-time password via FortiAuthenticator -> - Introduced in [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5. > - It's deployed behind a feature flag, disabled by default. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-fortiauthenticator-integration). -You can use FortiAuthenticator as an OTP provider in GitLab. Users must exist in +You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must exist in both FortiAuthenticator and GitLab with the exact same username, and users must have FortiToken configured in FortiAuthenticator. @@ -154,7 +153,7 @@ Feature.enable(:forti_authenticator, User.find(<user ID>)) ### One-time password via FortiToken Cloud -> - Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/212313). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7. > - It's deployed behind a feature flag, disabled by default. > - It's disabled on GitLab.com. > - It's not recommended for production use. @@ -163,7 +162,7 @@ Feature.enable(:forti_authenticator, User.find(<user ID>)) WARNING: This feature might not be available to you. Check the **version history** note above for details. -You can use FortiToken Cloud as an OTP provider in GitLab. Users must exist in +You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must exist in both FortiToken Cloud and GitLab with the exact same username, and users must have FortiToken configured in FortiToken Cloud. @@ -269,11 +268,11 @@ Click on **Register U2F Device** to complete the process. ### WebAuthn device -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-webauthn). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `webauthn`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6. + +FLAG: +On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. On GitLab.com, this feature is available. The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the following desktop browsers: @@ -350,7 +349,7 @@ request, and you're automatically signed in. ### Sign in by using a WebAuthn device In supported browsers you should be automatically prompted to activate your WebAuthn device -(e.g. by touching/pressing its button) after entering your credentials. +(for example, by touching or pressing its button) after entering your credentials. A message displays, indicating that your device responded to the authentication request and you're automatically signed in. @@ -465,13 +464,20 @@ If you regenerate 2FA recovery codes, save them. You can't use any previously cr ### Have 2FA disabled on your account -If you cannot use a saved recovery code or generate new recovery codes then please submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) requesting that a GitLab global administrator disables two-factor authentication for your account. Please note that only the actual owner of the account can make this request and that disabling this setting will temporarily leave your account in a less secure state. You should therefore sign in and re-enable two-factor authentication as soon as possible. +If you can't use a saved recovery code or generate new recovery codes, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to +request a GitLab global administrator disable two-factor authentication for your account. Note that: + +- Only the owner of the account can make this request. +- This service is only available for accounts that have a GitLab.com subscription. For more information, see our + [blog post](https://about.gitlab.com/blog/2020/08/04/gitlab-support-no-longer-processing-mfa-resets-for-free-users/). +- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor authentication + as soon as possible. ## Note to GitLab administrators - You need to take special care to that 2FA keeps working after [restoring a GitLab backup](../../../raketasks/backup_restore.md). -- To ensure 2FA authorizes correctly with TOTP server, you may want to ensure +- To ensure 2FA authorizes correctly with time-based one time passwords (TOTP) server, you may want to ensure your GitLab server's time is synchronized via a service like NTP. Otherwise, you may have cases where authorization always fails because of time differences. - The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from @@ -488,25 +494,6 @@ If you cannot use a saved recovery code or generate new recovery codes then plea - To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). -## Enable or disable WebAuthn **(FREE SELF)** - -Support for WebAuthn is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:webauthn) -``` - -To disable it: - -```ruby -Feature.disable(:webauthn) -``` - ## Troubleshooting If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself. diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 1797307a00c..b30ee002758 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -5,14 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Active sessions +# Active sessions **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17867) in GitLab 10.8. GitLab lists all devices that have logged into your account. You can review the sessions, and revoke any you don't recognize. -## Listing all active sessions +## List all active sessions To list all active sessions: @@ -29,7 +29,7 @@ To list all active sessions: GitLab allows users to have up to 100 active sessions at once. If the number of active sessions exceeds 100, the oldest ones are deleted. -## Revoking a session +## Revoke a session To revoke an active session: @@ -40,7 +40,7 @@ To revoke an active session: NOTE: When any session is revoked all **Remember me** tokens for all -devices are revoked. See ['Why do I keep getting signed out?'](index.md#why-do-i-keep-getting-signed-out) +devices are revoked. See [Why do I keep getting signed out?](index.md#why-do-i-keep-getting-signed-out) for more information about the **Remember me** feature. <!-- ## Troubleshooting diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d9f10b58c3f..90cb6502bbd 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -100,17 +100,20 @@ When visiting the public page of a user, you can only see the projects which you 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. -## User profile README +## Add details to your profile with a README > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232157) in GitLab 14.5. -You can add a README section to your profile that can include more information and [formatting](../markdown.md) than -your profile's bio. +If you want to add more information to your profile page, you can create a README file. When you populate the README file with information, it's included on your profile page. To add a README to your profile: -1. Create a new public project with the same name as your GitLab username. +1. Create a new public project with the same project path as your GitLab username. 1. Create a README file inside this project. The file can be any valid [README or index file](../project/repository/index.md#readme-and-index-files). +1. Populate the README file with [Markdown](../markdown.md). + +To use an existing project, [update the path](../project/settings/index.md#renaming-a-repository) of the project to match +your username. ## Add external accounts to your user profile page @@ -257,6 +260,29 @@ To change your commit email: 1. In the **Commit email** dropdown list, select an email address. 1. Select **Update profile settings**. +## Change your primary email + +Your primary email: + +- Is the default email address for your login, commit email, and notification email. +- Must be already [linked to your user profile](#add-emails-to-your-user-profile). + +To change your primary email: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the **Email** field, enter your new email address. +1. Select **Update profile settings**. + +## Set your public email + +You can select one of your [configured email addresses](#add-emails-to-your-user-profile) to be displayed on your public profile: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the **Public email** field, select one of the available email addresses. +1. Select **Update profile settings**. + ### Use an automatically-generated private commit email GitLab provides an automatically-generated private commit email address, diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 9faa4b78f8c..acbaf62579f 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -67,7 +67,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. | | Participate | Receive notifications for threads you have participated in. | -| On mention | Receive notifications when you are [mentioned](../project/issues/issue_data_and_actions.md#mentions) in a comment. | +| On mention | Receive notifications when you are [mentioned](../discussions/index.md#mentions) in a comment. | | Disabled | Receive no notifications. | | Custom | Receive notifications for selected events. | @@ -203,7 +203,7 @@ In issues, merge requests, and epics, for most events, the notification is sent - Participants: - The author and assignee. - Authors of comments. - - Anyone [mentioned](../project/issues/issue_data_and_actions.md#mentions) by username in the title + - Anyone [mentioned](../discussions/index.md#mentions) by username in the title or description. - Anyone mentioned by username in a comment if their notification level is "Participating" or higher. - Watchers: users with notification level "Watch". @@ -287,7 +287,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](../project/issues/issue_data_and_actions.md#mentions) in a comment on the design. +- Anyone that is [mentioned](../discussions/index.md#mentions) in a comment on the design. ## Opt out of all GitLab emails @@ -316,19 +316,19 @@ a merge request or an issue. The following table lists all GitLab-specific email headers: -| Header | Description | -|------------------------------------|-------------------------------------------------------------------------| -| `List-Id` | The path of the project in an RFC 2919 mailing list identifier. You can use it for email organization with filters. | -| `X-GitLab-(Resource)-ID` | The ID of the resource the notification is for. The resource, for example, can be `Issue`, `MergeRequest`, `Commit`, or another such resource. | -| `X-GitLab-Discussion-ID` | The ID of the thread the comment belongs to, in notification emails for comments. | -| `X-GitLab-Group-Id` **(PREMIUM)** | The group's ID. Only present on notification emails for epics. | -| `X-GitLab-Group-Path` **(PREMIUM)** | The group's path. Only present on notification emails for epics. | -| [`X-GitLab-NotificationReason`](#x-gitlab-notificationreason) | The reason for the notification. This can be `mentioned`, `assigned`, or `own_activity`. | -| `X-GitLab-Pipeline-Id` | The ID of the pipeline the notification is for, in notification emails for pipelines. | -| `X-GitLab-Project-Id` | The project's ID. | -| `X-GitLab-Project-Path` | The project's path. | -| `X-GitLab-Project` | The name of the project the notification belongs to. | -| `X-GitLab-Reply-Key` | A unique token to support reply by email. | +| Header | Description | +|---------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| `List-Id` | The path of the project in an RFC 2919 mailing list identifier. You can use it for email organization with filters. | +| `X-GitLab-(Resource)-ID` | The ID of the resource the notification is for. The resource, for example, can be `Issue`, `MergeRequest`, `Commit`, or another such resource. | +| `X-GitLab-Discussion-ID` | The ID of the thread the comment belongs to, in notification emails for comments. | +| `X-GitLab-Group-Id` | The group's ID. Only present on notification emails for [epics](../group/epics/index.md). | +| `X-GitLab-Group-Path` | The group's path. Only present on notification emails for [epics](../group/epics/index.md) | +| [`X-GitLab-NotificationReason`](#x-gitlab-notificationreason) | The reason for the notification. This can be `mentioned`, `assigned`, or `own_activity`. | +| `X-GitLab-Pipeline-Id` | The ID of the pipeline the notification is for, in notification emails for pipelines. | +| `X-GitLab-Project-Id` | The project's ID. | +| `X-GitLab-Project-Path` | The project's path. | +| `X-GitLab-Project` | The name of the project the notification belongs to. | +| `X-GitLab-Reply-Key` | A unique token to support reply by email. | ### X-GitLab-NotificationReason diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 197ba4647b2..ea66f3e508f 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -7,10 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Personal access tokens **(FREE)** -> - 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). +> - Notifications for expiring tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. +> - Token lifetime limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. +> - Additional notifications for expiring tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214721) in GitLab 13.3. +> - Prefill for token name and scopes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334664) in GitLab 14.1. Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to: diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index e079e6dcbee..63be88f90d6 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Profile preferences +# Profile preferences **(FREE)** A user's profile preferences page allows the user to customize various aspects of GitLab to their liking. @@ -120,7 +120,7 @@ You can include the following options for your default dashboard view: - Your [To-Do List](../todos.md) - Assigned Issues - Assigned Merge Requests -- Operations Dashboard **(PREMIUM)** +- [Operations Dashboard](../operations_dashboard/index.md) ### Group overview content @@ -130,7 +130,7 @@ displayed on a group's home page. You can choose between 2 options: - Details (default) -- [Security dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)** +- [Security dashboard](../application_security/security_dashboard/index.md) ### Project overview content diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index 7aa1ae89c9f..be86db3daf5 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -1,11 +1,10 @@ --- -type: concepts, howto 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 --- -# Email notification for unknown sign-ins +# Email notification for unknown sign-ins **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27211) in GitLab 13.0. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index e03e5b10236..a5473629d4f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -This feature was deprecated in GitLab 14.5. Use [Infrastrucure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) to create new clusters. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic @@ -19,11 +19,11 @@ Kubernetes Service (EKS). ## Connect an existing EKS cluster If you already have an EKS cluster and want to connect it to GitLab, -use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +use the [GitLab Agent](../../clusters/agent/index.md). ## Create a new EKS cluster -To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). ### How to create a new cluster on EKS through cluster certificates (DEPRECATED) diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index fcf2583d3ab..acc5ed4cb30 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) instead. If you have an existing Kubernetes cluster, you can add it to a project, group, diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 30be319f2df..99edddeb3e9 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -Use [Infrastrucure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md) +Use [Infrastructure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md) to create a cluster hosted on Google Kubernetes Engine (GKE). Through GitLab, you can create new and connect existing clusters @@ -19,7 +19,7 @@ hosted on Google Kubernetes Engine (GKE). ## Connect an existing GKE cluster If you already have a GKE cluster and want to connect it to GitLab, -use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +use the [GitLab Agent](../../clusters/agent/index.md). ## Create a new GKE cluster from GitLab diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 49708e3b6aa..a0fca517f2e 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -29,7 +29,7 @@ in a few clicks. > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) to **safely create new clusters from GitLab**. Creating clusters from GitLab using cluster certificates is still available on the @@ -49,7 +49,7 @@ supports connecting existing clusters using the certificate-based connection met ## Add existing cluster -As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) to connect your cluster to GitLab. Alternatively, you can [add an existing cluster](add_existing_cluster.md) @@ -57,7 +57,7 @@ through the certificate-based method, but we don't recommend using this method f ## Configure your cluster -As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) to configure your cluster. ## Disable a cluster diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 510aad821cf..4e00ae0dd07 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) instead. When creating a cluster in GitLab, you are asked if you would like to create either: diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index c3a71ec8585..e89ce12b35e 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md). To deploy with the Agent, use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md). A Kubernetes cluster can be the destination for a deployment job. If diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index ad378be2d9a..686b3026b2c 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../../user/clusters/agent/index.md). +To connect your cluster to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). To manage applications, use the [Cluster Project Management Template](../../../user/clusters/management_project_template.md). You can choose to allow GitLab to manage your cluster for you. If your cluster diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index c16c6446acd..dc37060593c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, use the -[GitLab Kubernetes Agent](../../clusters/agent/index.md). +[GitLab Agent](../../clusters/agent/index.md). [Project-level](../../infrastructure/clusters/connect/index.md#cluster-levels-deprecated) Kubernetes clusters allow you to connect a Kubernetes cluster to a project in GitLab. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 540907bf915..12527853b40 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Using multiple Kubernetes clusters for a single project **with cluster certificates** was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect clusters to GitLab, use the [GitLab Kubernetes Agent](../../../user/clusters/agent/index.md). +To connect clusters to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index c005ce64bb5..98ba4a1f84d 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). You can continue using Container Host Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Host Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +method. The work to allow all aspects of Container Host Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350). Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index eb15675da19..06dc6b24620 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). You can continue using Container Network Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Network Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +method. The work to allow all aspects of Container Network Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350) and [this GitLab Epic](https://gitlab.com/groups/gitlab-org/-/epics/7057). Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 283e6c0b81c..340c9397e9c 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -192,11 +192,10 @@ violations but don't block any traffic. To set Cilium to Blocking mode, you must lines to the `applications/cilium/values.yaml` file in your cluster management project: ```yaml -config: - policyAuditMode: false +policyEnforcementMode: "always" monitor: - eventTypes: ["drop"] + eventTypes: ["drop", "policy-verdict"] ``` ### Traffic is not being allowed as expected diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 06fa18d80c9..ccf90a3d3dd 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -290,7 +290,7 @@ The example code is available: - As a [clonable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). - In a version with [tests and secret variables](https://gitlab.com/gitlab-org/project-templates/serverless-framework/). -You can also use a [template](../../working_with_projects.md#project-templates) +You can also use a [template](../../working_with_projects.md#create-a-project) (based on the version with tests and secret variables) from within the GitLab UI (see the `Serverless Framework/JS` template). diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index f6598f8846b..265a60c6f2c 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -539,7 +539,7 @@ server that has Python 3 installed, and may not work on other operating systems or with other versions of Python. 1. Install Certbot by running the - [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto). + [`certbot-auto` wrapper script](https://eff-certbot.readthedocs.io/install.html#certbot-auto). On the command line of your server, run the following commands: ```shell diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index c138dc64d19..a95e4d2bc26 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -11,6 +11,10 @@ type: reference > - Code Owners for merge request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. > - Moved to GitLab Premium in 13.9. +INFO: +Get access to Code Owners and more with a +[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-code-owners-docs). + Code Owners define who owns specific files or directories in a repository. - The users you define as Code Owners are displayed in the UI when you browse directories. @@ -173,12 +177,16 @@ entries under **Database**. The entries defined under the sections **Documentati ### Make a Code Owners section optional -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8. -You can make a section optional, so that approval from the Code Owners in that section is optional. +You can designate optional sections in your Code Owners file. Prepend the +section name with the caret `^` character to treat the entire section as optional. +Optional sections enable you to designate responsible parties for various parts +of your codebase, but not require approval from them. This approach provides +a more relaxed policy for parts of your project that are frequently updated, +but don't require stringent reviews. -Put a caret `^` character before the Code Owners section name. For example: +In this example, the `[Go]` section is optional: ```plaintext [Documentation] @@ -200,8 +208,12 @@ If a section is duplicated in the file, and one of them is marked as optional an 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. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297638) -to allow direct pushes to the protected branch for sections marked as optional. +section is marked as optional. + +### Allowed to Push + +The Code Owner approval and protected branch features do not apply to users who +are **Allowed to push**. ## Example `CODEOWNERS` file diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 5b19a54bd91..66e5931fa4c 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -71,7 +71,7 @@ To create the `.gitlab/issue_templates` directory: 1. Select **New directory**. 1. Name your directory `issue_templates` and commit to your default branch. -To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) +To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-an-issue) and see if you can choose a description template. ## Create a merge request template diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index e1a81ae1bba..72bf0841687 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -52,9 +52,12 @@ self-managed GitLab instance. - If you're importing to a self-managed GitLab instance, you can alternatively use the [GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects without the constraints of a [Sidekiq](../../../development/sidekiq_style_guide.md) worker. -- If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable - [GitHub integration](../../../integration/github.md). +- If you're importing from GitHub Enterprise to your self-managed GitLab instance: + - You must first enable [GitHub integration](../../../integration/github.md). - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). + - If GitLab is behind a HTTP/HTTPS proxy you must populate the [allowlist for local requests](../../../security/webhooks.md#allowlist-for-local-requests) + with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue + [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941) - If you're importing from GitHub.com to your self-managed GitLab instance, setting up GitHub integration is not required. You can use the [Import API](../../../api/import.md). diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 6e02a9bf5ab..9d7ed593d41 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -76,7 +76,7 @@ a self-managed instance from an old server to a new server. The backups produced don't depend on the operating system running GitLab. You can therefore use the restore method to switch between different operating system distributions or versions, as long -as the same GitLab version [is available for installation](../../../administration/package_information/deprecated_os.md). +as the same GitLab version [is available for installation](../../../administration/package_information/supported_os.md). To instead merge two self-managed GitLab instances together, use the instructions in [Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 78cd2f8fb79..07e8ea1dc06 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -146,7 +146,7 @@ There are numerous [APIs](../../api/index.md) to use with your projects: - [Markdown](../../api/markdown.md) - [Merge Requests](../../api/merge_requests.md) - [Milestones](../../api/milestones.md) -- [Services](../../api/services.md) +- [Services](../../api/integrations.md) - [Snippets](../../api/project_snippets.md) - [Templates](../../api/project_templates.md) - [Traffic](../../api/project_statistics.md) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 436df07d673..957290c5f20 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -149,7 +149,7 @@ Supported values are: | Name | Example | | ----- | ------- | | `bar` |  | -| `bar` (time series, i.e. when `group_by` is used) |  | +| `bar` (time series, that is when `group_by` is used) |  | | `line` |  | | `stacked-bar` |  | diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 963fca34827..b4d7790df1d 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -37,7 +37,7 @@ Complete these steps in GitLab: 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Asana. -1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch** +1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. 1. Select **Save changes** or optionally select **Test settings**. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 58cfd8c3a2f..38de8d9f1af 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,59 +4,66 @@ 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 --- -# Atlassian Bamboo Service **(FREE)** +# Atlassian Bamboo integration **(FREE)** -GitLab provides integration with Atlassian Bamboo for continuous integration. -When configured, pushes to a project trigger a build in Bamboo automatically. -Merge requests also display CI/CD status showing whether the build is pending, -failed, or completed successfully. It also provides a link to the Bamboo build -page for more information. +You can automatically trigger builds in Atlassian Bamboo when you push changes +to your project in GitLab. -Bamboo doesn't quite provide the same features as a traditional build system when -it comes to accepting webhooks and commit data. There are a few things that -need to be configured in a Bamboo build plan before GitLab can integrate. +When this integration is configured, merge requests also display the following information: -## Setup +- A CI/CD status that shows if the build is pending, failed, or has completed successfully. +- A link to the Bamboo build page for more information. -### Complete these steps in Bamboo +Bamboo doesn't provide the same features as a traditional build system when +accepting webhooks and commit data. You must configure a Bamboo +build plan before you configure the integration in GitLab. -1. Navigate to a Bamboo build plan and choose **Configure plan** from the **Actions** - dropdown. +## Configure Bamboo + +1. In Bamboo, go to a build plan and choose **Actions > Configure plan**. 1. Select the **Triggers** tab. -1. Click **Add trigger**. -1. Enter a description such as **GitLab trigger**. -1. Choose **Repository triggers the build when changes are committed**. +1. Select **Add trigger**. +1. Enter a description like `GitLab trigger`. +1. Select **Repository triggers the build when changes are committed**. 1. Select the checkbox for one or more repositories. -1. Enter the GitLab IP address in the **Trigger IP addresses** box. This is a - list of IP addresses that are allowed to trigger Bamboo builds. +1. Enter the GitLab IP address in **Trigger IP addresses**. These IP addresses + are allowed to trigger Bamboo builds. 1. Save the trigger. -1. In the left pane, select a build stage. If you have multiple build stages - you want to select the last stage that contains the Git checkout task. +1. In the left pane, select a build stage. If you have multiple build stages, + select the last stage that contains the Git checkout task. 1. Select the **Miscellaneous** tab. -1. Under **Pattern Match Labeling** put `${bamboo.repository.revision.number}` - in the **Labels** box. -1. Save - -Bamboo is now ready to accept triggers from GitLab. Next, set up the Bamboo -service in GitLab. - -### Complete these steps in GitLab - -1. Navigate to the project you want to configure to trigger builds. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click **Atlassian Bamboo**. -1. Ensure that the **Active** toggle is enabled. -1. Enter the base URL of your Bamboo server. `https://bamboo.example.com` -1. Enter the build key from your Bamboo build plan. Build keys are typically made - up from the Project Key and Plan Key that are set on project/plan creation and - separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all - uppercase identifier that is unique. When viewing a plan in Bamboo, the - build key is also shown in the browser URL, for example `https://bamboo.example.com/browse/PROJ-PLAN`. -1. If necessary, enter username and password for a Bamboo user that has +1. Under **Pattern Match Labeling** enter `${bamboo.repository.revision.number}` + in **Labels**. +1. Select **Save**. + +Bamboo is ready to accept triggers from GitLab. Next, set up the Bamboo +integration in GitLab. + +## Configure GitLab + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Atlassian Bamboo**. +1. Ensure the **Active** checkbox is selected. +1. Enter the base URL of your Bamboo server. For example, `https://bamboo.example.com`. +1. Enter the [build key](#identify-the-bamboo-build-plan-build-key) from your Bamboo + build plan. +1. If necessary, enter a username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require authentication. -1. Save or optionally click **Test Settings**. **Test Settings** - actually triggers a build in Bamboo. +1. Optional. To test the configuration and trigger a build in Bamboo, + select **Test Settings**. +1. Select **Save changes**. + +### Identify the Bamboo build plan build key + +A build key is a unique identifier typically made up from the project key and +plan key. +Build keys are short, all uppercase, and separated with a dash (`-`), +for example `PROJ-PLAN`. + +The build key is included in the browser URL when you view a plan in +Bamboo. For example, `https://bamboo.example.com/browse/PROJ-PLAN`. ## Troubleshooting diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 47a81594ca9..9f1ea3796c6 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -6,17 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub project integration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab Premium 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab 10.6. -GitLab provides an integration for updating the pipeline statuses on GitHub. -This is especially useful if using GitLab for CI/CD only. - -This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) -and is automatically configured on [GitHub import](../../../integration/github.md). +You can update GitHub with pipeline status updates from GitLab. +This integration can help you if you use GitLab for CI/CD.  -## Configuration +This project integration is separate from the [instance-wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) +and is automatically configured when you import a [GitHub project](../../../integration/github.md). + +## Configure the integration This integration requires a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo:status` access granted. @@ -26,31 +26,39 @@ Complete these steps on GitHub: 1. Go to your **Personal access tokens** page at <https://github.com/settings/tokens>. 1. Select **Generate new token**. 1. Under **Note**, enter a name for the new token. -1. Ensure that `repo:status` is checked and select **Generate token**. +1. Ensure `repo:status` is selected and select **Generate token**. 1. Copy the generated token to use in GitLab. Complete these steps in GitLab: -1. Go to the project you want to configure. -1. Go to the [Integrations page](overview.md#accessing-integrations) +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **GitHub**. -1. Ensure that the **Active** toggle is enabled. -1. Paste the token you generated on GitHub. -1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`. -1. (Optional) To disable static status check names, clear the **Enable static status check names** checkbox. -1. Select **Save changes** or optionally select **Test settings**. +1. Ensure the **Active** checkbox is selected. +1. In **Token**, paste the token you generated on GitHub. +1. In **Repository URL**, enter the path to your project on GitHub, such as `https://github.com/username/repository`. +1. Optional. To disable [static status check names](#static-or-dynamic-status-check-names), clear the **Enable static status check names** checkbox. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. ### Static or dynamic status check names -> - Introduced in GitLab 11.5: using static status check names as opt-in option. -> - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. +> - Introduced in GitLab 11.5 with static status check names as an opt-in option. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/9931) in GitLab 12.4 to make static status check names the default behavior for new projects. + +A status check name can be static or dynamic: + +- **Static**: The hostname of your + GitLab instance is appended to the status check name. -This makes it possible to mark these status checks as **Required** on GitHub. +- **Dynamic**: The branch name is appended + to the status check name. -When **Enable static status check names** is checked on the integration page, your -GitLab instance host name is appended to a status check name. +The **Enable static status check names** option enables you to configure +required status checks in GitHub, which need a consistent (static) name to work correctly. -When unchecked, it uses dynamic status check names and appends the branch name. +If you [disable this option](#configure-the-integration), +GitLab uses dynamic status check names instead. diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index bcaedbc4b10..7a96bb74e3f 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -32,7 +32,7 @@ Select a room and create a webhook: 1. Enter the room where you want to receive notifications from GitLab. 1. Open the room dropdown menu on the top-left and select **Manage webhooks**. 1. Enter the name for your webhook, for example "GitLab integration". -1. (Optional) Add an avatar for your bot. +1. Optional. Add an avatar for your bot. 1. Select **Save**. 1. Copy the webhook URL. @@ -46,7 +46,7 @@ Enable the Google Chat integration in GitLab: 1. Scroll down to the end of the page where you find a **Webhook** field. 1. Enter the webhook URL you copied from Google Chat. 1. Select the events you want to be notified about in your Google Chat room. -1. (Optional) Select **Test settings** to verify the connection. +1. Optional. Select **Test settings** to verify the connection. 1. Select **Save changes**. To test the integration, make a change based on the events you selected and diff --git a/doc/user/project/integrations/img/webhook_testing.png b/doc/user/project/integrations/img/webhook_testing.png Binary files differindex 27836556acc..88ce05668f9 100644 --- a/doc/user/project/integrations/img/webhook_testing.png +++ b/doc/user/project/integrations/img/webhook_testing.png diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index b96605ff5c9..279b139bacd 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -10,7 +10,7 @@ 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. -See also the [irker integration API documentation](../../../api/services.md). +See also the [irker integration API documentation](../../../api/integrations.md). For more information, see the [irker project homepage](https://gitlab.com/esr/irker). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 119f219499c..f3f8d900e12 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -50,12 +50,12 @@ Then fill in the integration configuration: - **Webhook**: The incoming webhook URL on Mattermost, similar to `http://mattermost.example/hooks/5xo…`. -- **Username**: (Optional) The username shown in messages sent to Mattermost. +- **Username**: Optional. The username shown in messages sent to Mattermost. To change the bot's username, provide a value. - **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want notifications about failed pipelines only. - **Branches for which notifications are to be sent**: The branches to send notifications for. -- **Labels to be notified**: (Optional) Labels required for the issue or merge request +- **Labels to be notified**: Optional. Labels required for the issue or merge request to trigger a notification. Leave blank to notify for all issues and merge requests. - **Labels to be notified behavior**: When you use the **Labels to be notified** filter, messages are sent when an issue or merge request contains _any_ of the labels specified diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 93a3490e4b6..8b17f4afaa8 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -42,6 +42,6 @@ Complete these steps in GitLab: 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Pivotal Tracker. -1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch** +1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. 1. Select **Save changes** or optionally select **Test settings**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index d399c7f2901..87f38c3482b 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -31,7 +31,7 @@ to control GitLab from Slack. Slash commands are configured separately. [Triggers for Slack notifications](#triggers-for-slack-notifications). By default, messages are sent to the channel you configured during [Slack configuration](#configure-slack). -1. (Optional) To send messages to a different channel, multiple channels, or as +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. @@ -42,7 +42,7 @@ to control GitLab from Slack. Slash commands are configured separately. 1. In **Webhook**, enter the webhook URL you copied in the [Slack configuration](#configure-slack) step. -1. (Optional) In **Username**, enter the username of the Slack bot that sends +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 for which notifications are to be sent** dropdown, select which types of branches diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 4c35f007fc7..47a2d215024 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -219,27 +219,6 @@ This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, and vice versa. -### GraphQL-based issue boards - -<!-- 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), enabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1 -> - [Feature flag `graphql_board_lists`](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) removed in GitLab 14.3 - -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. - -Using GraphQL-based boards gives you these -additional features: - -- [Edit more issue attributes](#edit-an-issue) -- [View blocked issues](#blocked-issues) - -Learn more about the known issues in [epic 5596](https://gitlab.com/groups/gitlab-org/-/epics/5596). - ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -334,19 +313,13 @@ As in other list types, click the trash icon to remove a list. ### Iteration lists **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. -> - Enabled on GitLab.com and is ready for production use. -> - Enabled with `iteration_board_lists` flag for self-managed GitLab and is ready for production use. -> GitLab administrators can opt to [disable the feature flag](#enable-or-disable-iteration-lists-in-boards). - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an -administrator to [disable the `iteration_board_lists` flag](../../administration/feature_flags.md). -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11 [with a flag](../../administration/feature_flags.md) named `iteration_board_lists`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75404) in GitLab 14.6. Feature flag `iteration_board_lists` removed. You're also able to create lists of an iteration. -These are lists that filter issues by the assigned -iteration. To add an iteration list: +These lists filter issues by the assigned iteration. + +To add an iteration list: 1. Select **Create list**. 1. Select **Iteration**. @@ -434,8 +407,6 @@ status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. -This feature is only supported when using the [GraphQL-based boards](#graphql-based-issue-boards). The feature is enabled by default regardless when you use group issue boards in epic swimlanes mode. -  ## Actions you can take on an issue board @@ -457,25 +428,25 @@ If you're not able to do some of the things above, make sure you have the right ### Edit an issue +> Editing title, iteration, and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1. + You can edit an issue without leaving the board view. To open the right sidebar, select an issue card (not its title). You can edit the following issue attributes in the right sidebar: - Assignees -- [Epic](../group/epics/index.md) -- Milestone -- Time tracking value (view only) +- Confidentiality - Due date +- [Epic](../group/epics/index.md) +- [Iteration](../group/iterations/index.md) - Labels -- [Weight](issues/issue_weight.md) +- Milestone - Notifications setting - -When you use [GraphQL-based boards](#graphql-based-issue-boards), you can also edit the following issue attributes: - - Title -- [Iteration](../group/iterations/index.md) -- Confidentiality +- [Weight](issues/issue_weight.md) + +Additionally, you can also see the time tracking value. ### Create a new list @@ -620,13 +591,12 @@ and the target list. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. > - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-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](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an +administrator to [enable the feature flag](../../administration/feature_flags.md) named `board_multi_select`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. @@ -668,41 +638,3 @@ A few things to remember: - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next 20 appear. - -### Enable or disable iteration lists in boards **(PREMIUM SELF)** - -The iteration list 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 disable it. - -To enable it: - -```ruby -Feature.enable(:iteration_board_lists) -``` - -To disable it: - -```ruby -Feature.disable(:iteration_board_lists) -``` - -### Enable or disable multi-selecting issue cards **(FREE SELF)** - -Multi-selecting issue cards is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:board_multi_select) -``` - -To disable it: - -```ruby -Feature.disable(:board_multi_select) -``` diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index b8a01f7ccd6..e8c58f2feb9 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -42,6 +42,11 @@ system note in the issue's comments.  +When an issue is made confidential, only users with at least the [Reporter role](../../permissions.md) +for the project have access to the issue. +Users with Guest or [Minimal](../../permissions.md#users-with-minimal-access) roles can't access +the issue even if they were actively participating before the change. + ## Indications of a confidential issue There are a few things that visually separate a confidential issue from a @@ -88,7 +93,7 @@ sees in the project's search results respectively. |:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| |  |  | -## Related links +## Related topics - [Merge requests for confidential issues](../merge_requests/confidential.md) - [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 02a4f6a4384..69dc0cbafd8 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Issues can be imported to a project by uploading a CSV file with the columns `title` and `description`. Other columns are **not** imported. If you want to -retain columns such as labels and milestones, consider the [Move Issue feature](managing_issues.md#moving-issues). +retain columns such as labels and milestones, consider the [Move Issue feature](managing_issues.md#move-an-issue). The user uploading the CSV file is set as the author of the imported issues. @@ -48,7 +48,7 @@ When importing issues from a CSV file, it must be formatted in a certain way: - **double-quote character:** The double-quote (`"`) character is used to quote fields, enabling the use of the column separator within a field (see the third line in the sample CSV data below). To insert a double-quote (`"`) within a quoted - field, use two double-quote characters in succession, i.e. `""`. + field, use two double-quote characters in succession (`""`). - **data rows:** After the header row, succeeding rows must follow the same column order. The issue title is required while the description is optional. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 37c00bf0efa..ecf35fc4dcf 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -271,4 +271,4 @@ This is rendered as: User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#access-your-user-profile), [group](../../group/index.md#view-group-activity), -and [project](../working_with_projects.md#project-activity) activity pages. +and [project](../working_with_projects.md#view-project-activity) activity pages. diff --git a/doc/user/project/issues/img/button_close_issue_v13_6.png b/doc/user/project/issues/img/button_close_issue_v13_6.png Binary files differdeleted file mode 100644 index 6c7f8da496b..00000000000 --- a/doc/user/project/issues/img/button_close_issue_v13_6.png +++ /dev/null diff --git a/doc/user/project/issues/img/comment-or-discussion.png b/doc/user/project/issues/img/comment-or-discussion.png Binary files differdeleted file mode 100644 index a29014c984c..00000000000 --- a/doc/user/project/issues/img/comment-or-discussion.png +++ /dev/null diff --git a/doc/user/project/issues/img/create_mr_from_issue.png b/doc/user/project/issues/img/create_mr_from_issue.png Binary files differdeleted file mode 100644 index d05a678cd17..00000000000 --- a/doc/user/project/issues/img/create_mr_from_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/delete_issue_v13_11.png b/doc/user/project/issues/img/delete_issue_v13_11.png Binary files differdeleted file mode 100644 index d9905012eab..00000000000 --- a/doc/user/project/issues/img/delete_issue_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/disable_issue_auto_close.png b/doc/user/project/issues/img/disable_issue_auto_close.png Binary files differdeleted file mode 100644 index 5894d39622a..00000000000 --- a/doc/user/project/issues/img/disable_issue_auto_close.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_activity_sort_order_v12_10.png b/doc/user/project/issues/img/issue_activity_sort_order_v12_10.png Binary files differdeleted file mode 100644 index 3e19ee1ac66..00000000000 --- a/doc/user/project/issues/img/issue_activity_sort_order_v12_10.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_type_change_v13_12.png b/doc/user/project/issues/img/issue_type_change_v13_12.png Binary files differdeleted file mode 100644 index 55aa607b878..00000000000 --- a/doc/user/project/issues/img/issue_type_change_v13_12.png +++ /dev/null diff --git a/doc/user/project/issues/img/issues_main_view_numbered.png b/doc/user/project/issues/img/issues_main_view_numbered.png Binary files differdeleted file mode 100644 index 92b9df44972..00000000000 --- a/doc/user/project/issues/img/issues_main_view_numbered.png +++ /dev/null diff --git a/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png b/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png Binary files differdeleted file mode 100644 index 26b42239c12..00000000000 --- a/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_email.png b/doc/user/project/issues/img/new_issue_from_email.png Binary files differdeleted file mode 100644 index 6da899ea37c..00000000000 --- a/doc/user/project/issues/img/new_issue_from_email.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_issue_board.png b/doc/user/project/issues/img/new_issue_from_issue_board.png Binary files differdeleted file mode 100644 index 30a1ffb9011..00000000000 --- a/doc/user/project/issues/img/new_issue_from_issue_board.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png b/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png Binary files differdeleted file mode 100644 index 902aa40614a..00000000000 --- a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png b/doc/user/project/issues/img/new_issue_from_projects_dashboard.png Binary files differdeleted file mode 100644 index 474ca2b45c0..00000000000 --- a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_tracker_list.png b/doc/user/project/issues/img/new_issue_from_tracker_list.png Binary files differdeleted file mode 100644 index 66793cb44fa..00000000000 --- a/doc/user/project/issues/img/new_issue_from_tracker_list.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_v13_1.png b/doc/user/project/issues/img/new_issue_v13_1.png Binary files differdeleted file mode 100644 index a66846c234e..00000000000 --- a/doc/user/project/issues/img/new_issue_v13_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png Binary files differdeleted file mode 100644 index 4612ae254d4..00000000000 --- a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/show-all-activity.png b/doc/user/project/issues/img/show-all-activity.png Binary files differdeleted file mode 100644 index 55c6f5ab5db..00000000000 --- a/doc/user/project/issues/img/show-all-activity.png +++ /dev/null diff --git a/doc/user/project/issues/img/sidebar_move_issue.png b/doc/user/project/issues/img/sidebar_move_issue.png Binary files differdeleted file mode 100644 index 031284a24b2..00000000000 --- a/doc/user/project/issues/img/sidebar_move_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/similar_issues.png b/doc/user/project/issues/img/similar_issues.png Binary files differdeleted file mode 100644 index c5b7902b2ac..00000000000 --- a/doc/user/project/issues/img/similar_issues.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 64838b261ce..bd0cf92e320 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -29,24 +29,25 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ ## Related topics -- [Create issues](managing_issues.md#create-a-new-issue) +- [Create issues](managing_issues.md#create-an-issue) - [Create an issue from a template](../../project/description_templates.md#use-the-templates) -- [Move issues](managing_issues.md#moving-issues) -- [Close issues](managing_issues.md#closing-issues) -- [Delete issues](managing_issues.md#deleting-issues) +- [Edit issues](managing_issues.md#edit-an-issue) +- [Move issues](managing_issues.md#move-an-issue) +- [Close issues](managing_issues.md#close-an-issue) +- [Delete issues](managing_issues.md#delete-an-issue) - [Promote issues](managing_issues.md#promote-an-issue-to-an-epic) - [Set a due date](due_dates.md) - [Import issues](csv_import.md) - [Export issues](csv_export.md) - [Upload designs to issues](design_management.md) - [Linked issues](related_issues.md) +- [Similar issues](managing_issues.md#similar-issues) +- [Health status](managing_issues.md#health-status) - [Cross-link issues](crosslinking_issues.md) -- [Bulk edit issues](../issues/managing_issues.md) - [Sort issue lists](sorting_issue_lists.md) - [Search for issues](../../search/index.md#filter-issue-and-merge-request-lists) - [Epics](../../group/epics/index.md) - [Issue boards](../issue_board.md) - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) -- [Parts of an issue](issue_data_and_actions.md) - [Tasks](../../tasks.md) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 6bb60e5e31a..66ca29c094e 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,315 +1,9 @@ --- -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 +redirect_to: 'index.md' +remove_date: '2022-02-24' --- -# Issue Data and Actions **(FREE)** +This file was moved to [another location](index.md). -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -## Parts of an Issue - -The image below illustrates what an issue may look like. Certain parts -look slightly different or are absent, depending on the GitLab version -and the user's permissions. - -You can find all of an issue's information on one page. - - - -The numbers in the image correspond to the following features: - -- **1.** [Issue actions](#issue-actions) -- **2.** [To Do](#to-do) -- **3.** [Assignee](#assignee) - - **3.1.** [Multiple Assignees](#multiple-assignees) -- **4.** [Epic](#epic) -- **5.** [Milestone](#milestone) -- **6.** [Time tracking](#time-tracking) -- **7.** [Due date](#due-date) -- **8.** [Labels](#labels) -- **9.** [Weight](#weight) -- **10.** [Confidentiality](#confidentiality) -- **11.** [Lock issue](#lock-issue) -- **12.** [Participants](#participants) -- **13.** [Notifications](#notifications) -- **14.** [Reference](#reference) -- [Issue email](#email) -- **15.** [Edit](#edit) -- **16.** [Description](#description) -- **17.** [Mentions](#mentions) -- **18.** [Linked Issues](#linked-issues) -- **19.** [Related Merge Requests](#related-merge-requests) -- **20.** [Award emoji](#award-emoji) -- **21.** [Show all activity](#show-all-activity) -- **22.** [Create Merge Request](#create-merge-request) -- **23.** [Issue history](#issue-history) - - [Activity sort order](#activity-sort-order) -- **24.** [Comments](#comments) -- **25.** [Submit comment, start a thread, or comment and close](#submit-comment-start-a-thread-or-comment-and-close) -- **26.** [Zoom meetings](#zoom-meetings) - -Many of the elements of the issue screen refresh automatically, such as the title and -description, when they are changed by another user. Comments and system notes also -update automatically in response to various actions and content updates. - -### Issue actions - -In an open issue, you can close it by selecting the **Close issue** button. -The issue is marked as closed but is not deleted. - -To reopen a closed issue, select the **Reopen issue** button. -A reopened issue is no different from any other open issue. - -To access additional actions, select the vertical ellipsis -(**{ellipsis_v}**) button: - -- To create a new issue in the same project, select **New issue** in the dropdown menu. - -- If you are not the issue author, you can [submit an abuse report](../../report_abuse.md). - Select **Report abuse** in the dropdown menu. - -### To Do - -You can add issues to and remove issues from your [GitLab To-Do List](../../todos.md). - -The button to do this has a different label depending on whether the issue is already on your To-Do -List or not. If the issue is: - -- Already on your To-Do List: The button is labeled **Mark as done**. Click the button to remove the issue from your To-Do List. -- Not on your To-Do List: The button is labeled **Add a to do**. Click the button to add the issue to your To-Do List. - -### Assignee - -An issue can be assigned to: - -- Yourself. -- Another person. -- [Many people](#multiple-assignees). **(PREMIUM)** - -The assignees can be changed as often as needed. The idea is that the assignees are -responsible for that issue until it's reassigned to someone else to take it from there. -When assigned to someone, it appears in their assigned issues list. - -NOTE: -If a user is not member of that project, it can only be -assigned to them if they created the issue themselves. - -#### Multiple Assignees **(PREMIUM)** - -Often, multiple people work on the same issue together. This can be difficult -to track in large teams where there is shared ownership of an issue. - -To help with this, you can use GitLab to -[assign multiple people](multiple_assignees_for_issues.md) to an issue. - -### Epic **(PREMIUM)** - -You can assign issues to an [Epic](../../group/epics/index.md), which allows better -management of groups of related issues. - -### Milestone - -Select a [milestone](../milestones/index.md) to attribute that issue to. - -### Time tracking - -Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time -spent on issues](../time_tracking.md). You can add a [time estimate](../time_tracking.md#estimates) -for resolving the issue, and also add [the time spent](../time_tracking.md#time-spent) -to resolve the issue. - -### Due date - -When you work on a tight schedule, it's important to have a way to set a deadline for -implementations and for solving problems. This can be done in the [due date](due_dates.md) -element. Due dates can be changed as many times as needed. - -### Labels - -Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [issue board](../issue_board.md). - -Group Labels, which allow you to use the same labels for all projects in the same -group, can also be given to issues. They work exactly the same, but are immediately -available to all projects in the group. - -If a label doesn't exist yet, you can create one by clicking **Edit** -followed by **Create new label** in the dropdown menu. - -### Weight **(PREMIUM)** - -[Assign a weight](issue_weight.md) to an issue. -Larger values are used to indicate more effort is required to complete the issue. Only -positive values or zero are allowed. - -### Confidentiality - -You can [set an issue to be confidential](confidential_issues.md). Unauthorized users -cannot access the issue, and it is not listed in the project's issue boards nor list for them. - -### Lock issue - -You can [lock the issue](../../discussions/index.md#prevent-comments-by-locking-an-issue) -to prevent further comments from being added. - -### Participants - -All the users involved in that issue. Either they participated in the [thread](../../discussions/index.md), -or were mentioned in the description or threads. - -### Notifications - -Select the toggle to enable or disable [notifications](../../profile/notifications.md#notifications-on-issues-merge-requests-and-epics) -for the issue. Notifications are automatically enabled after you participate in the issue in any way. - -### Reference - -- A quick "copy" button for that issue's reference, which looks like - `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` is the - `project-name`, and `xxx` is the issue number. - -### Email - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. - -Guest users can see a button in the right sidebar to copy the email address for the issue. -Sending an email to this address creates a comment containing the email body. - -### Edit - -Clicking this icon opens the issue for editing. All the fields which -were shown when the issue was created are displayed for editing. -This icon is only displayed if the user has permission to edit the issue. - -### Description - -The plain text title and description of the issue fill the top center of the issue page. -The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown), -allowing many formatting options. - -[In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an -issue's description are listed in the [issue history](#issue-history). **(PREMIUM)** - -### Mentions - -You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname`. All mentioned users are notified via to-do items and emails, -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 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 -to all the members of that project's group. This might be interpreted as spam. - -### Linked Issues - -Issues that were mentioned as [linked issues](related_issues.md) are listed here. -You can also click the `+` to add more linked issues. - -### Related Merge Requests - -Merge requests that were mentioned in that issue's description or in the issue thread -are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. -Also, if the current issue was mentioned as related in another merge request, that -merge request is also listed here. - -### Award emoji - -You can award emojis to issues. You can select the "thumbs up" and "thumbs down", -or the gray "smiley-face" to choose from the list of available -[GitLab Flavored Markdown Emoji](../../markdown.md#emojis). - -NOTE: -Posting "+1" as a comment in a thread spams all subscribed participants of that issue, -clutters the threads, and is not recommended. Awarding an emoji is a way -to let them know your reaction without notifying them. - -### Show all activity - -You can filter what is displayed in the issue history by clicking on **Show all activity** -and selecting either: - -- **Show comments only**, which only shows threads and hides updates to the issue. -- **Show history only**, which hides threads and only shows updates. - -Also: - -- You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they are notified via to-do items - and emails, unless they have disabled all [notifications](#notifications) - in their user settings. -- Mentions for yourself (the current logged-in user) are highlighted - in a different color, which allows you to quickly see which comments involve you. - - - -### Create Merge Request - -Create a new branch and [**Draft** merge request](../merge_requests/drafts.md) -in one action. The branch is named `issuenumber-title` by default, but you can -choose any name, and GitLab verifies that it is not already in use. The merge request -inherits the milestone and labels of the issue, and is set to automatically -close the issue when it is merged. - - - -Optionally, you can choose to create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) -only, named after that issue. - -### Issue history - -All comments and updates to the issue are tracked and listed here, but this can be -filtered, as shown above. - -#### Activity sort order - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14588) in GitLab 12.10. - -You can reverse the default order and interact with the activity feed sorted by most recent items -at the top. Your preference is saved via local storage and automatically applied to every issue -you view. - -To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest -or newest items to be shown first. - - - -### Comments - -Collaborate in the issue by posting comments in its thread. This text field also fully -supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). - -### Submit comment, start a thread, or comment and close - -After you write a comment, you can: - -- Click **Comment** to publish your comment. -- Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#create-a-thread-without-replying-to-a-comment) - in that issue's main thread to discuss specific points. This invites other participants - to reply directly to your thread, keeping related comments grouped together. - - - -You can also close the issue from here, so you don't need to scroll to the top of the issue page. - -### Zoom meetings - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31103) in GitLab 12.3. - -You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove_zoom` [quick actions](../quick_actions.md) as part of -[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). - -Attaching a [Zoom](https://zoom.us) call an issue -results in a **Join Zoom meeting** button at the top of the issue, just under the header. - -Read more how to [add or remove a zoom meeting](associate_zoom_meeting.md). - -### Publish an issue **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. - -If a status page application is associated with the project, you can use the `/publish` [quick action](../quick_actions.md) to publish the issue. Refer to [GitLab Status Page](../../../operations/incident_management/status_page.md) for more information. +<!-- This redirect file can be deleted after <2022-02-24>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 6b3d5d6563a..1a23902514a 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -4,293 +4,411 @@ 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 --- -# Managing issues **(FREE)** +# Manage issues **(FREE)** [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and planning work in GitLab. -Key actions for issues include: +## Create an issue -- [Creating issues](#create-a-new-issue) -- [Moving issues](#moving-issues) -- [Closing issues](#closing-issues) -- [Deleting issues](#deleting-issues) -- [Promoting issues](#promote-an-issue-to-an-epic) **(PREMIUM)** +When you create an issue, you are prompted to enter the fields of the issue. +If you know the values you want to assign to an issue, you can use +[quick actions](../quick_actions.md) to enter them. -## Create a new issue +You can create an issue in many ways in GitLab: -When you create a new issue, you are prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), -as illustrated below. If you know the values you want to assign to an issue, you can use the -[Quick actions](../quick_actions.md) feature to input values. +- [From a project](#from-a-project) +- [From a group](#from-a-group) +- [From another issue](#from-another-issue) +- [From an issue board](#from-an-issue-board) +- [By sending an email](#by-sending-an-email) +- Using a URL with prefilled fields +- [Using Service Desk](#using-service-desk) -While creating an issue, you can associate it to an existing epic from current group by -selecting it using **Epic** dropdown. +### From a project -### Accessing the New Issue form +Prerequisites: -There are many ways to get to the New Issue form from a project's page: +- You must have at least the [Guest role](../../permissions.md) for the project. -- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: +To create an issue: -  +1. On the top bar, select **Menu > Projects** and find your project. +1. Either: -- From an **open issue** in your project, click the vertical ellipsis (**{ellipsis_v}**) button - to open a dropdown menu, and then click **New Issue** to create a new issue in the same project: + - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. + - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, + select **New issue**. -  +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. -- From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown - menu with a few options. Select **New Issue** to create an issue in that project: +The newly created issue opens. -  +### From a group -- From an **issue board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. - It opens a new issue for that project, pre-labeled with its respective list. +Issues belong to projects, but when you're in a group, you can access and create issues that belong +to the projects in the group. -  +Prerequisites: -### Elements of the New Issue form +- You must have at least the [Guest role](../../permissions.md) for the project in the group. -> Ability to add the new issue to an epic [was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. +To create an issue from a group: - +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues**. +1. In the top right corner, select **Select project to create issue**. +1. Select the project you'd like to create an issue for. The button now reflects the selected + project. +1. Select **New issue in `<project name>`**. +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. -When you're creating a new issue, these are the fields you can fill in: +The newly created issue opens. -- Title -- Description -- Checkbox to make the issue [confidential](confidential_issues.md) -- Assignee -- Weight -- [Epic](../../group/epics/index.md) -- Due date -- Milestone -- Labels +The project you selected most recently becomes the default for your next visit. +This can save you a lot of time and clicks, if you mostly create issues for the same project. -### New issue from the group-level issue tracker +### From another issue -To visit the issue tracker for all projects in your group: +> New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. -1. Go to the group dashboard. -1. On the left sidebar, select **Issues**. -1. In the top-right, select the **Select project to create issue** button. -1. Select the project you'd like to create an issue for. The button now reflects the selected - project. -1. Select the button to create an issue in the selected project. +You can create a new issue from an existing one. The two issues can then be marked as related. - +Prerequisites: -The project you selected most recently becomes the default for your next visit. -This should save you a lot of time and clicks, if you mostly create issues for the same project. +- You must have at least the [Guest role](../../permissions.md) for the project. -### New issue via Service Desk +To create an issue from another issue: -Enable [Service Desk](../service_desk.md) for your project and offer email support. -Now, when your customer sends a new email, a new issue can be created in -the appropriate project and followed up from there. +1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **New issue**. +1. Complete the [fields](#fields-in-the-new-issue-form). + The new issue's description is prefilled with `Related to #123`, where `123` is the ID of the + issue of origin. If you keep this mention in the description, the two issues become + [linked](related_issues.md). +1. Select **Create issue**. -### New issue via email +The newly created issue opens. -A link to **Email a new issue to this project** is displayed at the bottom of a project's -**Issues List** page. The link is shown only if your GitLab instance has [incoming email](../../../administration/incoming_email.md) -configured and there is at least one issue in the issue list. +### From an issue board - +You can create a new issue from an [issue board](../issue_board.md). -When you click this link, an email address is generated and displayed, which should be used -by **you only**, to create issues in this project. You can save this address as a -contact in your email client for quick access. +Prerequisites: -WARNING: -This is a private email address, generated just for you. **Keep it to yourself**, -as anyone who knows it can create issues or merge requests as if they -were you. If the address is compromised, or you want to regenerate it, -click **Email a new issue to this project**, followed by **reset it**. +- You must have at least the [Guest role](../../permissions.md) for the project. + +To create an issue from a project issue board: + +1. On the top bar, select **Menu > Projects** and find your project. +1. Select **Issues > Boards**. +1. At the top of a board list, select **New issue** (**{plus-square}**). +1. Enter the issue's title. +1. Select **Create issue**. + +To create an issue from a group issue board: + +1. On the top bar, select **Menu > Groups** and find your group. +1. Select **Issues > Boards**. +1. At the top of a board list, select **New issue** (**{plus-square}**). +1. Enter the issue's title. +1. Under **Projects**, select the project in the group that the issue should belong to. +1. Select **Create issue**. -Sending an email to this address creates a new issue associated with your account for -this project, where: +The issue is created and shows up in the board list. It shares the list's characteristic, so, for +example, if the list is scoped to a label `Frontend`, the new issue also has this label. -- The email subject becomes the issue title. -- The email body becomes the issue description. -- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. +### By sending an email -NOTE: -In GitLab 11.7, we updated the format of the generated email address. However the -older format is still supported, allowing existing aliases or contacts to continue working. +> Generated email address format changed in GitLab 11.7. +> The older format is still supported, so existing aliases and contacts still work. -### New issue via URL with prefilled fields +You can send an email to create an issue in a project on the project's +**Issues List** page. + +Prerequisites: + +- Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) + configured. +- There must be at least one issue in the issue list. +- You must have at least the [Guest role](../../permissions.md) for the project. + +To email an issue to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. Select **Issues**. +1. At the bottom of the page, select **Email a new issue to this project**. +1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). +1. From your email client, send an email to this address. + The subject is used as the title of the new issue, and the email body becomes the description. + You can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md). + +A new issue is created, with your user as the author. +You can save this address as a contact in your email client to use it again. + +WARNING: +The email address you see is a private email address, generated just for you. +**Keep it to yourself**, because anyone who knows it can create issues or merge requests as if they +were you. + +To regenerate the email address: + +1. On the issues list, select **Email a new issue to this project**. +1. Select **reset this token**. + +### Using a URL with prefilled values To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external -HTML page to create issues with certain -fields prefilled. +HTML page to create issues with certain fields prefilled. + +| Field | URL parameter | Notes | +| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Issue type | `issue[issue_type]` | Either `incident` or `issue`. | +| Description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Cannot be used at the same time as `issuable_template`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | + +Adapt these examples to form your new issue URL with prefilled fields. +To create an issue in the GitLab project: + +- With a prefilled title and description: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Whoa%2C%20we%27re%20half-way%20there&issue[description]=Whoa%2C%20livin%27%20in%20a%20URL + ``` -| Field | URL Parameter Name | Notes | -|----------------------|-----------------------|-------------------------------------------------------| -| title | `issue[title]` | | -| description | `issue[description]` | Cannot be used at the same time as `issuable_template`. | -| description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. | -| issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential. | +- With a prefilled title and description template: -Follow these examples to form your new issue URL with prefilled fields. + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Feature%20Proposal%20-%20basic + ``` -- For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` -- For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` -- For a new issue in the GitLab Community Edition project with a pre-filled title, - a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` +- With a prefilled title, description, and marked as confidential: -## Bulk edit issues at the project level + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true + ``` -> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +### Using Service Desk + +To offer email support, enable [Service Desk](../service_desk.md) for your project. + +Now, when your customer sends a new email, a new issue can be created in +the appropriate project and followed up from there. + +### Fields in the new issue form + +> Adding the new issue to an epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in GitLab 13.1. + +When you're creating a new issue, you can complete the following fields: + +- Title +- Type: either issue (default) or incident +- [Description template](../description_templates.md): overwrites anything in the Description text box +- Description: you can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) +- Checkbox to make the issue [confidential](confidential_issues.md) +- [Assignees](#assignee) +- [Weight](issue_weight.md) +- [Epic](../../group/epics/index.md) +- [Due date](due_dates.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) + +## Edit an issue + +You can edit an issue's title and description. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To edit an issue: + +1. To the right of the title, select **Edit title and description** (**{pencil}**). +1. Edit the available fields. +1. Select **Save changes**. + +### Bulk edit issues from a project + +> - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. > - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. > - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. -Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. +You can edit multiple issues at a time when you're in a project. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To edit multiple issues at the same time: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. Select **Edit issues**. A sidebar on the right of your screen appears. +1. Select the checkboxes next to each issue you want to edit. +1. From the sidebar, edit the available fields. +1. Select **Update all**. When bulk editing issues in a project, you can edit the following attributes: -- Status (open/closed) -- Assignee +- Status (open or closed) +- [Assignees](#assignee) - [Epic](../../group/epics/index.md) - [Milestone](../milestones/index.md) - [Labels](../labels.md) - [Health status](#health-status) -- Notification subscription +- [Notification](../../profile/notifications.md) subscription - [Iteration](../../group/iterations/index.md) -To update multiple project issues at the same time: - -1. In a project, go to **Issues > List**. -1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Select the checkboxes next to each issue you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Bulk edit issues at the group level +### Bulk edit issues from a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. -> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. > - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. > - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. -Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. +You can edit multiple issues across multiple projects when you're in a group. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for a group. + +To edit multiple issues at the same time: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues**. +1. Select **Edit issues**. A sidebar on the right of your screen appears. +1. Select the checkboxes next to each issue you want to edit. +1. From the sidebar, edit the available fields. +1. Select **Update all**. When bulk editing issues in a group, you can edit the following attributes: - [Epic](../../group/epics/index.md) - [Milestone](../milestones/index.md) +- [Iteration](../../group/iterations/index.md) - [Labels](../labels.md) - [Health status](#health-status) -- [Iteration](../../group/iterations/index.md) -To update multiple project issues at the same time: +## Move an issue -1. In a group, go to **Issues > List**. -1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Select the checkboxes next to each issue you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Moving issues - -Moving an issue copies it to the target project, and closes it in the originating project. +When you move an issue, it's closed and copied to the target project. The original issue is not deleted. A system note, which indicates where it came from and went to, is added to both issues. -The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. +Prerequisites: - +- You must have at least the [Reporter role](../../permissions.md) for the project. -### Moving issues in bulk **(FREE SELF)** +To move an issue: -If you have advanced technical skills you can also bulk move all the issues from -one project to another in the rails console. The below script moves all issues -that are not in status **closed** from one project to another. +1. Go to the issue. +1. On the right sidebar, select **Move issue**. +1. Search for a project to move the issue to. +1. Select **Move**. -To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below -script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. -We do also recommend [creating a backup](../../../raketasks/backup_restore.md) before -attempting any changes in the console. +### Bulk move issues **(FREE SELF)** -```ruby -project = Project.find_by_full_path('full path of the project where issues are moved from') -issues = project.issues -admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues -target_project = Project.find_by_full_path('full path of target project where issues moved to') +You can move all open issues from one project to another. -issues.each do |issue| - if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project, admin_user).execute(issue, target_project) - else - puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" - end -end; nil -``` +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To do it: + +1. Optional (but recommended). [Create a backup](../../../raketasks/backup_restore.md) before + attempting any changes in the console. +1. Open the [Rails console](../../../administration/operations/rails_console.md). +1. Run the following script. Make sure to change `project`, `admin_user`, and `target_project` to + your values. + + ```ruby + project = Project.find_by_full_path('full path of the project where issues are moved from') + issues = project.issues + admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues + target_project = Project.find_by_full_path('full path of target project where issues moved to') + + issues.each do |issue| + if issue.state != "closed" && issue.moved_to.nil? + Issues::MoveService.new(project, admin_user).execute(issue, target_project) + else + puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" + end + end; nil + ``` + +1. To exit the Rails console, enter `quit`. -## Closing issues +## Close an issue -When you decide that an issue is resolved, or no longer needed, you can close the issue -using the close button: +When you decide that an issue is resolved or no longer needed, you can close it. +The issue is marked as closed but is not deleted. - +Prerequisites: -You can also close an issue from the [issue boards](../issue_board.md) by dragging an issue card -from its list and dropping it into the **Closed** list. +- You must have at least the [Reporter role](../../permissions.md) for the project. - +To close an issue, you can do the following: + +- At the top of the issue, select **Close issue**. +- In an [issue board](../issue_board.md), drag an issue card from its list into the **Closed** list. + +  + +### Reopen a closed issue + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To reopen a closed issue, at the top of the issue, select **Reopen issue**. +A reopened issue is no different from any other open issue. ### Closing issues automatically -When a commit or merge request resolves issues, the issues -can be closed automatically when the commit reaches the project's default branch. +You can close issues automatically by using certain words in the commit message or MR description. -If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), -all issues referenced in the matched text are closed. This happens when the commit -is pushed to a project's [**default** branch](../repository/branches/default.md), -or when a commit or merge request is merged into it. +If a commit message or merge request description contains text matching the [defined pattern](#default-closing-pattern), +all issues referenced in the matched text are closed when either: -For example, if `Closes #4, #6, Related to #5` is included in a Merge Request -description, issues `#4` and `#6` are closed automatically when the MR is merged, but not `#5`. -Using `Related to` flags `#5` as a [related issue](related_issues.md), -but is not closed automatically. +- The commit is pushed to a project's [**default** branch](../repository/branches/default.md). +- The commit or merge request is merged into the default branch. - +For example, if you include `Closes #4, #6, Related to #5` in a merge request +description: -If the issue is in a different repository than the MR, add the full URL for the issue(s): +- Issues `#4` and `#6` are closed automatically when the MR is merged. +- Issue `#5` is marked as a [related issue](related_issues.md), but it's not closed automatically. -```markdown -Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> -``` +Alternatively, when you [create a merge request from an issue](../merge_requests/getting_started.md#merge-requests-to-close-issues), +it inherits the issue's milestone and labels. For performance reasons, automatic issue closing is disabled for the very first push from an existing repository. #### Default closing pattern -When not specified, this default issue closing pattern is used: +To automatically close an issue, use the following keywords followed by the issue reference. -```shell -\b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) -``` - -This translates to the following keywords: +Available keywords: - Close, Closes, Closed, Closing, close, closes, closed, closing - Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing - Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving - Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing -Note that `%{issue_ref}` is a complex regular expression defined inside the GitLab -source code that can match references to: +Available issue reference formats: - A local issue (`#123`). - A cross-project issue (`group/project#123`). -- A link to an issue (`https://gitlab.example.com/group/project/issues/123`). +- The full URL of an issue (`https://gitlab.example.com/group/project/issues/123`). -For example the following commit message: +For example: ```plaintext Awesome commit message @@ -300,54 +418,93 @@ This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23. ``` -closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +The previous commit message closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, as well as `#22` and `#23` in `group/otherproject`. `#17` is not closed as it does -not match the pattern. It works with multi-line commit messages as well as one-liners -when used from the command line with `git commit -m`. +not match the pattern. + +You can use the closing patterns in multi-line commit messages or one-liners +done from the command line with `git commit -m`. -#### Disabling automatic issue closing +The default issue closing pattern regex: + +```shell +\b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) +``` + +#### Disable automatic issue closing > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. -The automatic issue closing feature can be disabled on a per-project basis -in the [project's repository settings](../settings/index.md). Referenced -issues are still displayed, but are not closed automatically. +You can disable the automatic issue closing feature on a per-project basis +in the [project's settings](../settings/index.md). + +Prerequisites: - +- You must have at least the [Maintainer role](../../permissions.md) for the project. -The automatic issue closing is also disabled in a project if the project has the issue tracker +To disable automatic issue closing: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Default branch**. +1. Select **Auto-close referenced issues on default branch**. +1. Select **Save changes**. + +Referenced issues are still displayed, but are not closed automatically. + +The automatic issue closing is disabled by default in a project if the project has the issue tracker disabled. If you want to enable automatic issue closing, make sure to [enable GitLab Issues](../settings/index.md#sharing-and-permissions). -This only applies to issues affected by new merge requests or commits. Already -closed issues remain as-is. +Changing this setting applies only to new merge requests or commits. Already +closed issues remain as they are. If issue tracking is enabled, disabling automatic issue closing only applies to merge requests -attempting to automatically close issues within the same project. +attempting to automatically close issues in the same project. Merge requests in other projects can still close another project's issues. -#### Customizing the issue closing pattern **(FREE SELF)** +#### Customize the issue closing pattern **(FREE SELF)** + +Prerequisites: -In order to change the default issue closing pattern, GitLab administrators must edit the +- You must have the [administrator access level](../../../administration/index.md) for your GitLab instance. + +To change the default issue closing pattern, edit the [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) of your installation. ## Change the issue type -Users with the [Developer role](../../permissions.md) -can change an issue's type. To do this, edit the issue and select an issue type from the -**Issue type** selector menu: +Prerequisites: + +- You must be the issue author or have at least the [Reporter role](../../permissions.md) for the project. + +To change issue type: + +1. To the right of the title, select **Edit title and description** (**{pencil}**). +1. Edit the issue and select an issue type from the **Issue type** dropdown list: -- [Issue](index.md) -- [Incident](../../../operations/incident_management/index.md) + - Issue + - [Incident](../../../operations/incident_management/index.md) - +1. Select **Save changes**. -## Deleting issues +## Delete an issue -Users with the [Owner role](../../permissions.md) can delete an issue by -editing it and selecting **Delete issue**. +> Deleting from the vertical ellipsis menu [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299933) in GitLab 14.6. - +Prerequisites: + +- You must have the [Owner role](../../permissions.md) for a project. + +To delete an issue: + +1. In an issue, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Delete issue**. + +Alternatively: + +1. In an issue, select **Edit title and description** (**{pencil}**). +1. Select **Delete issue**. ## Promote an issue to an epic **(PREMIUM)** @@ -355,16 +512,16 @@ editing it and selecting **Delete issue**. > - Moved to GitLab Premium in 12.8. > - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab Premium 13.6. -You can promote an issue to an epic in the immediate parent group. +You can promote an issue to an [epic](../../group/epics/index.md) in the immediate parent group. To promote an issue to an epic: -1. In an issue, select the vertical ellipsis (**{ellipsis_v}**) button. +1. In an issue, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Promote to epic**. Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). -Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). +Read more about [promoting an issues to epics](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). ## Add an issue to an iteration **(PREMIUM)** @@ -373,12 +530,41 @@ Read more about promoting an issue to an epic on the [Manage epics page](../../g To add an issue to an [iteration](../../group/iterations/index.md): -1. In an issue sidebar, click **Edit** next to **Iteration**. A dropdown appears. -1. Click an iteration you'd like to associate this issue with. +1. Go to the issue. +1. On the right sidebar, in the **Iteration** section, select **Edit**. +1. From the dropdown list, select the iteration to associate this issue with. +1. Select any area outside the dropdown list. + +Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics). + +## Copy issue reference + +To refer to an issue elsewhere in GitLab, you can use its full URL or a short reference, which looks like +`namespace/project-name#123`, where `namespace` is either a group or a username. + +To copy the issue reference to your clipboard: -You can also use the `/iteration` -[quick action](../quick_actions.md#issues-merge-requests-and-epics) -in a comment or description field. +1. Go to the issue. +1. On the right sidebar, next to **Reference**, select **Copy Reference** (**{copy-to-clipboard}**). + +You can now paste the reference into another description or comment. + +Read more about issue references in [GitLab-Flavored Markdown](../../markdown.md#gitlab-specific-references). + +## Copy issue email address + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. + +You can create a comment in an issue by sending an email. +Sending an email to this address creates a comment that contains the email body. + +To learn more about creating comments by sending an email and the necessary configuration, see +[Reply to a comment by sending email](../../discussions/index.md#reply-to-a-comment-by-sending-email). + +To copy the issue's email address: + +1. Go to the issue. +1. On the right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**). ## Real-time sidebar @@ -393,35 +579,84 @@ On GitLab.com, this feature is available. Assignees in the sidebar are updated in real time. +## Assignee + +An issue can be assigned to one or [more users](multiple_assignees_for_issues.md). + +The assignees can be changed as often as needed. The idea is that the assignees are +people responsible for an issue. +When an issue is assigned to someone, it appears in their assigned issues list. + +If a user is not a member of a project, an issue can only be assigned to them if they create it +themselves or another project member assigns them. + +To change the assignee on an issue: + +1. Go to your issue. +1. On the right sidebar, in the **Assignee** section, select **Edit**. +1. From the dropdown list, select the user to add as an assignee. +1. Select any area outside the dropdown list. + ## Similar issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22866) in GitLab 11.6. +To prevent duplication of issues on the same topic, GitLab searches for similar issues +when you create a new issue. -To prevent duplication of issues for the same topic, GitLab searches for similar issues -when new issues are being created. +Prerequisites: -As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions -across all issues to in the current project. Only issues you have access to are returned. -Up to five similar issues, sorted by most recently updated, are displayed below the title box. -[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature. +- [GraphQL](../../../api/graphql/index.md) must be enabled. - +As you type in the title text box of the **New issue** page, GitLab searches titles and descriptions +across all issues in the current project. Only issues you have access to are returned. +Up to five similar issues, sorted by most recently updated, are displayed below the title text box. ## Health status **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10. -> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later. -> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab 12.10. +> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab 13.4 and later. +> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. To help you track issue statuses, you can assign a status to each issue. -This marks issues as progressing as planned or needs attention to keep on schedule: +This status marks issues as progressing as planned or needing attention to keep on schedule. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To edit health status of an issue: + +1. Go to the issue. +1. On the right sidebar, in the **Health status** section, select **Edit**. +1. From the dropdown list, select the status to add to this issue: -- On track (green) -- Needs attention (amber) -- At risk (red) + - On track (green) + - Needs attention (amber) + - At risk (red) + +You can then see the issue's status in the issues list and the epic tree. After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. -You can then see issue statuses in the issues list and the epic tree. +## Publish an issue **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.1. + +If a status page application is associated with the project, you can use the `/publish` +[quick action](../quick_actions.md) to publish the issue. + +For more information, see [GitLab Status Page](../../../operations/incident_management/status_page.md). + +## Issue-related quick actions + +You can also use [quick actions](../quick_actions.md#issues-merge-requests-and-epics) to manage issues. + +Some actions don't have corresponding UI buttons yet. +You can do the following **only by using quick actions**: + +- [Add or remove a Zoom meeting](associate_zoom_meeting.md) (`/zoom` and `/remove_zoom`). +- [Publish an issue](#publish-an-issue) (`/publish`). +- Clone an issue to the same or another project (`/clone`). +- Close an issue and mark as a duplicate of another issue (`/duplicate`). +- Copy labels and milestone from another merge request in the project (`/copy_metadata`). diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 189777d40e7..98e940b6b51 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -12,8 +12,7 @@ In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who didn't even start yet. -In [GitLab Enterprise Edition](https://about.gitlab.com/pricing/), -you can also select multiple assignees to an issue, making it easier to +You can also select multiple [assignees](managing_issues.md#assignee) for an issue, making it easier to track, and making clearer who is accountable for it.  diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index e4972181a5a..8a2a104c54d 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -26,7 +26,7 @@ To manage linked issues through our API, visit the [issue links API documentatio 1. Link one issue to another by selecting the add linked issue button (**{plus}**) in the **Linked issues** section of an issue. -1. Select the relationship the between the two issues. Either: +1. Select the relationship between the two issues. Either: - **relates to** - **blocks** **(PREMIUM)** - **is blocked by** **(PREMIUM)** diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index ebfc723280f..0340f15c25c 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -37,7 +37,7 @@ creation date. Issues created most recently are first. ## Sorting by due date When you sort by **Due date**, the issue list changes to sort ascending by the issue -[due date](issue_data_and_actions.md#due-date). Issues with the earliest due date are first, +[due date](due_dates.md). Issues with the earliest due date are first, and issues without a due date are last. ## Sorting by label priority diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index e9cbe012110..8874512f9c3 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -16,7 +16,7 @@ Labels are a key part of [issue boards](issue_board.md). With labels you can: - Categorize epics, issues, and merge requests using colors and descriptive titles like `bug`, `feature request`, or `docs`. - Dynamically filter and manage epics, issues, and merge requests. -- [Search lists of issues, merge requests, and epics](../search/index.md#issues-and-merge-requests), +- [Search lists of issues, merge requests, and epics](../search/index.md#search-issues-and-merge-requests), as well as [issue boards](../search/index.md#issue-boards). ## Project labels and group labels @@ -42,8 +42,8 @@ To assign or unassign a label: You can search repeatedly to add more labels. The selected labels are marked with a checkmark. 1. Click the labels you want to assign or unassign. -1. To apply your changes to labels, click **X** next to **Assign labels** or anywhere outside the - label section. +1. To apply your changes to labels, select **X** next to **Assign labels** or select any area + outside the label section. Alternatively, to unassign a label, click the **X** on the label you want to unassign. @@ -72,9 +72,9 @@ To create a new project label: 1. Select the **New label** button. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). -1. (Optional) In the **Description** field, you can enter additional +1. Optional. In the **Description** field, you can enter additional information about how and when to use this label. -1. (Optional) Select a background color for the label by selecting one of the +1. Optional. Select a background color for the label by selecting one of the available colors, or by entering a hex color value in the **Background color** field. 1. Select **Create label**. @@ -86,7 +86,7 @@ label section of the right sidebar of an issue or a merge request: 1. Click **Create project label**. - Fill in the name field. Note that you can't specify a description if creating a label this way. You can add a description later by editing the label (see below). - - (Optional) Select a color by clicking on the available colors, or input a hex + - Optional. Select a color by clicking on the available colors, or input a hex color value for a specific color. 1. Click **Create**. @@ -189,7 +189,7 @@ For example, filtering by the `platform::*` label returns issues that have `plat `platform::Android`, or `platform::Linux` labels. NOTE: -This is not available on the [issues or merge requests dashboard pages](../search/index.md#issues-and-merge-requests). +This is not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests). ### Workflows with scoped labels diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index adf0a115c6e..283576fb4e9 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -52,7 +52,8 @@ Prerequisite: To add groups to a project: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. On the **Invite group** tab, under **Select a group to invite**, choose a group. 1. Select the highest max [role](../../permissions.md) for users in the group. 1. Optional. Choose an expiration date. On that date, the user can no longer access the project. @@ -75,7 +76,8 @@ Prerequisite: To import users: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. On the **Invite member** tab, at the bottom of the panel, select **Import**. 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. @@ -115,7 +117,8 @@ Prerequisites: To remove a member from a project: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. Next to the project member you want to remove, select **Remove member** **{remove}**. 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. @@ -136,7 +139,8 @@ You can filter and sort members in a project. ### Display inherited members -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press Enter. @@ -144,7 +148,8 @@ You can filter and sort members in a project. ### Display direct members -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press Enter. @@ -166,7 +171,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. Go to the project you'd like to be a member of. +1. On the top bar, select **Menu > Projects** and find the project you want to be a member of. 1. By the project name, select **Request Access**.  @@ -189,8 +194,9 @@ Prerequisite: - You must be the project owner. -1. Go to the project and select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Under **Project visibility**, select **Users can request access**. 1. Select **Save changes**. @@ -213,7 +219,8 @@ This feature might not be available to you. Check the **version history** note a In GitLab 13.11, you can optionally replace the form to add a member with a modal window. To add a member after enabling this feature: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. Select **Invite members**. 1. Enter an email address and select a role. 1. Optional. Select an **Access expiration date**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index abca140411a..4c96c4d9f56 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,7 +4,7 @@ group: Workspace info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Share projects with other groups +# Share projects with other groups **(FREE)** You can share projects with other [groups](../../group/index.md). This makes it possible to add a group of users to a project with a single action. @@ -30,18 +30,20 @@ To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Project information > Members**. 1. Select the **Invite group** tab. 1. Add the 'Engineering' group with the maximum access level of your choice. -1. Optionally, select an expiring date. -1. Click **Invite**. -1. After sharing 'Project Acme' with 'Engineering': - - The group is listed in the **Groups** tab. - - The project is listed on the group dashboard. +1. Optional. Select an expiration date. +1. Select **Invite**. + +After sharing 'Project Acme' with 'Engineering': + +- The group is listed in the **Groups** tab. +- The project is listed on the group dashboard. -Note that you can only share a project with: +You can share a project only with: -- groups for which you have an explicitly defined membership -- groups that contain a nested subgroup or project for which you have an explicitly defined role +- Groups for which you have an explicitly defined membership. +- Groups that contain a nested subgroup or project for which you have an explicitly defined role. -Administrators are able to share projects with any group in the system. +Administrators can share projects with any group in the system. ### Share a project modal window @@ -61,7 +63,7 @@ To share a project after enabling this feature: 1. Go to your project's page. 1. On the left sidebar, go to **Project information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. -1. (Optional) Select an **Access expiration date**. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. ### Enable or disable modal window **(FREE SELF)** diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index d873f715557..dddd3925dbb 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -105,7 +105,7 @@ Without the approvals, the work cannot merge. Required approvals enable multiple - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. **(ULTIMATE)** -## Related links +## Related topics - [Merge request approvals API](../../../../api/merge_request_approvals.md) - [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 1249aa826fa..f4393b2b76d 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -63,7 +63,7 @@ To edit a merge request approval rule: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**, and then select **Edit**. -1. (Optional) Change the **Rule name**. +1. Optional. Change the **Rule name**. 1. Set the number of required approvals in **Approvals required**. The minimum value is `0`. 1. Add or remove eligible approvers, as needed: - *To add users or groups as approvers,* search for users or groups that are diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 56e93741c1a..a6ca9423df0 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -157,7 +157,7 @@ You can also enforce merge request approval settings: If the settings are inherited by a group or project, they cannot be changed in the group or project that inherited them. -## Related links +## Related topics - [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) - [Compliance report](../../../compliance/compliance_report/index.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index eff3a5bd99e..e59456e5b34 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,7 +40,7 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance). +[Browser Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. @@ -89,7 +89,7 @@ The above example: GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4a2319774ac..15ba6e9de98 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -76,10 +76,10 @@ merge request is from a fork: 1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  -1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. +1. Optional. Select **Start a new merge request** if you're ready to create a merge request. 1. Click **Cherry-pick**. -## Related links +## Related topics - The [Commits API](../../../api/commits.md) enables you to add custom messages to changes you cherry-pick through the API. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 9bfbbd8fc6f..b791bce5749 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -87,7 +87,7 @@ include: The above example creates a `code_quality` job in your CI/CD pipeline which scans your source code for code quality issues. The report is saved as a -[Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -343,7 +343,7 @@ It's possible to have a custom tool provide Code Quality reports in GitLab. To do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the - [Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality). + [Code Quality report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index b615c86288c..bffb66755e0 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -7,15 +7,42 @@ type: reference, howto # Commit message templates **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6. -## Merge commit message template +GitLab uses commit templates to create default messages for specific types of +commits. These templates encourage commit messages to follow a particular format, +or contain specific information. Users can override these templates when merging +a merge request. -As a project maintainer, you're able to configure merge commit message template. It will be used during merge to -create commit message. Template uses similar syntax to +Commit templates use syntax similar to the syntax for [review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -Default merge commit message can be recreated using following template: +## Configure commit templates + +Change the commit templates for your project if the default templates don't +contain the information you need. + +Prerequisite: + +- You must have at least the Maintainer role for a project. + +To do this: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General** and expand **Merge requests**. +1. Depending on the type of template you want to create, scroll to either + [**Merge commit message template**](#default-template-for-merge-commits) or + [**Squash commit message template**](#default-template-for-squash-commits). +1. For your desired commit type, enter your default message. You can use both static + text and [variables](#supported-variables-in-commit-templates). Each template + is limited to a maximum of 500 characters, though after replacing the templates + with data, the final message may be longer. +1. Select **Save changes**. + +## Default template for merge commits + +The default template for merge commit messages is: ```plaintext Merge branch '%{source_branch}' into '%{target_branch}' @@ -27,25 +54,35 @@ Merge branch '%{source_branch}' into '%{target_branch}' See merge request %{reference} ``` -This commit message can be customized to follow any guidelines you might have. -To do so, expand the **Merge requests** tab within your project's **General** -settings and change the **Merge commit message template** text: +## Default template for squash commits + +If you have configured your project to [squash commits on merge](squash_and_merge.md), +GitLab creates a squash commit message with this template: + +```plaintext +%{title} +``` + +## Supported variables in commit templates + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. - +Commit message templates support these variables: -You can use static text and following variables: +| Variable | Description | Output example | +|----------|-------------|----------------| +| `%{source_branch}` | The name of the branch being merged. | `my-feature-branch` | +| `%{target_branch}` | The name of the branch that the changes are applied to. | `main` | +| `%{title}` | Title of the merge request. | `Fix tests and translations` | +| `%{issues}` | String with phrase `Closes <issue numbers>`. Contains all issues mentioned in the merge request description that match [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). Empty if no issues are mentioned. | `Closes #465, #190 and #400` | +| `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | +| `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | +| `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | +| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge Request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | -| Variable | Description | Output example | -|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| -| `%{source_branch}` | The name of the branch that is being merged. | `my-feature-branch` | -| `%{target_branch}` | The name of the branch that the changes are applied to. | `master` | -| `%{title}` | Title of the merge request. | Fix stuff | -| `%{issues}` | String with phrase "Closes <issue numbers>" with all issues mentioned in the MR description matching [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). It will be empty when no issues were mentioned. | `Closes #465, #190 and #400` | -| `%{description}` | Description of the merge request. | Merge request description.<br>Can be multiline. | -| `%{reference}` | Reference to the merge request. | group-name/project-name!72359 | +Empty variables that are the only word in a line are removed, along with all newline characters preceding it. -NOTE: -Empty variables that are the only word in a line will be removed along with all newline characters preceding it. +## Related topics -Merge commit template field has a limit of 500 characters. This limit only applies to the template -itself. +- [Squash and merge](squash_and_merge.md). diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index ff2e6acf123..10c63421876 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -70,7 +70,7 @@ Open a merge request - You are satisfied the problem is resolved in your private fork. - You are ready to make the confidential commits public. -## Related links +## Related topics - [Confidential issues](../issues/confidential_issues.md) - [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 918f9830edc..220049d9a88 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -21,6 +21,10 @@ You can create a merge request from the list of merge requests. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. +NOTE: +Merge requests are designed around a one-to-one (1:1) branch relationship. Only one open merge request may +be associated with a given target branch at a time. + ## From an issue You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). @@ -155,6 +159,8 @@ branch already exists, the patches are applied on top of it. ## Set the default target project +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58093) in GitLab 13.11. + Merge requests have a source and a target project that are the same, unless forking is involved. Creating a fork of the project can cause either of these scenarios when you create a new merge request: diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 006e6d4a8aa..323b7505190 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -88,7 +88,7 @@ Choose an assignee to designate someone as the person responsible for the first [review of the merge request](reviews/index.md). Open the drop down box to search for the user you wish to assign, and the merge request is added to their -[assigned merge request list](../../search/index.md#issues-and-merge-requests). +[assigned merge request list](../../search/index.md#search-issues-and-merge-requests). #### Multiple assignees **(PREMIUM)** @@ -136,10 +136,18 @@ To learn more, read [Review a merge request](reviews/index.md). ### Merge requests to close issues -If the merge request is being created to resolve an issue, you can -add a note in the description which sets it to -[automatically close the issue](../issues/managing_issues.md#closing-issues-automatically) -when merged. +To create a merge request to close an issue when it's merged, you can either: + +- [Add a note in the MR description](../issues/managing_issues.md#closing-issues-automatically). +- In the issue, select **Create a merge request**. Then, you can either: + + - Create a new branch and [a draft merge request](../merge_requests/drafts.md) + in one action. The branch is named `issuenumber-title` by default, but you can + choose any name, and GitLab verifies that it's not already in use. The merge request + inherits the milestone and labels of the issue, and is set to automatically + close the issue when it is merged. + - Create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) + only, with its name starting with the issue number. If the issue is [confidential](../issues/confidential_issues.md), you may want to use a different workflow for diff --git a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png Binary files differdeleted file mode 100644 index f18ca640d38..00000000000 --- a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 54b97eb5732..8222d696853 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -74,7 +74,7 @@ change and whether you need access to a development environment: If you decide to permanently stop work on a merge request, GitLab recommends you close the merge request rather than -[delete it](#delete-a-merge-request). Users with +[delete it](#delete-a-merge-request). The author and assignees of a merge request, and users with Developer, Maintainer, or Owner [roles](../../permissions.md) in a project can close merge requests in the project: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 1d892a3c2e1..7b157aa94d8 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). +[Load Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). +as a [Load Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. @@ -161,7 +161,7 @@ such as: ``http.get(`${__ENV.ENVIRONMENT_URL}`)``. For example: 1. In the `review` job: - 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. + 1. Capture the dynamic URL and save it into a `.env` file, for example, `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. 1. Set the `.env` file to be a [job artifact](../../../ci/pipelines/job_artifacts.md#job-artifacts). 1. In the `load_performance` job: 1. Set it to depend on the review job, so it inherits the environment file. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 597dcb3dfb9..c34a8116625 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -43,7 +43,7 @@ To start your review: - **Add to review**: Keep this comment private and add to the current review. These review comments are marked **Pending** and are visible only to you. - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. -1. (Optional) You can use [quick actions](../../quick_actions.md) inside review comments. +1. Optional. You can use [quick actions](../../quick_actions.md) inside review comments. The comment shows the actions to perform after publication, but does not perform them until you submit your review. 1. When your review is complete, you can [submit the review](#submit-a-review). Your comments @@ -72,7 +72,7 @@ When you submit your review, GitLab: ### Resolve or unresolve thread with a comment -Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread). When replying to a comment, a checkbox is displayed to resolve or unresolve the thread after publication. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 7bfb8e52279..c25b9e15974 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -144,6 +144,6 @@ to your branch to address your reviewers' requests. WARNING: Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. -## Related links +## Related topics - [Suggestions API](../../../../api/suggestions.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index c3fc2fa871f..3fe82fb8ef3 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -29,11 +29,9 @@ The squashed commit in this example is followed by a merge commit, because the m **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. The squashed commit's default commit message is taken from the merge request title. +You can [edit the default message for squash commits](commit_templates.md). -NOTE: -This only takes effect if there are at least 2 commits. As there is nothing to squash, the commit message does not change if there is only 1 commit. - -It can be customized before merging a merge request. +It can also be customized before merging a merge request.  @@ -126,6 +124,10 @@ NOTE: If your project is set to **Do not allow** Squash and Merge, the users still have the option to squash commits locally through the command line and force-push to their remote branch before merging. +## Related topics + +- [Commit message templates](commit_templates.md). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 08b82462187..f5ebfb3668c 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -181,6 +181,6 @@ You should: - Check the [GitLab status page](https://status.gitlab.com/) if the problem persists, to see if there is a wider outage. -## Related links +## Related topics - [External status checks API](../../../api/status_checks.md) diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index b36510c2df8..1f84964c619 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -29,7 +29,7 @@ between pipeline completion and the visualization loading on the page. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/yaml/index.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/artifacts_reports.md#artifactsreportscobertura). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -52,10 +52,15 @@ from any job in any stage in the pipeline. The coverage displays for each line: Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. -NOTE: +### Limits + A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds 100 nodes, there can be mismatches or no matches in the merge request diff view. +A single Cobertura XML file can be no more than 10MiB. For large projects, split the Cobertura XML into +smaller files. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328772) for more details. +When submitting many files, it can take a few minutes for coverage to show on a merge request. + ### Artifact expiration By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 3922ee4d770..796ffc7866c 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -2,10 +2,9 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts --- -# Merge requests versions +# Merge requests versions **(FREE)** Every time you push to a branch that is tied to a merge request, a new version of merge request diff is created. When you visit a merge request that contains diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 3f7d5b6aac1..fb61e123faf 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -119,7 +119,7 @@ Every issue and merge request can be assigned a milestone. The milestones are vi ### Filtering in list pages -From the project and group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group and project milestones. +From the project and group issue/merge request list pages, you can [filter](../../search/index.md#search-issues-and-merge-requests) by both group and project milestones. ### Filtering in issue boards diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 410fdab15e7..165131d50a4 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -36,12 +36,15 @@ for the most popular hosting services: - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) - [cPanel](https://documentation.cpanel.net/display/84Docs/Edit+DNS+Zone) +- [DigitalOcean](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/) - [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) +- [Gandi](https://docs.gandi.net/en/domain_names/faq/dns_records.html) - [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) - [Hostgator](https://www.hostgator.com/help/article/changing-dns-records) - [Inmotion hosting](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) - [Microsoft](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/bb727018(v=technet.10)) +- [Namecheap](https://www.namecheap.com/support/knowledgebase/subcategory/2237/host-records-setup/) <!-- vale gitlab.Spelling = YES --> 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 ee4320d5ea1..ec66dce41f9 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 @@ -25,7 +25,8 @@ and steps below. (`*.gitlab.io`, for GitLab.com). - A custom domain name `example.com` or subdomain `subdomain.example.com`. - Access to your domain's server control panel to set up DNS records: - - A DNS A or CNAME record pointing your domain to GitLab Pages server. + - A DNS record (`A`, `ALIAS`, or `CNAME`) pointing your domain to the GitLab Pages server. If + there are multiple DNS records on that name, you must use an `ALIAS` record. - A DNS `TXT` record to verify your domain's ownership. - Set either `external_http` or `external_https` in `/etc/gitlab/gitlab.rb` to the IP and port of your [Pages Daemon](../../../../administration/pages/index.md#overview). @@ -109,15 +110,15 @@ as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-re Subdomains (`subdomain.example.com`) require: -- A DNS [CNAME record](dns_concepts.md#cname-record) pointing your subdomain to the Pages server. +- A DNS [`ALIAS` or `CNAME` record](dns_concepts.md#cname-record) pointing your subdomain to the Pages server. - A DNS [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. -| From | DNS Record | To | -| ------------------------------------------------------- | ---------- | --------------------- | -| `subdomain.example.com` | CNAME | `namespace.gitlab.io` | -| `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| From | DNS Record | To | +|:--------------------------------------------------------|:----------------|:----------------------| +| `subdomain.example.com` | `ALIAS`/`CNAME` | `namespace.gitlab.io` | +| `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -Note that, whether it's a user or a project website, the `CNAME` +Note that, whether it's a user or a project website, the DNS record should point to your Pages domain (`namespace.gitlab.io`), without any `/project-name`. @@ -130,8 +131,8 @@ domain to the same website, for instance, `example.com` and `www.example.com`. They require: -- A DNS A record for the domain. -- A DNS CNAME record for the subdomain. +- A DNS `A` record for the domain. +- A DNS `ALIAS`/`CNAME` record for the subdomain. - A DNS `TXT` record for each. | From | DNS Record | To | @@ -147,7 +148,7 @@ If you're using Cloudflare, check > **Notes**: > -> - **Do not** use a CNAME record if you want to point your +> - **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. For example, don't point `subdomain.domain.com` to @@ -231,7 +232,7 @@ If you use Cloudflare, you can redirect `www` to `domain.com` without adding both `www.domain.com` and `domain.com` to GitLab. To do so, you can use Cloudflare's page rules associated to a -CNAME record to redirect `www.domain.com` to `domain.com`. You +`CNAME` record to redirect `www.domain.com` to `domain.com`. You can use the following setup: 1. In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`. 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 ee1004a3416..75fc407ce3f 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 @@ -67,7 +67,7 @@ associated Pages domain. GitLab also renews it automatically. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30146) in GitLab 13.0. -If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visbility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: +If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: 1. Go to your project's **Settings > Pages**. 1. Click **Edit** on your domain. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 386ed566225..b43af2f0efe 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -18,9 +18,9 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. -1. Click the name of the project you want to [fork](../../../../user/project/working_with_projects.md#fork-a-project). -1. In the top right, click the **Fork** button, and then choose a namespace to fork to. -1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. +1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork). +1. In the top right, select **Fork** and then choose a namespace to fork to. +1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. GitLab CI/CD builds and deploys your site. The site can take approximately 30 minutes to deploy. @@ -31,13 +31,13 @@ that immediately publishes your changes to the Pages site. You can take some **optional** further steps: -- _Remove the fork relationship._ If you want to contribute to the project you forked from, +- Remove the fork relationship. If you want to contribute to the project you forked from, you can keep this relationship. Otherwise, go to your project's **Settings > General**, expand **Advanced settings**, and scroll down to **Remove fork relationship**:  -- _Change the URL to match your namespace._ If your Pages site is hosted on GitLab.com, +- Change the URL to match your namespace. If your Pages site is hosted on GitLab.com, you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace (the one you chose when you forked the project). diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index eb5f3a1bbf0..e0c10e27ec3 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -27,7 +27,7 @@ To create a GitLab Pages website: ## Prerequisites -You must have a [blank project](../../working_with_projects.md#blank-projects) in GitLab. +You must have a [blank project](../../working_with_projects.md#create-a-blank-project) in GitLab. ## Create the project files diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 978e35b3a9f..1f60aafe71b 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,165 +1,9 @@ --- -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 -description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." +redirect_to: 'custom_domains_ssl_tls_certification/lets_encrypt_integration.md' +remove_date: '2022-03-14' --- -# Let's Encrypt for GitLab Pages (manual process, deprecated) **(FREE)** +This file was moved to [another location](custom_domains_ssl_tls_certification/lets_encrypt_integration.md). -WARNING: -This method is still valid but was **deprecated** in favor of the -[Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) -introduced in GitLab 12.1. - -If you have a GitLab Pages website served under your own domain, -you might want to secure it with a SSL/TLS certificate. - -[Let's Encrypt](https://letsencrypt.org) is a free, automated, and -open source Certificate Authority. - -## Requirements - -To follow along with this tutorial, we assume you already have: - -- [Created a project](index.md#getting-started) in GitLab - containing your website's source code. -- Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) - pointing it to your Pages website. -- [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps) - and verified your ownership. -- Cloned your project into your computer. -- Your website up and running, served under HTTP protocol at `http://example.com`. - -## Obtaining a Let's Encrypt certificate - -Once you have the requirements addressed, follow the instructions -below to learn how to obtain the certificate. - -Note that these instructions were tested on macOS Mojave. For other operating systems the steps -might be slightly different. Follow the -[CertBot instructions](https://certbot.eff.org/) according to your OS. - -1. On your computer, open a terminal and navigate to your repository's - root directory: - - ```shell - cd path/to/dir - ``` - -1. Install CertBot (the tool Let's Encrypt uses to issue certificates): - - ```shell - brew install certbot - ``` - -1. Request a certificate for your domain (`example.com`) and - provide an email account (`your@email.com`) to receive notifications: - - ```shell - sudo certbot certonly -a manual -d example.com --email your@email.com - ``` - - Alternatively, you can register without adding an email account, - but you aren't notified about the certificate expiration's date: - - ```shell - sudo certbot certonly -a manual -d example.com --register-unsafely-without-email - ``` - - NOTE: - Read through CertBot's documentation on their - [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). - -1. You're prompted with a message to agree with their terms. - Press `A` to agree and `Y` to let they log your IP. - - CertBot then prompts you with the following message: - - ```shell - Create a file containing just this data: - - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - - And make it available on your web server at this URL: - - http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP - - Press Enter to Continue - ``` - -1. **Do not press Enter yet.** Let's Encrypt needs to verify your - domain ownership before issuing the certificate. To do so, create 3 - consecutive directories under your website's root: - `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` - and add to the last folder an `index.html` file containing the content - referred on the previous prompt message: - - ```shell - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - ``` - - Note that this file needs to be accessed under - `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` - to allow Let's Encrypt to verify the ownership of your domain, - therefore, it needs to be part of the website content under the - repository's [`public`](index.md#how-it-works) folder. - -1. Add, commit, and push the file into your repository in GitLab. Once the pipeline - passes, press **Enter** on your terminal to continue issuing your - certificate. CertBot then prompts you with the following message: - - ```shell - Waiting for verification... - Cleaning up challenges - - IMPORTANT NOTES: - - Congratulations! Your certificate and chain have been saved at: - /etc/letsencrypt/live/example.com/fullchain.pem - Your key file has been saved at: - /etc/letsencrypt/live/example.com/privkey.pem - Your cert will expire on 2019-03-12. To obtain a new or tweaked - version of this certificate in the future, simply run certbot - again. To non-interactively renew *all* of your certificates, run - "certbot renew" - - If you like Certbot, please consider supporting our work by: - - Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate - Donating to EFF: https://eff.org/donate-le - ``` - -## Add your certificate to GitLab Pages - -Now that your certificate has been issued, let's add it to your Pages site: - -1. Back at GitLab, navigate to your project's **Settings > Pages**, - find your domain and click **Details** and **Edit** to add your certificate. -1. From your terminal, copy and paste the certificate into the first field - **Certificate (PEM)**: - - ```shell - sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy - ``` - -1. Copy and paste the private key into the second field **Key (PEM)**: - - ```shell - sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy - ``` - -1. Click **Save changes** to apply them to your website. -1. Wait a few minutes for the configuration changes to take effect. -1. Visit your website at `https://example.com`. - -To force `https` connections on your site, navigate to your -project's **Settings > Pages** and check **Force HTTPS (requires -valid certificates)**. - -## Renewal - -Let's Encrypt certificates expire every 90 days and you must -renew them periodically. To renew all your certificates at once, run: - -```shell -sudo certbot renew -``` +<!-- This redirect file can be deleted after <2022-03-14>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 3deea92f56e..beafbc86cb5 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -92,7 +92,7 @@ you can explicitly set your own. The following HTTP codes are supported: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. > - Enabled on GitLab.com. -> - Enabled by default in self-managed GitLab behind the [`FF_ENABLE_REDIRECTS` feature flag](#feature-flag-for-redirects). +> - Enabled on self-managed in [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/618). To create a redirect, add a rule that includes a `from` path, a `to` path, and an [HTTP status code](#http-status-codes): @@ -261,36 +261,7 @@ However, there are some minor differences: literal `:placeholder`). - GitLab redirects to `/new/`. -## Features behind feature flags - -Some Pages features are behind feature flags. - -### Feature flag for redirects - -FLAG: -Redirects in GitLab Pages is under development, and is deployed behind a feature flag -that is **enabled by default**. - -To disable redirects, for [Omnibus installations](../../../administration/pages/index.md), define the -`FF_ENABLE_REDIRECTS` environment variable in the -[global settings](../../../administration/pages/index.md#global-settings). -Add the following line to `/etc/gitlab/gitlab.rb` and -[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - -```ruby -gitlab_pages['env']['FF_ENABLE_REDIRECTS'] = 'false' -``` - -For [source installations](../../../administration/pages/source.md), define the -`FF_ENABLE_REDIRECTS` environment variable, then -[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): - -```shell -export FF_ENABLE_REDIRECTS="false" -/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf -``` - -### Feature flag for rewrites +## Feature flag for rewrites FLAG: Rewrites in GitLab Pages is under development, and is deployed behind a feature flag diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index a4d7b94506b..75a5a2a6a4f 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -35,7 +35,7 @@ If you manually enter a parameter, it must be enclosed in double quotation marks - ASCII letters - Numbers (0-9) -- Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`) +- Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), ampersand (`&`) or at (`@`) Parameters are case-sensitive. Autocomplete handles this, and the insertion of quotation marks, automatically. @@ -45,14 +45,15 @@ of quotation marks, automatically. The following quick actions are applicable to descriptions, discussions, and threads. Some quick actions might not be available to all subscription tiers. +<!-- Keep this table sorted alphabetically --> + | Command | Issue | Merge request | Epic | Action | |:--------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/add_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | -| `/assign @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user. | -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | -| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user as a reviewer. | -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users as reviewers. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | | `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | | `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | | `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | @@ -81,11 +82,12 @@ threads. Some quick actions might not be available to all subscription tiers. | `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | -| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | +| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | | `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | | `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/remove_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | | `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | | `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | diff --git a/doc/user/project/releases/img/feature_count_v14_6.png b/doc/user/project/releases/img/feature_count_v14_6.png Binary files differnew file mode 100644 index 00000000000..0b1a0552631 --- /dev/null +++ b/doc/user/project/releases/img/feature_count_v14_6.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index abedae5d10b..239e6c9cea8 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Release group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -9,26 +8,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. -To introduce a checkpoint in your source code history, you can assign a -[Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) at the moment of release. -However, in most cases, your users need more than just the raw source code. -They need compiled objects or other assets output by your CI/CD system. +In GitLab, a release enables you to create a snapshot of your project for your users, including +installation packages and release notes. You can create a GitLab release on any branch. Creating a +release also creates a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to mark the +release point in the source code. -A GitLab Release can be: +WARNING: +Deleting a Git tag associated with a release also deletes the release. + +A release can include: - A snapshot of the source code of your repository. - [Generic packages](../../packages/generic_packages/index.md) created from job artifacts. - Other metadata associated with a released version of your code. +- Release notes. -You can create a GitLab release on any branch. When you create a release: +When you [create a release](#create-a-release): - GitLab automatically archives source code and associates it with the release. - GitLab automatically creates a JSON file that lists everything in the release, so you can compare and audit releases. This file is called [release evidence](#release-evidence). -- You can add release notes and a message for the tag associated with the release. -After you create a release, you can [associate milestones with it](#associate-milestones-with-a-release), -and attach [release assets](#release-assets), like runbooks or packages. +When you create a release, or after, you can: + +- Add release notes. +- Add a message for the Git tag associated with the release. +- [Associate milestones with it](#associate-milestones-with-a-release). +- Attach [release assets](#release-assets), like runbooks or packages. ## View releases @@ -46,49 +52,84 @@ To view a list of releases: - On private projects, this number is visible to users with Reporter [permissions](../../permissions.md#project-members-permissions) or higher. -### Sort Releases +### Sort releases -On the top right of the **Releases** page, you can use the sorting button to order releases by -**Released date** or **Created date**. You can sort releases in ascending or descending order. +To sort releases by **Released date** or **Created date**, select from the sort order dropdown. To +switch between ascending or descending order, select **Sort order**. - + ## Create a release > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. -You can create a release in the user interface, or by using the -[Releases API](../../../api/releases/index.md#create-a-release). -We recommend using the API to create releases as one of the last steps in your -CI/CD pipeline. +You can create a release: -Only users with at least the Developer role can create releases. -Read more about [Release permissions](#release-permissions). +- [Using a job in your CI/CD pipeline](#create-a-release-by-using-a-cicd-job). +- [In the Releases page](#create-a-release-in-the-releases-page). +- [In the Tags page](#create-a-release-in-the-tags-page). +- Using the [Releases API](../../../api/releases/index.md#create-a-release). + +We recommend creating a release as one of the last steps in your CI/CD pipeline. + +Prerequisites: + +- You must have at least the Developer role for a project. For more information, read +[Release permissions](#release-permissions). + +### Create a release in the Releases page -To create a new release through the GitLab UI: +To create a release in the Releases page: +1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases** and select **New release**. -1. Open the [**Tag name**](#tag-name) dropdown. Select an existing tag or type - in a new tag name. Selecting an existing tag that is already associated with - a release will result in a validation error. -1. If creating a new tag, open the **Create from** dropdown. Select a - branch, tag, or commit SHA to use when creating the new tag. -1. Optionally, fill out any additional information about the release, such as its - [title](#title), [milestones](#associate-milestones-with-a-release), - [release notes](#release-notes-description), or [assets links](#links). -1. Click **Create release**. - -## Create a release by using a CI/CD job +1. From the [**Tag name**](#tag-name) dropdown, either: + - Select an existing Git tag. Selecting an existing tag that is already associated with a release + results in a validation error. + - Enter a new Git tag name. + 1. From the **Create from** dropdown, select a branch or commit SHA to use when creating the + new tag. +1. Optional. Enter additional information about the release, including: + - [Title](#title). + - [Milestones](#associate-milestones-with-a-release). + - [Release notes](#release-notes-description). + - [Asset links](#links). +1. Select **Create release**. + +### Create a release in the Tags page + +To create a release in the Tags page, add release notes to either an existing or a new Git tag. + +To add release notes to a new Git tag: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Select **New tag**. +1. Optional. Enter a tag message in the **Message** text box. +1. In the **Release notes** text box, enter the release's description. + You can use Markdown and drag and drop files to this text box. +1. Select **Create tag**. + +To edit release notes of an existing Git tag: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Select **Edit release notes** (**{pencil}**). +1. In the **Release notes** text box, enter the release's description. + You can use Markdown and drag and drop files to this text box. +1. Select **Save changes**. + +### Create a release by using a CI/CD job > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. You can create a release directly as part of the GitLab CI/CD pipeline -by using [the `release` keyword](../../../ci/yaml/index.md#release) in the job definition. +by using the [`release` keyword](../../../ci/yaml/index.md#release) in the job definition. -The release is created only if the job processes without error. If the Rails API returns an error -during release creation, the release job fails. +The release is created only if the job processes without error. If the API returns an error during +release creation, the release job fails. -### CI/CD example of the `release` keyword +#### CI/CD example of the `release` keyword To create a release when you push a Git tag, or when you add a Git tag in the UI by going to **Repository > Tags**: @@ -100,7 +141,7 @@ release_job: rules: - if: $CI_COMMIT_TAG # Run this job when a tag is created manually script: - - echo 'running release_job' + - echo "running release_job" release: name: 'Release $CI_COMMIT_TAG' description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined @@ -149,7 +190,7 @@ release_job: when: never # Do not run this job when a tag is created manually - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch script: - - echo 'running release_job for $TAG' + - echo "running release_job for $TAG" release: name: 'Release $TAG' description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG @@ -207,7 +248,7 @@ which requires the text representation of the certificate. ### `release-cli` command line -The entries under the `release` node are transformed into a `bash` command line and sent +The entries under the `release` node are transformed into Bash commands and sent to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). You can also call the `release-cli` directly from a `script` entry. @@ -224,14 +265,14 @@ A pipeline can have multiple `release` jobs, for example: ```yaml ios-release: script: - - echo 'iOS release job' + - echo "iOS release job" release: tag_name: v1.0.0-ios description: 'iOS release v1.0.0' android-release: script: - - echo 'Android release job' + - echo "Android release job" release: tag_name: v1.0.0-android description: 'Android release v1.0.0' @@ -255,7 +296,8 @@ release tag. When the `released_at` date and time has passed, the badge is autom ## Edit a release -> [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. +> - Asset link editing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. Only users with at least the Developer role can edit releases. Read more about [Release permissions](#release-permissions). @@ -271,29 +313,6 @@ You can edit the release title, notes, associated milestones, and asset links. To change the release date use the [Releases API](../../../api/releases/index.md#update-a-release). -## Add release notes to Git tags - -If you have an existing Git tag, you can add release notes to it. - -You can do this in the user interface, or by using the [Releases API](../../../api/releases/index.md). -We recommend using the API to add release notes as one of the last steps in your CI/CD release pipeline. - -In the interface, to add release notes to a new Git tag: - -1. Navigate to your project's **Repository > Tags**. -1. Click **New tag**. -1. In the **Release notes** field, enter the release's description. - You can use Markdown and drag and drop files to this field. -1. Click **Create tag**. - -In the interface, to add release notes to an existing Git tag: - -1. Navigate to your project's **Repository > Tags**. -1. Click **Edit release notes** (the pencil icon). -1. In the **Release notes** field, enter the release's description. - You can use Markdown in this field, and drag and drop files to it. -1. Click **Save changes**. - ## Associate milestones with a release > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29020) in GitLab 12.5. @@ -325,6 +344,11 @@ Here is an example of milestones with no releases, one release, and two releases  +NOTE: +A subgroup's project releases cannot be associated with a supergroup's milestone. To learn +more, read issue #328054, +[Releases cannot be associated with a supergroup milestone](https://gitlab.com/gitlab-org/gitlab/-/issues/328054). + ## Get notified when a release is created > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26001) in GitLab 12.4. @@ -576,6 +600,29 @@ links to a release is not recommended, because artifacts are ephemeral and are used to pass data in the same pipeline. This means there's a risk that they could either expire or someone might manually delete them. +#### Number of new and total features **(FREE SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235618) in GitLab 13.5. + +On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view the number of new and total features in the project. + + + +The totals are displayed on [shields](https://shields.io/) and are generated per release by +[a Rake task in the `www-gitlab-com` repo](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). + +| Item | Formula | +| ------ | ------ | +| `New features` | Total count of release posts across all tiers for a single release in the project. | +| `Total features` | Total count of release posts in reverse order for all releases in the project. | + +The counts are also shown by license tier. + +| Item | Formula | +| ------ | ------ | +| `New features` | Total count of release posts across a single tier for a single release in the project. | +| `Total features` | Total count of release posts across a single tier in reverse order for all releases in the project. | + ## Release evidence > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. @@ -776,7 +823,7 @@ You can copy the example project to your own group or instance for testing. More ### Getting `403 Forbidden` or `Something went wrong while creating a new release` errors when creating, updating or deleting releases and their assets -If the release is associted with a [protected tag](../protected_tags.md), +If the release is associated with a [protected tag](../protected_tags.md), the UI/API request might result in an authorization failure. Make sure that the user or a service/bot account is allowed to [create the protected tag](../protected_tags.md#configuring-protected-tags) too. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index c23ceaa1aba..b55f0b0a734 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,11 +1,10 @@ --- -type: reference, howto stage: Release group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install the `release-cli` for the Shell executor +# Install the `release-cli` for the Shell executor **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. > - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages). diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index bc6bc799670..65b7c4a9881 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -41,7 +41,7 @@ To update the default branch name for an individual [project](../../index.md): 1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. -1. (Optional) Select the **Auto-close referenced issues on default branch** checkbox to close +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**. @@ -134,7 +134,7 @@ renames a Git repository's (`example`) default branch. [change the default branch for this project](#change-the-default-branch-name-for-a-project). Select `main` as your new default branch. 1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). -1. (Optional) If you want to delete the old default branch: +1. Optional. If you want to delete the old default branch: 1. Verify that nothing is pointing to it. 1. Delete the branch on the remote: diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index bf4ef21e31b..1ab21286a8e 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -26,17 +26,17 @@ To fork an existing project in GitLab: 1. Select the project to fork to: - - *(Recommended method)* Below **Select a namespace to fork the project**, identify + - Recommended method. Below **Select a namespace to fork the project**, identify the project you want to fork to, and click **Select**. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown.  - - *(Experimental method)* If your GitLab administrator has + - Experimental method. If your GitLab administrator has [enabled the experimental fork project form](#enable-or-disable-the-fork-project-form), read [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). - Only namespaces you have Developer and higher - [permissions](../../permissions.md) for are shown. + Only namespaces you have at least the Developer + [role](../../permissions.md) for are shown. NOTE: The project path must be unique in the namespace. @@ -101,7 +101,7 @@ To use it, follow the instructions at [Creating a fork](#creating-a-fork) and pr - The project name. - The project URL. - The project slug. -- *(Optional)* The project description. +- Optional. The project description. - The visibility level for your fork. ### Enable or disable the fork project form **(FREE SELF)** diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 6aa32b1b816..27767f8d325 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -40,7 +40,7 @@ For a commit to be verified by GitLab: account. - One of the emails in the GPG key must match a **verified** email address used by the committer in GitLab. This address will be part of the public key. - If you want to keep this address private, use the automatically generated + If you want to keep this address private, use the automatically generated [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) GitLab provides in your profile. - The committer's email address must match the verified email address from the @@ -54,17 +54,18 @@ started: 1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in the following commands. -1. Generate the private/public key pair with the following command, which will - spawn a series of questions: +1. Generate the private/public key pair with the command appropriate for your version + of `gpg`. This command spawns a series of questions: ```shell + # Use this command for the default version of gpg, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key + + # Use this command for versions of GPG later than 2.1.17: gpg --full-gen-key ``` - NOTE: - In some cases like Gpg4win on Windows and other macOS versions, the command - here may be `gpg --gen-key`. - 1. The first question is which algorithm can be used. Select the kind you want or press <kbd>Enter</kbd> to choose the default (RSA and RSA): @@ -200,7 +201,7 @@ key to use. Replace `30F2B65B9246B6CA` with your GPG key ID. -1. (Optional) If Git is using `gpg` and you get errors like `secret key not available` +1. Optional. If Git is using `gpg` and you get errors like `secret key not available` or `gpg: signing failed: secret key not available`, run the following command to change to `gpg2`: diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index bb1a55f6b2b..54e9470892c 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -248,9 +248,19 @@ When you [rename a user](../../profile/index.md#change-your-username), - The redirects are available as long as the original path is not claimed by another group, user, or project. -## Related links +## Related topics -- [GitLab Workflow VS Code extension](vscode.md) +- [GitLab Workflow VS Code extension](vscode.md). +- To lock files and prevent change conflicts, use [file locking](../file_lock.md). +- [Repository API](../../../api/repositories.md). +- [Find files](file_finder.md) in a repository. +- [Branches](branches/index.md). +- [File templates](web_editor.md#template-dropdowns). +- [Create a directory](web_editor.md#create-a-directory). +- [Start a merge request](web_editor.md#tips). +- [Find file history](git_history.md). +- [Identify changes by line (Git blame)](git_blame.md). +- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). ## Troubleshooting @@ -287,16 +297,3 @@ The same approach should also allow misidentified file types to be fixed. ``` `*.txt` files have an entry in the heuristics file. This example prevents parsing of these files. - -## Related topics - -- To lock files and prevent change conflicts, use [file locking](../file_lock.md). -- [Repository API](../../../api/repositories.md). -- [Find files](file_finder.md) in a repository. -- [Branches](branches/index.md). -- [File templates](web_editor.md#template-dropdowns). -- [Create a directory](web_editor.md#create-a-directory). -- [Start a merge request](web_editor.md#tips). -- [Find file history](git_history.md). -- [Identify changes by line (Git blame)](git_blame.md). -- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). diff --git a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png Binary files differindex bc63322cd65..3dc940c23de 100644 --- a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png +++ b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 8074f311e5f..ba105a970a7 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -175,10 +175,10 @@ request, you can create a new branch upfront.  1. Enter a new **Branch name**. -1. (Optional) Change the **Create from** field to choose which branch, tag, or +1. Optional. Change the **Create from** field to choose which branch, tag, or commit SHA this new branch originates from. This field autocompletes if you start typing an existing branch or tag. -1. Click **Create branch** to return to the file browser on this new branch. +1. To return to the file browser on this new branch, select **Create branch**.  @@ -201,10 +201,10 @@ SHA: 1. Give the tag a name such as `v1.0.0`. 1. Choose the branch or SHA from which you want to create this new tag. -1. (Optional) Add a message and release notes. The release notes section supports +1. Optional. Add a message and release notes. The release notes section supports Markdown format. -1. (Optional) Upload an attachment. -1. Click **Create tag**, and GitLab redirects you to the tag list page. +1. Optional. Upload an attachment. +1. Select **Create tag**. GitLab redirects you to the tag list page.  diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 2db7ae308bd..f9d9af3e672 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -290,7 +290,7 @@ To investigate why a commit shows as `Unverified`: 1. The verification status is stored in the database. To display the database record: ```ruby - pp X509CommitSignature.by_commit_sha(commit.sha);nil + pp CommitSignatures::X509CommitSignature.by_commit_sha(commit.sha);nil ``` If all the previous checks returned the correct values: diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 6ee23c91680..294e493dfe9 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -17,6 +17,10 @@ In 14.4, Requirements was moved under **Issues**. With requirements, you can set criteria to check your products against. They can be based on users, stakeholders, system, software, or anything else you find important to capture. +INFO: +Meet your compliance needs with requirements in GitLab. +[Try Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-project-requirements-docs). + A requirement is an artifact in GitLab which describes the specific behavior of your product. Requirements are long-lived and don't disappear unless manually cleared. @@ -134,7 +138,7 @@ You can also sort the requirements list by: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. -GitLab supports [requirements test reports](../../../ci/yaml/index.md#artifactsreportsrequirements) now. +GitLab supports [requirements test reports](../../../ci/yaml/artifacts_reports.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing requirements as Satisfied (you may manually satisfy a requirement in the edit form [edit a requirement](#edit-a-requirement)). diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 4f8e068ca2d..072d685bde4 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -274,7 +274,7 @@ When configured, the custom suffix creates a new Service Desk email address, con For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: -- Project name suffix is set to `support`. +- Email address suffix is set to `support`. - Service Desk email address is configured to `contact+%{key}@example.com`. The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. @@ -289,6 +289,8 @@ In these issues, you can also see our friendly neighborhood [Support Bot](#suppo ### As an end user (issue creator) +> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. +> In earlier versions, the Service Desk email address had to be in the "To" field. To create a Service Desk issue, an end user does not need to know anything about the GitLab instance. They just send an email to the address they are given, and receive an email back confirming receipt: @@ -304,6 +306,9 @@ are sent as emails: Any responses they send via email are displayed in the issue itself. +For information about headers used for treating email, see +[the incoming email documentation](../../administration/incoming_email.md#accepted-headers). + ### As a responder to the issue For responders to the issue, everything works just like other GitLab issues. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 74879dae2d6..da0336d01ff 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -44,8 +44,9 @@ Note the following: a maintainer or administrator role in the group where the exported project lives. - Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. - Additionally, the user must be an existing member of the namespace, or the user can be added as a -member of the project for contributions to be mapped. + The public email is not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) + for mapping to work correctly. Additionally, the user must be an existing member of the namespace, + or the user can be added as a member of the project for contributions to be mapped. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. - For project migration imports performed over GitLab.com Groups, preserving author information is diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 5c4d4649240..c6cbd45a6ab 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -7,18 +7,18 @@ type: reference, index, howto # Project settings **(FREE)** -NOTE: -Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) -to access project settings. - The **Settings** page in GitLab provides a centralized home for your [project](../index.md) configuration options. To access it, go to your project's homepage -and, in the left navigation menu, clicking **Settings**. To reduce complexity, settings are -grouped by topic into sections. To display all settings in a section, click **Expand**. +and, in the left navigation menu, select **Settings**. To reduce complexity, settings are +grouped by topic into sections. To display all settings in a section, select **Expand**. In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epics/4842), GitLab displays a search box to help you find the settings you want to view. +NOTE: +Only users who have the [Maintainer role](../../permissions.md) for the project and administrators can +access project settings. + ## General settings Under a project's general settings, you can find everything concerning the @@ -315,7 +315,7 @@ Set up your project's merge request settings: - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -- Configure [merge commit message template](../merge_requests/commit_templates.md). +- Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk @@ -449,17 +449,22 @@ To delete a project: This action deletes a project including all associated resources (issues, merge requests, and so on). -In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) and later, on Premium or higher tiers, -group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects in a group -to be deleted after a delayed period. -When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). - WARNING: -The default behavior of [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to -[Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +The default deletion behavior for projects was changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) +in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. + +#### Delayed project deletion **(PREMIUM)** + +Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether +delayed project deletion is enabled for a particular project: + +- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion). + You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the + delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). +- Group [settings](../../group/index.md#enable-delayed-project-deletion) to enabled delayed project deletion for all + projects in the group. -#### Delete a project immediately **(PREMIUM)** +##### Delete a project immediately > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 85e412e7a41..44ece6cb172 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -12,111 +12,91 @@ type: reference, howto > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. -Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md) -except they are attached to a project rather than a user. They can be used to: +You can use a project access token to authenticate: -- Authenticate with the [GitLab API](../../../api/index.md#personalproject-access-tokens). -- Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when - authenticating, you can use any non-empty value because only the token is needed. +- With the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- With Git, when using HTTP Basic Authentication. -Project access tokens: +After you configure a project access token, you don't need a password when you authenticate. +Instead, you can enter any non-blank value. -- Expire on the date you define, at midnight UTC. -- Are supported for self-managed instances on Free tier and above. Free self-managed instances - should: - - Review their security and compliance policies with regards to +Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md), +except they are associated with a project rather than a user. + +You can use project access tokens: + +- On GitLab SaaS if you have the Premium license tier or higher. Personal access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab, with any license tier. If you have the Free tier: + - Review your security and compliance policies around [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. -- Are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/).) -For examples of how you can use a project access token to authenticate with the API, see the -[relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens). +Project access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) +configured for personal access tokens. -NOTE: -For GitLab.com and self-managed instances, the default prefix is `glpat-`. +## Create a project access token -## Creating a project access token +To create a project access token: -1. Log in to GitLab. -1. Navigate to the project you would like to create an access token for. -1. In the **Settings** menu choose **Access Tokens**. -1. Choose a name and optional expiry date for the token. -1. Choose a role for the token. -1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token). -1. Click the **Create project access token** button. -1. Save the project access token somewhere safe. Once you leave or refresh - the page, you don't have access to it again. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Enter a name. +1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. +1. Select a role for the token. +1. Select the [desired scopes](#scopes-for-a-project-access-token). +1. Select **Create project access token**. -## Project bot users +A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can't view it again. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. -> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. +## Revoke a project access token -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. +To revoke a project access token: -For each project access token created, a bot user is created and added to the project with -the [specified level permissions](../../permissions.md#project-members-permissions). - -For the bot: - -- The name is set to the name of the token. -- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. -- The email is set to `project{project_id}_bot@example.com`, for example `project123_bot@example.com`. -- For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`, for example `project_123_bot1`. -- For additional acess tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`, for example `project123_bot1@example.com` - -API calls made with a project access token are associated with the corresponding bot user. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Next to the project access token to revoke, select **Revoke**. -These bot users are included in a project's **Project information > Members** list but cannot be modified. Also, a bot -user cannot be added to any other project. +## Scopes for a project access token -When the project access token is [revoked](#revoking-a-project-access-token), the bot user is deleted -and all records are moved to a system-wide user with the username "Ghost User". For more -information, see [Associated Records](../../profile/account/delete_account.md#associated-records). +The scope determines the actions you can perform when you authenticate with a project access token. -## Revoking a project access token - -At any time, you can revoke any project access token by clicking the -respective **Revoke** button in **Settings > Access Tokens**. - -## Limiting scopes of a project access token - -Project access tokens can be created with one or more scopes that allow various -actions that a given token can perform. The available scopes are depicted in -the following table. - -| Scope | Description | -| ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | -| `read_repository` | Allows read-only access (pull) to the repository. | -| `write_repository` | Allows read-write access (pull, push) to the repository. | +| Scope | Description | +|:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_registry` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | +| `read_repository` | Allows read access (pull) to the repository. | +| `write_repository` | Allows read and write access (pull and push) to the repository. | ## Enable or disable project access token creation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287707) in GitLab 13.11. -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. +To enable or disable project access token creation for all projects in a top-level group: -## Group access token workaround **(FREE SELF)** +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions, LFS, 2FA**. +1. Under **Permissions**, turn on or off **Allow project access token creation**. -NOTE: -This section describes a workaround and is subject to change. +Even when creation is disabled, you can still use and revoke existing project access tokens. + +## Group access tokens **(FREE SELF)** -Group access tokens let you use a single token to: +With group access tokens, you can use a single token to: -- Perform actions at the group level. +- Perform actions for groups. - Manage the projects within the group. -- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate - with Git over HTTPS. +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. + +NOTE: +You cannot use the UI to create a group access token. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) +to add this functionality. This section describes a workaround. -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). +If you are an administrator of a self-managed GitLab instance, you can create a group access token in the +[Rails console](../../../administration/operations/rails_console.md). <div class="video-fallback"> For a demo of the group access token workaround, see <a href="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>. @@ -127,37 +107,83 @@ administrators can create them using the [Rails console](../../../administration ### Create a group access token -To create a group access token, run the following in a Rails console: +To create a group access token: -```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 -``` +1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): + + ```ruby + # Set the GitLab administration user to use. If user ID 1 is not available or is not an adinistrator, use 'admin = User.admins.first' instead to select an admininistrator. + admin = User.find(1) + + # Set the group group you want to create a token for. For example, group with ID 109. + group = Group.find(109) + + # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. + bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute + + # Confirm the group bot. + bot.confirm + + # Add the bot to the group with the required role. + group.add_user(bot, :maintainer) -Test if the generated group access token works: + # Give the bot a personal access token. + token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') -1. Pass the group access token in the `PRIVATE-TOKEN` header to GitLab REST APIs. For example: + # Get the token value. + gtoken = token.token + ``` - - [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. Test if the generated group access token works: -1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) - using HTTPS. + 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: + + - [Create an epic](../../../api/epics.md#new-epic) in the group. + - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. + - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. + + 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) + using HTTPS. ### Revoke a group access token -To revoke a group access token, run the following in a Rails console: +To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): ```ruby bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke token = bot.personal_access_tokens.last # the token you want to revoke token.revoke! ``` + +## Project bot users + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. +> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. + +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). +Each time you create a project access token, a bot user is created and added to the project. +These bot users do not count as licensed seats. + +The bot users have [permissions](../../permissions.md#project-members-permissions) that correspond with the +selected role and [scope](#scopes-for-a-project-access-token) of the project access token. + +- The name is set to the name of the token. +- The username is set to `project_{project_id}_bot` for the first access token. For example, `project_123_bot`. +- The email is set to `project{project_id}_bot@example.com`. For example, `project123_bot@example.com`. +- For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`. For + example, `project_123_bot1`. +- For additional access tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`. + For example, `project123_bot1@example.com`. + +API calls made with a project access token are associated with the corresponding bot user. + +Bot users: + +- Are included in a project's member list but cannot be modified. +- Cannot be added to any other project. + +When the project access token is [revoked](#revoke-a-project-access-token): + +- The bot user is deleted. +- All records are moved to a system-wide user with the username `Ghost User`. For more information, see + [associated records](../../profile/account/delete_account.md#associated-records). diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 431250a817d..50b1a3a929d 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -72,11 +72,11 @@ First, set up the project. Once done, you can use the Static Site Editor to 1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) - or [create a new project from a template](../working_with_projects.md#built-in-templates). + or [create a new project from a template](../working_with_projects.md#create-a-project-from-a-built-in-template). 1. Edit the [`data/config.yml`](#static-site-generator-configuration) configuration file to replace `<username>` and `<project-name>` with the proper values for your project's path. -1. (Optional) Edit the [`.gitlab/static-site-editor.yml`](#static-site-editor-configuration-file) file +1. Optional. Edit the [`.gitlab/static-site-editor.yml`](#static-site-editor-configuration-file) file to customize the behavior of the Static Site Editor. 1. When you submit your changes, GitLab triggers a CI/CD pipeline to deploy your project with GitLab Pages. 1. When the pipeline finishes, from your project's left-side menu, go to **Settings > Pages** to find the URL of your new website. @@ -96,15 +96,15 @@ After setting up your project, you can start editing content directly from the S To edit a file: 1. Visit the page you want to edit. -1. Click the **Edit this page** button. +1. Select **Edit this page**. 1. The file is opened in the Static Site Editor in **WYSIWYG** mode. If you wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request, to submit +1. Optional. Adjust the default title and description of the merge request, to submit with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#create-a-merge-request-template) from the dropdown menu and edit it accordingly. -1. Click **Submit changes**. +1. Select **Submit changes**. 1. A new merge request is automatically created and you can assign a colleague for review. ### Text @@ -123,11 +123,11 @@ The Static Site Editors supports Markdown files (`.md`, `.md.erb`) for editing t You can upload image files via the WYSIWYG editor directly to the repository to default upload directory `source/images`. To do so: -1. Click the image icon (**{doc-image}**). -1. Choose the **Upload file** tab. -1. Click **Choose file** to select a file from your computer. -1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). -1. Click **Insert image**. +1. Select the image icon (**{doc-image}**). +1. Select the **Upload file** tab. +1. To select a file from your computer, select **Choose file**. +1. Optional. Add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Select **Insert image**. The selected file can be any supported image file (`.png`, `.jpg`, `.jpeg`, `.gif`). The editor renders thumbnail previews so you can verify the correct image is included and there aren't any references to @@ -137,11 +137,11 @@ missing images. You can also link to an image if you'd like: -1. Click the image icon (**{doc-image}**). -1. Choose the **Link to an image** tab. +1. Select the image icon (**{doc-image}**). +1. Select the **Link to an image** tab. 1. Add the link to the image into the **Image URL** field (use the full path; relative paths are not supported yet). -1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). -1. Click **Insert image**. +1. Optional. Add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Select **Insert image**. The link can reference images already hosted in your project, an asset hosted externally on a content delivery network, or any other external URL. The editor renders thumbnail previews diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 8902bdc21c4..b41ea30bfef 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -123,7 +123,7 @@ To do so: With this option enabled, `75h` is displayed instead of `1w 4d 3h`. -## Related links +## Related topics - [Time tracking solutions page](https://about.gitlab.com/solutions/time-tracking/) - Time tracking GraphQL references: diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index d75a180492e..40c9ae8bd59 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -456,7 +456,7 @@ when: - <kbd>Control</kbd> + <kbd>S</kbd> (or <kbd>Command</kbd> + <kbd>S</kbd> on Mac) is pressed while editing a file. -- Anything outside the file editor is clicked after editing a file. +- You select any area outside the file editor after editing a file. - A file or folder is created, deleted, or renamed. ### Limitations diff --git a/doc/user/project/wiki/img/content_editor_v14.0.png b/doc/user/project/wiki/img/content_editor_v14.0.png Binary files differdeleted file mode 100644 index b44a633073d..00000000000 --- a/doc/user/project/wiki/img/content_editor_v14.0.png +++ /dev/null diff --git a/doc/user/project/wiki/img/content_editor_v14.6.png b/doc/user/project/wiki/img/content_editor_v14.6.png Binary files differnew file mode 100644 index 00000000000..55fca0ace1e --- /dev/null +++ b/doc/user/project/wiki/img/content_editor_v14.6.png diff --git a/doc/user/project/wiki/img/use_new_editor_button_v14.0.png b/doc/user/project/wiki/img/use_new_editor_button_v14.0.png Binary files differdeleted file mode 100644 index d9a5cf83302..00000000000 --- a/doc/user/project/wiki/img/use_new_editor_button_v14.0.png +++ /dev/null diff --git a/doc/user/project/wiki/img/use_new_editor_button_v14.6.png b/doc/user/project/wiki/img/use_new_editor_button_v14.6.png Binary files differnew file mode 100644 index 00000000000..078fed8a1e9 --- /dev/null +++ b/doc/user/project/wiki/img/use_new_editor_button_v14.6.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 5d2a0530f68..9f1670d3f4c 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -87,7 +87,7 @@ Users with the [Developer role](../../permissions.md) can create new wiki pages: [special characters](#special-characters-in-page-titles) for subdirectories and formatting, and have [length restrictions](#length-restrictions-for-file-and-directory-names). 1. Add content to your wiki page. -1. (Optional) Attach a file, and GitLab stores it according to your installed version of GitLab: +1. Optional. Attach a file, and GitLab stores it according to your installed version of GitLab: - *Files added in [GitLab 11.3 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475):* Files are stored in the wiki's Git repository. - *Files added GitLab 11.2 and earlier:* Files are stored in GitLab itself. To add @@ -236,7 +236,7 @@ GitLab tracks wiki creation, deletion, and update events. These events are displ - [User profile](../../profile/index.md#access-your-user-profile). - Activity pages, depending on the type of wiki: - [Group activity](../../group/index.md#view-group-activity). - - [Project activity](../working_with_projects.md#project-activity). + - [Project activity](../working_with_projects.md#view-project-activity). Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). @@ -290,7 +290,7 @@ To add a link to an external wiki from a project's left sidebar: 1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. -1. (Optional) Select **Test settings** to verify the connection. +1. Optional. To verify the connection, select **Test settings**. 1. Select **Save changes**. You can now see the **External wiki** option from your project's @@ -339,27 +339,24 @@ experience in the Wiki. To opt in for the new editor: 1. Create a new wiki page, or edit an existing one. 1. Ensure the wiki page uses the Markdown format. Other formats are not yet supported. -1. Below the **Format** select box, select **Use the new editor**: +1. Above the content field, select **Edit rich text**: -  +  ### Use the Content Editor 1. [Create](#create-a-new-wiki-page) a new wiki page, or [edit](#edit-a-wiki-page) an existing one. 1. Select **Markdown** as your format. -1. Below the **Format** select box, select **Use new editor**. +1. Above **Content**, select **Edit rich text**. 1. Customize your page's content using the various formatting options available in the content editor. 1. Select **Create page** for a new page, or **Save changes** for an existing page: -  +  ### Switch back to the old editor 1. *If you're editing the page in the content editor,* scroll to **Content**. -1. Select **Switch me back to the classic editor**. -1. Select **Switch to classic editor** in the confirmation popup to confirm. - -When you switch back to the old editor, any unsaved changes are lost. +1. Select **Edit source**. ### GitLab Flavored Markdown support diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 3c82e544e26..b5b3f2d2085 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -4,35 +4,59 @@ group: Workspace info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- -# Working with projects **(FREE)** +# Manage projects **(FREE)** Most work in GitLab is done in a [project](../../user/project/index.md). Files and code are saved in projects, and most features are in the scope of projects. -## Explore projects +## View projects -You can explore other popular projects available on GitLab. To explore projects: +To explore projects: 1. On the top bar, select **Menu > Projects**. 1. Select **Explore projects**. -GitLab displays a list of projects, sorted by last updated date. To view -projects with the most [stars](#star-a-project), click **Most stars**. To view -projects with the largest number of comments in the past month, click **Trending**. +The **Projects** page shows a list of projects, sorted by last updated date. + +- To view projects with the most [stars](#star-a-project), select **Most stars**. +- To view projects with the largest number of comments in the past month, select **Trending**. NOTE: -By default, `/explore` is visible to unauthenticated users. However, if the +The **Explore projects** tab is visible to unauthenticated users unless the [**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/explore` is visible only to signed-in users. +is restricted. Then the tab is visible only to signed-in users. + +### Who can view the **Projects** page + +When you select a project, the project landing page shows the project contents. + +For public projects, and members of internal and private projects +with [permissions to view the project's code](../permissions.md#project-members-permissions), +the project landing page shows: + +- A [`README` or index file](repository/index.md#readme-and-index-files). +- A list of directories in the project's repository. + +For users without permission to view the project's code, the landing page shows: + +- The wiki homepage. +- The list of issues in the project. + +### Access a project page with the project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +To access a project from the GitLab UI using the project ID, +visit the `/projects/:id` URL in your browser or other tool accessing the project. ## Explore topics -You can explore popular project topics available on GitLab. To explore project topics: +To explore project topics: 1. On the top bar, select **Menu > Projects**. 1. Select **Explore topics**. -GitLab displays a list of topics sorted by the number of associated projects. +The **Projects** page shows list of topics sorted by the number of associated projects. To view projects associated with a topic, select a topic from the list. You can assign topics to a project on the [Project Settings page](settings/index.md#topics). @@ -44,290 +68,280 @@ If you're an instance administrator, you can administer all project topics from To create a project in GitLab: -1. In your dashboard, select **New project** or use the **New...** **{plus-square}** icon -on the top bar. The **New project** page opens. +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. 1. On the **New project** page, choose if you want to: - - Create a [blank project](#blank-projects). - - Create a project using one of the available [project templates](#project-templates). - - [Import a project](../../user/project/import/index.md) from a different repository, - if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable. - - Run [CI/CD pipelines for external repositories](../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** + - Create a [blank project](#create-a-blank-project). + - Create a project from a: + - [built-in template](#create-a-project-from-a-built-in-template). + - [custom template](#create-a-project-from-a-custom-template). + - [HIPAA audit protocol template](#create-a-project-from-the-hipaa-audit-protocol-template). + - [Import a project](../../user/project/import/index.md) + from a different repository. Contact your GitLab administrator if this option is not available. + - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). NOTE: For a list of words that can't be used as project names see -[Reserved project and group names](../../user/reserved_names.md). - -### Blank projects - -To create a new blank project on the **New project** page: - -1. Click **Create blank project** -1. Provide the following information: - - The name of your project in the **Project name** field. You can't use - special characters, but you can use spaces, hyphens, underscores, or even - emoji. When adding the name, the **Project slug** auto populates. - The slug is what the GitLab instance uses as the URL path to the project. - If you want a different slug, input the project name first, - then change the slug after. - - The path to your project in the **Project slug** field. This is the URL - path for your project that the GitLab instance uses. If the - **Project name** is blank, it auto populates when you fill in - the **Project slug**. - - The **Project description (optional)** field enables you to enter a - description for your project's dashboard, which helps others - understand what your project is about. Though it's not required, it's a good - idea to fill this in. - - Changing the **Visibility Level** modifies the project's - [viewing and access rights](../../public_access/public_access.md) for users. - - Selecting the **Initialize repository with a README** option creates a - README file so that the Git repository is initialized, has a default branch, and - can be cloned. -1. Click **Create project**. - -### Project templates - -Project templates can pre-populate a new project with the necessary files to get you -started quickly. - -There are two main types of project templates: - -- [Built-in templates](#built-in-templates), sourced from the following groups: - - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - - [`pages`](https://gitlab.com/pages) -- [Custom project templates](#custom-project-templates), for custom templates - configured by GitLab administrators and users. - -#### Built-in templates - -Built-in templates are project templates that are: - -- Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - and [`pages`](https://gitlab.com/pages) groups. -- Released with GitLab. -- Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/). - -To use a built-in template on the **New project** page: - -1. Click **Create from template** +[reserved project and group names](../../user/reserved_names.md). + +## Create a blank project + +To create a blank project: + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for + users, change the **Visibility Level**. + - To create README file so that the Git repository is initialized, has a default branch, and + can be cloned, select **Initialize repository with a README**. + - To analyze the source code in the project for known security vulnerabilities, + select **Enable Static Application Security Testing (SAST)**. +1. Select **Create project**. + +## Create a project from a built-in template + +A built-in project template populates a new project with files to get you started. +Built-in templates are sourced from the following groups: + +- [`project-templates`](https://gitlab.com/gitlab-org/project-templates) +- [`pages`](https://gitlab.com/pages) + +Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/). + +To create a project from a built-in template: + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create from template**. 1. Select the **Built-in** tab. -1. From the list of available built-in templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is - the same as creating a [blank project](#blank-projects). +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from a custom template **(PREMIUM)** -##### Enterprise templates **(ULTIMATE)** - -GitLab is developing Enterprise templates to help you streamline audit management with selected regulatory standards. These templates automatically import issues that correspond to each regulatory requirement. - -To create a new project with an Enterprise template, on the **New project** page: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. -1. Click **Create from template** +Custom project templates are available at: + +- The [instance-level](../../user/admin_area/custom_project_templates.md) +- The [group-level](../../user/group/custom_project_templates.md) + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create from template**. +1. Select the **Instance** or **Group** tab. +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - The description of your project's dashboard in the **Project description (optional)** field. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 + +The HIPAA Audit Protocol template contains issues for audit inquiries in the +HIPAA Audit Protocol published by the U.S Department of Health and Human Services. + +To create a project from the HIPAA Audit Protocol template: + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create from template**. 1. Select the **Built-in** tab. -1. From the list of available built-in Enterprise templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is the same as creating a [blank project](#blank-projects). +1. Locate the **HIPAA Audit Protocol** template: + - To view a preview of the template, select **Preview**. + - To use the template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Push to create a new project -Available Enterprise templates include: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. -- HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) +Use `git push` to push a local project repository to GitLab. After you push a repository, +GitLab creates your project in your chosen namespace. -NOTE: -You can improve the existing built-in templates or contribute new ones in the -[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and -[`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). +You cannot use `git push` to create projects with project paths that: -##### Custom project templates **(PREMIUM)** +- Have previously been used. +- Have been [renamed](settings/index.md#renaming-a-repository). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +Previously used project paths have a redirect. The redirect causes push attempts to redirect requests +to the renamed project location, instead of creating a new project. To create a new project for a previously +used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). -Creating new projects based on custom project templates is a convenient option for -quickly starting projects. +Prerequisites: -Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) -from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) -from the **Group** tab, on the **Create from template** page. +- To push with SSH, you must have [an SSH key](../../ssh/index.md) that is +[added to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). +- You must have permission to add new projects to a namespace. To check if you have permission: -To use a custom project template on the **New project** page: + 1. On the top bar, select **Menu > Project**. + 1. Select **Groups**. + 1. Select a group. + 1. Confirm that **New project** is visible in the upper right + corner. Contact your GitLab + administrator if you require permission. -1. Click **Create from template** -1. Select the **Instance** tab or the **Group** tab. -1. From the list of available custom templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is - the same as creating a [blank project](#blank-projects). +To push your repository and create a project: -## Push to create a new project +1. Push with SSH or HTTPS: + - To push with SSH: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + ```shell + git push --set-upstream git@gitlab.example.com:namespace/myproject.git master + ``` -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/index.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. - ``` + - To push with HTTPS: -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. + ```shell + git push --set-upstream https://gitlab.example.com/namespace/myproject.git master + ``` -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)). + - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. + - For `namespace`, use the name of your [namespace](../group/index.md#namespaces). + - For `myproject`, use the name of your project. + - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. +1. Optional. To configure the remote: -This feature does not work for project paths that have previously been in use and -[renamed](settings/index.md#renaming-a-repository). A redirect exists over the previous project path -that causes push attempts to redirect requests to the renamed project location, instead of creating -a new project. To create a new project, use the [Web UI](#create-a-project) or the -[Projects API](../../api/projects.md#create-project). + ```shell + git remote add origin https://gitlab.example.com/namespace/myproject.git + ``` -## Fork a project +When the push completes, GitLab displays the message: -A fork is a copy of an original repository that you put in another namespace -where you can experiment and apply changes that you can later decide whether or -not to share, without affecting the original project. +```shell +remote: The private project namespace/myproject was created. +``` -It takes just a few steps to [fork a project in GitLab](repository/forking_workflow.md#creating-a-fork). +To view your new project, go to `https://gitlab.example.com/namespace/myproject`. +Your project's visibility is set to **Private** by default. To change project visibility, adjust your +[project's settings](../../public_access/public_access.md#change-project-visibility). ## Star a project -You can star a project to make it easier to find projects you frequently use. -The number of stars a project has can indicate its popularity. +You can add a star to projects you use frequently to make them easier to find. -To star a project: +To add a star to a project: -1. Go to the home page of the project you want to star. -1. In the upper right corner of the page, click **Star**. +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. In the upper right corner of the page, select **Star**. -To view your starred projects: +## View starred projects -1. On the top bar, select **Menu > Projects**. -1. Select **Starred Projects**. +1. On the top bar, select **Menu > Project**. +1. Select **Starred projects**. 1. GitLab displays information about your starred projects, including: - - Project description, including name, description, and icon - - Number of times this project has been starred - - Number of times this project has been forked - - Number of open merge requests - - Number of open issues + - Project description, including name, description, and icon. + - Number of times this project has been starred. + - Number of times this project has been forked. + - Number of open merge requests. + - Number of open issues. ## Delete a project -To delete a project, first navigate to the home page for that project. +After you delete a project, projects in personal namespaces are deleted immediately. To delay deletion of projects in a group +you can [enable delayed project removal](../group/index.md#enable-delayed-project-deletion). -1. Navigate to **Settings > General**. +To delete a project: + +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. -1. Click **Delete project** -1. Confirm this action by typing in the expected text. +1. Select **Delete project** +1. Confirm this action by completing the field. -Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enable delayed project removal](../group/index.md#enable-delayed-project-removal). +## View project activity -## Project settings +To view the activity of a project: -Set the project's visibility level and the access levels to its various pages -and perform actions like archiving, renaming or transferring a project. +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. On the left sidebar, select **Project information > Activity**. +1. Select a tab to view the type of project activity. -Read through the documentation on [project settings](settings/index.md). +## Leave a project -## Project activity +If you leave a project you are no longer a project +member and cannot contribute. -To view the activity of a project: +To leave a project: -1. On the left sidebar, select **Project information > Activity**. -1. Select a tab to view **All** the activity, or to filter it by any of these criteria: - - **Push events** - - **Merge events** - - **Issue events** - - **Comments** - - **Team** - - **Wiki** - -### Leave a project - -**Leave project** only displays on the project's dashboard -when a project is part of a group (under a -[group namespace](../group/index.md#namespaces)). -If you choose to leave a project you are no longer a project -member, and cannot contribute. - -## Use your project as a Go package - -Any project can be used as a Go package. GitLab responds correctly to `go get` -and `godoc.org` discovery requests, including the -[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and -[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. - -Private projects, including projects in subgroups, can be used as a Go package, -but may require configuration to work correctly. GitLab responds correctly -to `go get` discovery requests for projects that *are not* in subgroups, -regardless of authentication or authorization. -[Authentication](#authenticate-go-requests) is required to use a private project -in a subgroup as a Go package. Otherwise, GitLab truncates the path for -private projects in subgroups to the first two segments, causing `go get` to -fail. - -GitLab implements its own Go proxy. This feature must be enabled by an -administrator and requires additional configuration. See [GitLab Go -Proxy](../packages/go_proxy/index.md). - -### Disable Go module features for private projects - -In Go 1.12 and later, Go queries module proxies and checksum databases in the -process of [fetching a -module](../../development/go_guide/dependencies.md#fetching). This can be -selectively disabled with `GOPRIVATE` (disable both), -[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy -queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) -(disable checksum queries). - -`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go -modules and Go module prefixes. For example, -`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that -one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all* -projects on GitLab.com. Go does not query module proxies if the module name or a -prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum -databases if the module name or a prefix of it appears in `GONOPRIVATE` or -`GONOSUMDB`. - -### Authenticate Go requests - -To authenticate requests to private projects made by Go, use a [`.netrc` -file](https://everything.curl.dev/usingcurl/netrc) and a [personal access -token](../profile/personal_access_tokens.md) in the password field. **This only -works if your GitLab instance can be accessed with HTTPS.** The `go` command -does not transmit credentials over insecure connections. This authenticates -all HTTPS requests made directly by Go, but does not authenticate requests made -through Git. +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. Select **Leave project**. The **Leave project** option only displays +on the project dashboard when a project is part of a group under a +[group namespace](../group/index.md#namespaces). -For example: +## Use a project as a Go package + +Prerequisites: + +- Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). +- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause +`go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. + +To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: + +- [`go-import`](https://pkg.go.dev/cmd/go#hdr-Remote_import_paths) +- [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) + +### Authenticate Go requests to private projects + +Prerequisites: + +- Your GitLab instance must be accessible with HTTPS. +- You must have a [personal access token](../profile/personal_access_tokens.md). + +To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: ```plaintext machine gitlab.example.com @@ -335,95 +349,110 @@ login <gitlab_user_name> password <personal_access_token> ``` -NOTE: On Windows, Go reads `~/_netrc` instead of `~/.netrc`. -### Authenticate Git fetches +The `go` command does not transmit credentials over insecure connections. It authenticates +HTTPS requests made by Go, but does not authenticate requests made +through Git. -If a module cannot be fetched from a proxy, Go falls back to using Git (for -GitLab projects). Git uses `.netrc` to authenticate requests. You can also -configure Git to either: +### Authenticate Git requests -- Embed specific credentials in the request URL. -- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. +If Go cannot fetch a module from a proxy, it uses Git. Git uses a `.netrc` file to authenticate requests, but you can +configure other authentication methods. -```shell -# Embed credentials in any request to GitLab.com: -git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" +Configure Git to either: -# Use SSH instead of HTTPS: -git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" -``` +- Embed credentials in the request URL: -### Fetch Go modules from Geo secondary sites + ```shell + git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + ``` + +- Use SSH instead of HTTPS: + + ```shell + git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" + ``` + +### Disable Go module fetching for private projects + +To [fetch modules or packages](../../development/go_guide/dependencies.md#fetching), Go uses +the [environment variables](../../development/go_guide/dependencies.md#proxies): -As Go modules are stored in Git repositories, you can use the [Geo](../../administration/geo/index.md) -feature that allows Git repositories to be accessed on the secondary Geo servers. +- `GOPRIVATE` +- `GONOPROXY` +- `GONOSUMDB` -In the following examples, the primary's site domain name is `gitlab.example.com`, -and the secondary's is `gitlab-secondary.example.com`. +To disable fetching: -`go get` will initially generate some HTTP traffic to the primary, but when the module -download commences, the `insteadOf` configuration sends the traffic to the secondary. +1. Disable `GOPRIVATE`: + - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. + - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. +1. Disable proxy queries in `GONOPROXY`. +1. Disable checksum queries in `GONOSUMDB`. -#### Use SSH to access the Geo secondary +- If the module name or its prefix is in `GOPRIVATE` or `GONOPROXY`, Go does not query module +proxies. +- If the module name or its prefix is in `GONOPRIVATE` or `GONOSUMDB`, Go does not query +Checksum databases. -To fetch Go modules from the secondary using SSH: +### Fetch Go modules from Geo secondary sites + +Use [Geo](../../administration/geo/index.md) to access Git repositories that contain Go modules +on secondary Geo servers. + +You can use SSH or HTTP to access the Geo secondary server. + +#### Use SSH to access the Geo secondary server + +To access the Geo secondary server with SSH: 1. Reconfigure Git on the client to send traffic for the primary to the secondary: - ```plaintext + ```shell git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" ``` -1. Ensure the client is set up for SSH access to GitLab repositories. This can be tested on the primary, - and GitLab will replicate the public key to the secondary. + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + +1. Ensure the client is set up for SSH access to GitLab repositories. You can test this on the primary, + and GitLab replicates the public key to the secondary. + +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. #### Use HTTP to access the Geo secondary -Using HTTP to fetch Go modules does not work with CI/CD job tokens, only with -persistent access tokens that are replicated to the secondary. +You must use persistent access tokens that replicate to the secondary server. You cannot use +CI/CD job tokens to fetch Go modules with HTTP. -To fetch Go modules from the secondary using HTTP: +To access the Geo secondary server with HTTP: -1. Put in place a Git `insteadOf` redirect on the client: +1. Add a Git `insteadOf` redirect on the client: - ```plaintext + ```shell git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" ``` + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + 1. Generate a [personal access token](../profile/personal_access_tokens.md) and - provide those credentials in the client's `~/.netrc` file: + add the credentials in the client's `~/.netrc` file: - ```plaintext + ```shell machine gitlab.example.com login USERNAME password TOKEN machine gitlab-secondary.example.com login USERNAME password TOKEN ``` -## Access project page with project ID +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. +## Related topics -To quickly access a project from the GitLab UI using the project ID, -visit the `/projects/:id` URL in your browser or other tool accessing the project. - -## Project's landing page - -The project's landing page shows different information depending on -the project's visibility settings and user permissions. - -For public projects, and to members of internal and private projects -with [permissions to view the project's code](../permissions.md#project-members-permissions): - -- The content of a - [`README` or an index file](repository/index.md#readme-and-index-files) - is displayed (if any), followed by the list of directories in the - project's repository. -- If the project doesn't contain either of these files, the - visitor sees the list of files and directories of the repository. - -For users without permissions to view the project's code, GitLab displays: - -- The wiki homepage, if any. -- The list of issues in the project. +- [Import a project](../../user/project/import/index.md). +- [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). +- [Fork a project](repository/forking_workflow.md#creating-a-fork). +- [Adjust project visibility and access levels](settings/index.md#sharing-and-permissions). diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index 810e1427e11..c0fb29b435a 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -16,54 +16,51 @@ A GitLab administrator [can then choose](admin_area/review_abuse_reports.md) to: You can report a user through their: -- [Profile](#reporting-abuse-through-a-users-profile) -- [Comments](#reporting-abuse-through-a-users-comment) -- [Issues and Merge requests](#reporting-abuse-through-a-users-issue-or-merge-request) +- [Profile](#report-abuse-from-the-users-profile-page) +- [Comments](#report-abuse-from-a-users-comment) +- [Issues](#report-abuse-from-an-issue) +- [Merge requests](#report-abuse-from-a-merge-request) - [Snippets](snippets.md#mark-snippet-as-spam) -## Reporting abuse through a user's profile +## Report abuse from the user's profile page To report abuse from a user's profile page: -1. Click on the exclamation point report abuse button at the top right of the - user's profile. +1. Anywhere in GitLab, select the name of the user. +1. In the top right corner of the user's profile, select **Report abuse** (**{information-o}**). 1. Complete an abuse report. -1. Click the **Send report** button. +1. Select **Send report**. -## Reporting abuse through a user's comment +## Report abuse from a user's comment To report abuse from a user's comment: -1. Click on the vertical ellipsis (⋮) more actions button to open the dropdown. -1. Select **Report as abuse**. +1. In the comment, in the top right corner, select **More actions** (**{ellipsis_v}**). +1. Select **Report abuse to admin**. 1. Complete an abuse report. -1. Click the **Send report** button. +1. Select **Send report**. NOTE: A URL to the reported user's comment is pre-filled in the abuse report's **Message** field. -## Reporting abuse through a user's issue or merge request +## Report abuse from an issue -The **Report abuse** button is displayed at the top right of the issue or merge request: - -- When **Report abuse** is selected from the menu that appears when the - **Close issue** or **Close merge request** button is clicked, for users that - have permission to close the issue or merge request. -- When viewing the issue or merge request, for users that don't have permission - to close the issue or merge request. +1. On the issue, in the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Report abuse**. +1. Submit an abuse report. +1. Select **Send report**. -With the **Report abuse** button displayed, to submit an abuse report: +## Report abuse from a merge request -1. Click the **Report abuse** button. +1. On the merge request, in the top right corner, either: + - Select **Report abuse**. This option is displayed if you do not have permission to close the merge request. + - Next to **Mark as draft**, select the down arrow (**{chevron-down}**) and then select **Report abuse**. + This option is displayed if you have permission to close the merge request. 1. Submit an abuse report. -1. Click the **Send report** button. - -NOTE: -A URL to the reported user's issue or merge request is pre-filled -in the abuse report's **Message** field. +1. Select **Send report**. -## Managing abuse reports +## Related topics -Administrators are able to view and resolve abuse reports. -For more information, see [abuse reports administration documentation](admin_area/review_abuse_reports.md). +- Administrators can 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 f68951badff..b9c45bce43a 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -14,6 +14,10 @@ This is the user documentation. To configure the Advanced Search, visit the [administrator documentation](../../integration/elasticsearch.md). Advanced Search is enabled in GitLab.com. +INFO: +Get advanced search and more with a +[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-advanced-search-docs). + GitLab Advanced Search expands on the Basic Search with an additional set of features for faster, more advanced searches across the entire GitLab instance when searching in: @@ -48,13 +52,13 @@ The Advanced Search can be useful in various scenarios: ## Use the Advanced Search syntax -Elasticsearch has only data for the default branch. That means that if you go +Elasticsearch has data for the default branch only. That means that if you go to the repository tree and switch the branch from the default to something else, -then the "Code" tab in the search result page will be served by the basic +then the **Code** tab in the search result page is served by the basic search even if Elasticsearch is enabled. The Advanced Search syntax supports fuzzy or exact search queries with prefixes, -boolean operators, and much more. Use the search as before and GitLab will show +boolean operators, and much more. Use the search as before and GitLab shows you matching code from each project you have access to.  @@ -62,8 +66,8 @@ you matching code from each project you have access to. Full details can be found in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/query-dsl-simple-query-string-query.html#_simple_query_string_syntax), but here's a quick guide: -- Searches look for all the words in a query, in any order - e.g.: searching - issues for [`display bug`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=display+bug&group_id=9970&project_id=278964) and [`bug display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+Display&group_id=9970&project_id=278964) will return the same results. +- Searches look for all the words in a query, in any order - for example: searching + issues for [`display bug`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=display+bug&group_id=9970&project_id=278964) and [`bug display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+Display&group_id=9970&project_id=278964) return the same results. - To find the exact phrase (stemming still applies), use double quotes: [`"display bug"`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%22display+bug%22&group_id=9970&project_id=278964) - To find bugs not mentioning display, use `-`: [`bug -display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+-display&group_id=9970&project_id=278964) - To find a bug in display or banner, use `|`: [`bug display | banner`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+display+%7C+banner&group_id=9970&project_id=278964) @@ -81,7 +85,7 @@ Advanced Search also supports the use of filters. The available filters are: - `blob`: Filters by Git `object ID`. Exact match only. To use them, add them to your keyword in the format `<filter_name>:<value>` without -any spaces between the colon (`:`) and the value. When no keyword is provided, an asterisk (`*`) will be used as the keyword. +any spaces between the colon (`:`) and the value. When no keyword is provided, an asterisk (`*`) is used as the keyword. Examples: diff --git a/doc/user/search/img/dashboard_links_v13_11.png b/doc/user/search/img/dashboard_links_v13_11.png Binary files differdeleted file mode 100644 index 5f2e61eee1e..00000000000 --- a/doc/user/search/img/dashboard_links_v13_11.png +++ /dev/null diff --git a/doc/user/search/img/dashboard_links_v14_6.png b/doc/user/search/img/dashboard_links_v14_6.png Binary files differnew file mode 100644 index 00000000000..52ae39d9d1a --- /dev/null +++ b/doc/user/search/img/dashboard_links_v14_6.png diff --git a/doc/user/search/img/filter_approved_by_merge_requests_v13_0.png b/doc/user/search/img/filter_approved_by_merge_requests_v13_0.png Binary files differdeleted file mode 100644 index 5020da90297..00000000000 --- a/doc/user/search/img/filter_approved_by_merge_requests_v13_0.png +++ /dev/null diff --git a/doc/user/search/img/filter_approved_by_merge_requests_v14_6.png b/doc/user/search/img/filter_approved_by_merge_requests_v14_6.png Binary files differnew file mode 100644 index 00000000000..8d47fdc2652 --- /dev/null +++ b/doc/user/search/img/filter_approved_by_merge_requests_v14_6.png diff --git a/doc/user/search/img/filter_approver_merge_requests.png b/doc/user/search/img/filter_approver_merge_requests.png Binary files differdeleted file mode 100644 index 4c28ee17f47..00000000000 --- a/doc/user/search/img/filter_approver_merge_requests.png +++ /dev/null diff --git a/doc/user/search/img/filter_approver_merge_requests_v14_6.png b/doc/user/search/img/filter_approver_merge_requests_v14_6.png Binary files differnew file mode 100644 index 00000000000..58950031378 --- /dev/null +++ b/doc/user/search/img/filter_approver_merge_requests_v14_6.png diff --git a/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png b/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png Binary files differdeleted file mode 100644 index 8f59534ef1c..00000000000 --- a/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png +++ /dev/null diff --git a/doc/user/search/img/filtering_merge_requests_by_date_v14_6.png b/doc/user/search/img/filtering_merge_requests_by_date_v14_6.png Binary files differnew file mode 100644 index 00000000000..398820f7864 --- /dev/null +++ b/doc/user/search/img/filtering_merge_requests_by_date_v14_6.png diff --git a/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png b/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png Binary files differdeleted file mode 100644 index e73a0995d73..00000000000 --- a/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png +++ /dev/null diff --git a/doc/user/search/img/filtering_merge_requests_by_environment_v14_6.png b/doc/user/search/img/filtering_merge_requests_by_environment_v14_6.png Binary files differnew file mode 100644 index 00000000000..c35f2c8a58b --- /dev/null +++ b/doc/user/search/img/filtering_merge_requests_by_environment_v14_6.png diff --git a/doc/user/search/img/issue_search_by_term.png b/doc/user/search/img/issue_search_by_term.png Binary files differdeleted file mode 100644 index 64450c6a891..00000000000 --- a/doc/user/search/img/issue_search_by_term.png +++ /dev/null diff --git a/doc/user/search/img/issue_search_filter_v12_7.png b/doc/user/search/img/issue_search_filter_v12_7.png Binary files differdeleted file mode 100644 index 102a2e0859c..00000000000 --- a/doc/user/search/img/issue_search_filter_v12_7.png +++ /dev/null diff --git a/doc/user/search/img/issues_assigned_to_you.png b/doc/user/search/img/issues_assigned_to_you.png Binary files differdeleted file mode 100644 index 55986eedcba..00000000000 --- a/doc/user/search/img/issues_assigned_to_you.png +++ /dev/null diff --git a/doc/user/search/img/issues_filter_none_any.png b/doc/user/search/img/issues_filter_none_any.png Binary files differdeleted file mode 100644 index 9682fc55315..00000000000 --- a/doc/user/search/img/issues_filter_none_any.png +++ /dev/null diff --git a/doc/user/search/img/issues_mrs_shortcut_v14_4.png b/doc/user/search/img/issues_mrs_shortcut_v14_4.png Binary files differdeleted file mode 100644 index 2610e611446..00000000000 --- a/doc/user/search/img/issues_mrs_shortcut_v14_4.png +++ /dev/null diff --git a/doc/user/search/img/issues_mrs_shortcut_v14_6.png b/doc/user/search/img/issues_mrs_shortcut_v14_6.png Binary files differnew file mode 100644 index 00000000000..52753eb8fc7 --- /dev/null +++ b/doc/user/search/img/issues_mrs_shortcut_v14_6.png diff --git a/doc/user/search/img/project_search.png b/doc/user/search/img/project_search.png Binary files differdeleted file mode 100644 index b2525b2c771..00000000000 --- a/doc/user/search/img/project_search.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 325e5386417..aa4950cfa33 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -5,26 +5,20 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: index, reference, howto --- -# Search through GitLab **(FREE)** +# Searching in GitLab **(FREE)** -## Issues and merge requests +## Search issues and merge requests -To search through issues and merge requests in multiple projects, use the **Issues** or **Merge Requests** links -in the top-right part of your screen. These instructions are valid for both. +To search through issues and merge requests in multiple projects, on the top bar, select the **Issues** or **Merge Requests** links. -The numbers in the right-hand side of the top menu indicate how many issues, merge requests, -and to-do items are assigned to you: +The numbers indicate how many issues, merge requests, and to-do items are assigned to you: - + - **{issues}** **Issues**: The open issues assigned to you. - **{merge-request-open}** **Merge requests**: The [merge requests](../project/merge_requests/index.md) assigned to you. - **{todo-done}** **To-do items**: The [to-do items](../todos.md) assigned to you. -When you click **Issues**, GitLab shows the opened issues assigned to you: - - - You can search through **Open**, **Closed**, or **All** issues. You can also filter the results using the search and filter field, as described in @@ -35,7 +29,7 @@ You can also filter the results using the search and filter field, as described GitLab shows shortcuts to issues and merge requests created by you or assigned to you in the search field in the upper right corner: - + ### Filter issue and merge request lists @@ -63,25 +57,13 @@ groups: - `=`: Is - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) 1. Enter the text to [filter the attribute by](#filters-autocomplete). + You can filter some attributes by **None** or **Any**. 1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical - `AND`. For example, filtering by an Author and Milestone `!=` 12.6 filters for the issues where the - author matches your selection, and the milestone is not 12.6: - -  + `AND`. GitLab displays the results on-screen, but you can also [retrieve them as an RSS feed](#retrieve-search-results-as-feed). -### Filtering by **None** / **Any** - -Some filter fields like milestone and assignee, allow you to filter by **None** or **Any**. - - - -Selecting **None** returns results that have an empty value for that field. For example: no milestone, no assignee. - -Selecting **Any** does the opposite. It returns results that have a non-empty value for that field. - ### Searching for specific terms You can filter issues and merge requests by specific terms included in titles or descriptions. @@ -95,8 +77,6 @@ You can filter issues and merge requests by specific terms included in titles or issues for `included in titles` is same as `included titles` - Search is limited to 4096 characters and 64 terms per query. - - ### Retrieve search results as feed > Feeds for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66336) in GitLab 14.3. @@ -128,7 +108,7 @@ You can filter the **Issues** list to individual instances by their ID. For exam To filter merge requests by an individual approver, you can type (or select from the dropdown) **Approver** and select the user. - + ### Filtering merge requests by "approved by" **(PREMIUM)** @@ -138,7 +118,7 @@ the dropdown) **Approver** and select the user. To filter merge requests already approved by a specific individual, you can type (or select from the dropdown) **Approved-By** and select the user. - + ### Filtering merge requests by reviewer **(FREE)** @@ -161,13 +141,15 @@ you can type (or select from the dropdown) the following: When filtering by an environment, a dropdown presents all environments that you can choose from: - + -When filtering by a deploy date, you must enter the date manually. Deploy dates +When filtering by `Deployed-before` or `Deployed-after`, the date refers to when +the deployment to an environment (triggered by the merge commit) completed successfully. +You must enter the deploy date manually. Deploy dates use the format `YYYY-MM-DD`, and must be quoted if you wish to specify both a date and time (`"YYYY-MM-DD HH:MM"`): - + ## Filters autocomplete @@ -245,20 +227,9 @@ and **Labels**, select multiple issues to add to a list of your choice:  -## Shortcut - -To view issues and merge requests created or assigned to you in a project: - -1. Go to your project. -1. In the top navigation bar, click the search box to display a list of issues and - merge requests. -1. Select your desired issue or merge request: - -  - -### Autocomplete suggestions +## Autocomplete suggestions -You can also type in this search bar to see autocomplete suggestions for: +In the search bar, you can view autocomplete suggestions for: - Projects and groups - Various help pages (try and type **API help**) diff --git a/doc/user/snippets.md b/doc/user/snippets.md index e2cb9937f76..dc3ab35067e 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -52,7 +52,7 @@ You can create snippets in multiple ways, depending on whether you want to creat Filenames with appropriate extensions display [syntax highlighting](#filenames). Failure to add a filename can cause a known [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). If you don't provide a filename, GitLab [creates a name for you](#filenames). -1. (Optional) Add [multiple files](#add-or-remove-multiple-files) to your snippet. +1. Optional. Add [multiple files](#add-or-remove-multiple-files) to your snippet. 1. Select a visibility level, and select **Create snippet**. After you create a snippet, you can still [add more files to it](#add-or-remove-multiple-files). diff --git a/doc/user/tasks.md b/doc/user/tasks.md index e5e5510407e..5fde64e3578 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -15,15 +15,18 @@ For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitl FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `work_items`. +On GitLab.com, this feature is not available. The feature is not ready for production use. Use tasks to track steps needed for the [issue](project/issues/index.md) to be closed. When planning an issue, you need a way to capture and break down technical -requirements or steps necessary to complete it. An issue with tasks is better defined, +requirements or steps necessary to complete it. An issue with related tasks is better defined, and so you can provide a more accurate issue weight and completion criteria. -To see the roadmap for migrating issues and [epics](group/epics/index.md) +Tasks are a type of work item, a step towards [default issue types](https://gitlab.com/gitlab-org/gitlab/-/issues/323404) +in GitLab. +For the roadmap of migrating issues and [epics](group/epics/index.md) to work items and adding custom work item types, visit [epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or [Plan direction page](https://about.gitlab.com/direction/plan/). @@ -31,4 +34,4 @@ to work items and adding custom work item types, visit ## View a task The only way to view a task is to open it with a deep link, -for example: `/<group_name>/<project_name>/-/work_item/1` +for example: `/<group_name>/<project_name>/-/work_item/1`. diff --git a/doc/user/todos.md b/doc/user/todos.md index 9a985664ed1..2486db813ff 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -29,7 +29,7 @@ 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](project/issues/issue_data_and_actions.md#mentions) in the description or +- You're [mentioned](discussions/index.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. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 8ca7f7defb2..cf35f082880 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -6,6 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Workspace +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. + Workspace will be above the [top-level namespaces](../group/index.md#namespaces) for you to manage everything you do as a GitLab administrator, including: |
