diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-12-19 14:01:45 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-12-19 14:01:45 +0300 |
| commit | 9297025d0b7ddf095eb618dfaaab2ff8f2018d8b (patch) | |
| tree | 865198c01d1824a9b098127baa3ab980c9cd2c06 /doc/user | |
| parent | 6372471f43ee03c05a7c1f8b0c6ac6b8a7431dbe (diff) | |
Add latest changes from gitlab-org/gitlab@16-7-stable-eev16.7.0-rc42
Diffstat (limited to 'doc/user')
547 files changed, 6616 insertions, 4593 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md deleted file mode 100644 index 30ba2ad3e7b..00000000000 --- a/doc/user/admin_area/analytics/dev_ops_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/analytics/dev_ops_reports.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/analytics/dev_ops_reports.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md deleted file mode 100644 index f5849f0b876..00000000000 --- a/doc/user/admin_area/analytics/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/analytics/index.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/analytics/index.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md deleted file mode 100644 index 12eb44d6ebc..00000000000 --- a/doc/user/admin_area/analytics/usage_trends.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/analytics/usage_trends.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/analytics/usage_trends.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md deleted file mode 100644 index 6a3760bc62d..00000000000 --- a/doc/user/admin_area/appearance.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/appearance.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../administration/appearance.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md deleted file mode 100644 index 4893b94ce50..00000000000 --- a/doc/user/admin_area/broadcast_messages.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/broadcast_messages.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../administration/broadcast_messages.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md deleted file mode 100644 index f38eed5de43..00000000000 --- a/doc/user/admin_area/credentials_inventory.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/credentials_inventory.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../administration/credentials_inventory.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md deleted file mode 100644 index dc773b0aaca..00000000000 --- a/doc/user/admin_area/custom_project_templates.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/custom_project_templates.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/custom_project_templates.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md deleted file mode 100644 index 54d7d82af98..00000000000 --- a/doc/user/admin_area/diff_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/diff_limits.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/diff_limits.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/email_from_gitlab.md b/doc/user/admin_area/email_from_gitlab.md deleted file mode 100644 index e5194f05381..00000000000 --- a/doc/user/admin_area/email_from_gitlab.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/email_from_gitlab.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/email_from_gitlab.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/external_users.md b/doc/user/admin_area/external_users.md deleted file mode 100644 index ec28f109384..00000000000 --- a/doc/user/admin_area/external_users.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/external_users.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/external_users.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md deleted file mode 100644 index cd0f2f5646a..00000000000 --- a/doc/user/admin_area/geo_sites.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/geo_sites.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/geo_sites.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md deleted file mode 100644 index a729cefa7b8..00000000000 --- a/doc/user/admin_area/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/admin_area.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/admin_area.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md deleted file mode 100644 index 724c9885801..00000000000 --- a/doc/user/admin_area/labels.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/labels.md' -remove_date: '2023-10-05' ---- - -This document was moved to [another location](../../administration/labels.md). - -<!-- This redirect file can be deleted after <2023-10-05>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md deleted file mode 100644 index 636f5cb2831..00000000000 --- a/doc/user/admin_area/license.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/license.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/license.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md deleted file mode 100644 index 4835d656cfa..00000000000 --- a/doc/user/admin_area/license_file.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/license_file.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/license_file.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md deleted file mode 100644 index de079d08d3a..00000000000 --- a/doc/user/admin_area/merge_requests_approvals.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/merge_requests_approvals.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../administration/merge_requests_approvals.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md deleted file mode 100644 index 3390c4791be..00000000000 --- a/doc/user/admin_area/moderate_users.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/moderate_users.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../administration/moderate_users.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md deleted file mode 100644 index bda326d4daf..00000000000 --- a/doc/user/admin_area/monitoring/health_check.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/monitoring/health_check.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/monitoring/health_check.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md deleted file mode 100644 index 0e607b03b82..00000000000 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/reporting/git_abuse_rate_limit.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/reporting/git_abuse_rate_limit.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/reporting/ip_addr_restrictions.md b/doc/user/admin_area/reporting/ip_addr_restrictions.md deleted file mode 100644 index 85783640b28..00000000000 --- a/doc/user/admin_area/reporting/ip_addr_restrictions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/reporting/ip_addr_restrictions.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/reporting/ip_addr_restrictions.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md deleted file mode 100644 index 043481b6255..00000000000 --- a/doc/user/admin_area/reporting/spamcheck.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/reporting/spamcheck.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/reporting/spamcheck.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md deleted file mode 100644 index 0e01025896e..00000000000 --- a/doc/user/admin_area/review_abuse_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/review_abuse_reports.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/review_abuse_reports.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md deleted file mode 100644 index 2deed61388b..00000000000 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/account_and_limit_settings.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/account_and_limit_settings.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md deleted file mode 100644 index 72cf369146e..00000000000 --- a/doc/user/admin_area/settings/continuous_integration.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/continuous_integration.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/continuous_integration.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md deleted file mode 100644 index 984eeb24bd1..00000000000 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/deprecated_api_rate_limits.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/deprecated_api_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md deleted file mode 100644 index f90aa7cc865..00000000000 --- a/doc/user/admin_area/settings/email.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/email.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/email.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md deleted file mode 100644 index 02b1ebadc9b..00000000000 --- a/doc/user/admin_area/settings/external_authorization.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/external_authorization.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/external_authorization.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md deleted file mode 100644 index c87cac2b8ac..00000000000 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/files_api_rate_limits.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/files_api_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md deleted file mode 100644 index 8e99005509a..00000000000 --- a/doc/user/admin_area/settings/floc.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/floc.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/settings/floc.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md deleted file mode 100644 index 8d7840b804c..00000000000 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/git_lfs_rate_limits.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/settings/git_lfs_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md deleted file mode 100644 index 572a9c55642..00000000000 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/gitaly_timeouts.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/settings/gitaly_timeouts.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md deleted file mode 100644 index 38fe5c3b54c..00000000000 --- a/doc/user/admin_area/settings/help_page.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/help_page.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/settings/help_page.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md deleted file mode 100644 index ad55f424d81..00000000000 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/import_export_rate_limits.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/settings/import_export_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/incident_management_rate_limits.md b/doc/user/admin_area/settings/incident_management_rate_limits.md deleted file mode 100644 index ad11d6f7f36..00000000000 --- a/doc/user/admin_area/settings/incident_management_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/incident_management_rate_limits.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../../administration/settings/incident_management_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md deleted file mode 100644 index 37112e6897f..00000000000 --- a/doc/user/admin_area/settings/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/index.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../../administration/settings/index.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md deleted file mode 100644 index 752630ea922..00000000000 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/instance_template_repository.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../../administration/settings/instance_template_repository.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md deleted file mode 100644 index 269864bdd49..00000000000 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/package_registry_rate_limits.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../../administration/settings/package_registry_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md deleted file mode 100644 index eff19caabbe..00000000000 --- a/doc/user/admin_area/settings/project_integration_management.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/project_integration_management.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../../administration/settings/project_integration_management.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md deleted file mode 100644 index 519d035244a..00000000000 --- a/doc/user/admin_area/settings/protected_paths.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/protected_paths.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/protected_paths.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md deleted file mode 100644 index b7e059cf820..00000000000 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/push_event_activities_limit.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/push_event_activities_limit.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md deleted file mode 100644 index aca30177c54..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_issues_creation.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_issues_creation.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md deleted file mode 100644 index 6d5c93f8554..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_notes_creation.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_notes_creation.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md deleted file mode 100644 index c469a77f7d2..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_pipelines_creation.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_pipelines_creation.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_projects_api.md b/doc/user/admin_area/settings/rate_limit_on_projects_api.md deleted file mode 100644 index 12577ba44b1..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_projects_api.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_projects_api.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_projects_api.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_users_api.md b/doc/user/admin_area/settings/rate_limit_on_users_api.md deleted file mode 100644 index 80acbf21023..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_users_api.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_users_api.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_users_api.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md b/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md deleted file mode 100644 index b60a78d1f49..00000000000 --- a/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limits_on_git_ssh_operations.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limits_on_git_ssh_operations.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md deleted file mode 100644 index 5cfee536a58..00000000000 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limits_on_raw_endpoints.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limits_on_raw_endpoints.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/scim_setup.md b/doc/user/admin_area/settings/scim_setup.md deleted file mode 100644 index 4ebd8a84f8a..00000000000 --- a/doc/user/admin_area/settings/scim_setup.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/scim_setup.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/scim_setup.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/security_and_compliance.md b/doc/user/admin_area/settings/security_and_compliance.md deleted file mode 100644 index 8c1e514c575..00000000000 --- a/doc/user/admin_area/settings/security_and_compliance.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/security_and_compliance.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/security_and_compliance.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md deleted file mode 100644 index 81be26ec8e0..00000000000 --- a/doc/user/admin_area/settings/sidekiq_job_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/sidekiq_job_limits.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/sidekiq_job_limits.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md deleted file mode 100644 index c3957ed97eb..00000000000 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/sign_in_restrictions.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/sign_in_restrictions.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md deleted file mode 100644 index 553caa9ff0d..00000000000 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/sign_up_restrictions.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/sign_up_restrictions.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/slack_app.md b/doc/user/admin_area/settings/slack_app.md deleted file mode 100644 index 86762edd1a9..00000000000 --- a/doc/user/admin_area/settings/slack_app.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/slack_app.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/slack_app.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md deleted file mode 100644 index 444eeeb15ea..00000000000 --- a/doc/user/admin_area/settings/terms.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/terms.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/terms.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/terraform_limits.md b/doc/user/admin_area/settings/terraform_limits.md deleted file mode 100644 index 8fed7589bb7..00000000000 --- a/doc/user/admin_area/settings/terraform_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/terraform_limits.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/terraform_limits.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md deleted file mode 100644 index 54c5b36bbc0..00000000000 --- a/doc/user/admin_area/settings/third_party_offers.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/third_party_offers.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/third_party_offers.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md deleted file mode 100644 index 5b2afd3ad90..00000000000 --- a/doc/user/admin_area/settings/usage_statistics.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/usage_statistics.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/usage_statistics.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md deleted file mode 100644 index fae47358879..00000000000 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/user_and_ip_rate_limits.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/user_and_ip_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md deleted file mode 100644 index c9ff105f8c9..00000000000 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/visibility_and_access_controls.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/visibility_and_access_controls.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md deleted file mode 100644 index b0b4facd7db..00000000000 --- a/doc/user/admin_area/user_cohorts.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/user_cohorts.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/user_cohorts.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md index 222752a4561..71b5617a4a9 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -1,8 +1,7 @@ --- stage: AI-powered group: AI Model Validation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Duo @@ -13,22 +12,23 @@ type: index, reference GitLab is creating AI-assisted features across our DevSecOps platform. These features aim to help increase velocity and solve key pain points across the software development lifecycle. -| Feature | Purpose | Large Language Model | Current availability | Maturity | -|-|-|-|-|-| -| [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | Assists in creating faster and higher-quality reviews by automatically suggesting reviewers for your merge request. | GitLab creates a machine learning model for each project, which is used to generate reviewers <br><br> [View the issue](https://gitlab.com/gitlab-org/modelops/applied-ml/applied-ml-updates/-/issues/10) | SaaS only <br><br> Ultimate tier | [Generally Available (GA)](../policy/experiment-beta-support.md#generally-available-ga) | -| [Code Suggestions](project/repository/code_suggestions/index.md) | Helps you write code more efficiently by viewing code suggestions as you type. | For Code Completion: Vertex AI Codey [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion) <br><br> For Code Generation: Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model)| [SaaS: All tiers](project/repository/code_suggestions/saas.md) <br><br> [Self-managed: Premium and Ultimate with Cloud Licensing](project/repository/code_suggestions/self_managed.md) | [Beta](../policy/experiment-beta-support.md#beta) | -| [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | Helps you remediate vulnerabilities more efficiently, boost your skills, and write more secure code. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) <br><br> Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) if degraded performance | SaaS only <br><br> Ultimate tier | [Beta](../policy/experiment-beta-support.md#beta) | -| [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | Helps you understand code by explaining it in English language. | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [GitLab Duo Chat](gitlab_duo_chat.md) | Process and generate text and code in a conversational manner. Helps you quickly identify useful information in large volumes of text in issues, epics, code, and GitLab documentation. | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) <br><br> Vertex AI Codey [`textembedding-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | Assists you with predicting productivity metrics and identifying anomalies across your software development lifecycle. | Statistical forecasting | SaaS only <br> Self-managed <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | Assists with quickly getting everyone up to speed on lengthy conversations to help ensure you are all on the same page. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Merge request summary](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) | Efficiently communicate the impact of your merge request changes. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Code review summary](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) | Helps ease merge request handoff between authors and reviewers and help reviewers efficiently understand suggestions. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | Generate a description for the merge request based on the contents of the template. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | Automates repetitive tasks and helps catch bugs early. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | Helps you discover or recall Git commands when and where you need them. | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Root cause analysis](#root-cause-analysis) | Assists you in determining the root cause for a pipeline failure and failed CI/CD build. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Issue description generation](#summarize-an-issue-with-issue-description-generation) | Generate issue descriptions. | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | +| Goal | Feature | Tier/Offering/Status | +|---|---|---| +| Helps you discover or recall Git commands when and where you need them. | [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | **(ULTIMATE SAAS EXPERIMENT)** | +| Assists with quickly getting everyone up to speed on lengthy conversations to help ensure you are all on the same page. | [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | **(ULTIMATE SAAS EXPERIMENT)** | +| Generates issue descriptions. | [Issue description generation](#summarize-an-issue-with-issue-description-generation) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps you write code more efficiently by viewing code suggestions as you type. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=hCAyCTacdAQ) | [Code Suggestions](project/repository/code_suggestions/index.md) | For SaaS: **(FREE BETA)**<br><br> For self-managed: **(ULTIMATE BETA)** | +| Automates repetitive tasks and helps catch bugs early. | [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | **(ULTIMATE SAAS EXPERIMENT)** | +| Generates a description for the merge request based on the contents of the template. | [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | **(ULTIMATE SAAS EXPERIMENT)** | +| Assists in creating faster and higher-quality reviews by automatically suggesting reviewers for your merge request. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=ivwZQgh4Rxw) | [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | **(ULTIMATE SAAS)** | +| Efficiently communicates the impact of your merge request changes. | [Merge request summary](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps ease merge request handoff between authors and reviewers and help reviewers efficiently understand suggestions. | [Code review summary](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps you remediate vulnerabilities more efficiently, boost your skills, and write more secure code. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=6sDf73QOav8) | [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | **(ULTIMATE SAAS BETA)** | +| Generates a merge request containing the changes required to mitigate a vulnerability. | [Vulnerability resolution](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps you understand code by explaining it in English language. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=1izKaLmmaCA) | [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | **(ULTIMATE SAAS EXPERIMENT)** | +| Processes and generates text and code in a conversational manner. Helps you quickly identify useful information in large volumes of text in issues, epics, code, and GitLab documentation. | [GitLab Duo Chat](gitlab_duo_chat.md) | **(ULTIMATE SAAS BETA)** | +| Assists you in determining the root cause for a pipeline failure and failed CI/CD build. | [Root cause analysis](#root-cause-analysis) | **(ULTIMATE SAAS EXPERIMENT)** | +| Assists you with predicting productivity metrics and identifying anomalies across your software development lifecycle. | [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | **(ULTIMATE ALL EXPERIMENT)** | ## Enable AI/ML features @@ -82,7 +82,7 @@ You can also have code explained in the context of a merge request. To explain code in a merge request: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Code > Merge requests**, then select your merge request. +1. Select **Code > Merge requests**, then select your merge request. 1. On the secondary menu, select **Changes**. 1. On the file you would like explained, select the three dots (**{ellipsis_v}**) and select **View File @ $SHA**. @@ -182,9 +182,29 @@ Provide feedback on this experimental feature in [issue 409844](https://gitlab.c **Data usage**: When you use this feature, the text you enter is sent to the large language model referenced above. -### GitLab Duo Chat **(ULTIMATE SAAS EXPERIMENT)** - -For details about this Experimental feature, see [GitLab Duo Chat](gitlab_duo_chat.md). +### GitLab Duo Chat **(ULTIMATE SAAS BETA)** + +For details about this Beta feature, see [GitLab Duo Chat](gitlab_duo_chat.md). + +## Language models + +| Feature | Large Language Model | +|---|---| +| [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | +| [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Issue description generation](#summarize-an-issue-with-issue-description-generation) | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) | +| [Code Suggestions](project/repository/code_suggestions/index.md) | For Code Completion: Vertex AI Codey [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion) For Code Generation: Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) | +| [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | GitLab creates a machine learning model for each project, which is used to generate reviewers [View the issue](https://gitlab.com/gitlab-org/modelops/applied-ml/applied-ml-updates/-/issues/10) | +| [Merge request summary](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Code review summary](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) if degraded performance | +| [Vulnerability resolution](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | Vertex AI Codey [`code-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-generation) | +| [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | +| [GitLab Duo Chat](gitlab_duo_chat.md) | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) Vertex AI Codey [`textembedding-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings) | +| [Root cause analysis](#root-cause-analysis) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | Statistical forecasting | ## Data usage @@ -209,7 +229,7 @@ The below reflects the current retention periods of GitLab AI model [Sub-Process - Anthropic retains input and output data for 30 days. - Google discards input and output data immediately after the output is provided. Google currently does not store data for abuse monitoring. -All of these AI providers are under data protection agreements with GitLab that prohibit the use of Customer Content for their own purposes, except to perform their independent legal obligations. +All of these AI providers are under data protection agreements with GitLab that prohibit the use of Customer Content for their own purposes, except to perform their independent legal obligations. ### Telemetry diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index 8bed8018eb8..0699be4e0ad 100644 --- a/doc/user/analytics/analytics_dashboards.md +++ b/doc/user/analytics/analytics_dashboards.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Analytics dashboards **(ULTIMATE ALL EXPERIMENT)** @@ -64,12 +64,8 @@ Your dashboard files are versioned in source control with the rest of a project' ## Dashboard designer -> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/411407) in GitLab 16.6. Feature flag `combined_analytics_dashboards_editor` removed. You can use the dashboard designer to: @@ -81,12 +77,8 @@ You can use the dashboard designer to: ## Visualization designer -> Introduced in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - Introduced in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425048) in GitLab 16.7. Feature flag `combined_analytics_visualization_editor` removed. NOTE: This feature is only compatible with the [product analytics](../product_analytics/index.md) data source. @@ -98,7 +90,7 @@ You can use the dashboard designer to: ## View project dashboards -Prerequisite: +Prerequisites: - You must have at least the Developer role for the project. @@ -108,6 +100,60 @@ To view a list of dashboards (both built-in and custom) for a project: 1. Select **Analyze > Analytics dashboards**. 1. From the list of available dashboards, select the dashboard you want to view. +### View the value streams dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137483) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `project_analytics_dashboard_dynamic_vsd`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards` and `project_analytics_dashboard_dynamic_vsd`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the project. +- Overview background aggregation for Value Streams Dashboards must be enabled. + +To view the Value Streams Dashboard as an analytics dashboard for a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Analytics dashboards**. +1. From the list of available dashboards, select **Value Streams Dashboard**. + +## View group dashboards + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390542) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the group. + +To view a list of dashboards (both built-in and custom) for a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Analyze > Analytics dashboards**. +1. From the list of available dashboards, select the dashboard you want to view. + +### View the value streams dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132839) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboard_dynamic_vsd`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboard_dynamic_vsd`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +To view the Value Streams Dashboard as an analytics dashboard for a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Analyze > Analytics dashboards**. +1. From the list of available dashboards, select **Value Streams Dashboard**. + ## Change the location of dashboards You can change the location of your project or group dashboards. @@ -231,7 +277,7 @@ To create a custom visualization: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Analytics dashboards**. -1. Select **Visualization Designer**. +1. Select **Visualization designer**. 1. In the **Visualization title** field, enter the name of your visualization. 1. From the **Visualization type** dropdown list, select a visualization type. 1. In the **What metric do you want to visualize?** section, select the metric you want to query. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 61bc77e4469..360559fad60 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD analytics **(FREE ALL)** @@ -30,6 +30,17 @@ View pipeline duration history: ## View CI/CD analytics +You can view CI/CD analytics for a group or project. + +### For a group **(ULTIMATE ALL)** + +To view CI/CD analytics: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Analyze > CI/CD analytics**. + +### For a project **(FREE ALL)** + To view CI/CD analytics: 1. On the left sidebar, select **Search or go to** and find your project. @@ -44,7 +55,7 @@ frequency to the `production` environment. The environment must be part of the [production deployment tier](../../ci/environments/index.md#deployment-tier-of-environments) for its deployment information to appear on the graphs. - Deployment frequency is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. +Deployment frequency is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. The deployment frequency chart is available for groups and projects. @@ -68,7 +79,7 @@ merge requests to be deployed to a production environment. This chart is availab - For time periods in which no merge requests were deployed, the charts render a red, dashed line. - Lead time for changes is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. +Lead time for changes is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. To view the lead time for changes chart: diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index e5b475d0e45..43c6d381874 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -2,7 +2,7 @@ description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code review analytics **(PREMIUM ALL)** @@ -24,11 +24,11 @@ and improve your code review process. - Few comments and approvers may indicate a lack of available team members. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video explanation, see [Code review analytics: Faster code review](https://www.youtube.com/watch?v=OkLaWhYkASM). +For a video explanation, see [Code review analytics: Faster code review](https://www.youtube.com/watch?v=849o0XD991M). ## View code review analytics -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/user/analytics/contributor_analytics.md b/doc/user/analytics/contributor_analytics.md new file mode 100644 index 00000000000..26dd79533a3 --- /dev/null +++ b/doc/user/analytics/contributor_analytics.md @@ -0,0 +1,48 @@ +--- +stage: Plan +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Contributor analytics **(FREE ALL)** + +Contributor analytics give you an overview of the commits made by projects members to a project over time. + +## View contributor analytics + +The contributor analytics page displays a line chart with the number of commits to the selected project branch over time, +and line charts with the number of commits by each project member. + +To view contributor analytics for a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Contributor analytics**. +1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. +1. To view the number of commits made on a specific day, hover over the line chart. +1. Optional. To display commits only for a specific time period, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: + + - To change the start date, slide the left pause icon to the left or right. + - To change the end date, slide the right pause icon to the left or right. + +## View project commit history + +To view a list of commits made by project members per day: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Contributor analytics**. +1. Select **History**. +1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. +1. To view the number of commits made by the members on a specific day, hover over the line chart. +1. Optional. Filter the results. + + - To filter by author, from the **Author** dropdown list, select the user whose commits you want to view. + - To filter by commit message, in the text box, enter your search criteria. + +## Retrieve project commits as an RSS feed + +To view the list of commits to the project as an RSS feed in Atom format: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Contributor analytics**. +1. Select **History**. +1. In the upper-right corner, select the feed symbol (**{rss}**). diff --git a/doc/user/analytics/contributor_statistics.md b/doc/user/analytics/contributor_statistics.md index ee10522e80b..b6f195e22ad 100644 --- a/doc/user/analytics/contributor_statistics.md +++ b/doc/user/analytics/contributor_statistics.md @@ -1,48 +1,11 @@ --- -stage: Plan -group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'contributor_analytics.md' +remove_date: '2023-03-06' --- -# Contributor statistics **(FREE ALL)** +This document was moved to [another location](contributor_analytics.md). -Contributor statistics give you an overview of the commits made by projects members to a project over time. - -## View contributor statistics - -The contributor statistics page displays a line chart with the number of commits to the selected project branch over time, -and line charts with the number of commits by each project member. - -To view contributor statistics for a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Analyze > Contributor statistics**. -1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. -1. To view the number of commits made on a specific day, hover over the line chart. -1. Optional. To display commits only for a specific time period, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: - - - To change the start date, slide the left pause icon to the left or right. - - To change the end date, slide the right pause icon to the left or right. - -## View project commit history - -To view a list of commits made by project members per day: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Analyze > Contributor statistics**. -1. Select **History**. -1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. -1. To view the number of commits made by the members on a specific day, hover over the line chart. -1. Optional. Filter the results. - - - To filter by author, from the **Author** dropdown list, select the user whose commits you want to view. - - To filter by commit message, in the text box, enter your search criteria. - -## Retrieve project commits as an RSS feed - -To view the list of commits to the project as an RSS feed in Atom format: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Analyze > Contributor statistics**. -1. Select **History**. -1. In the upper-right corner, select the feed symbol (**{rss}**). +<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index e90bfd690ca..53a25acbca5 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DevOps Research and Assessment (DORA) metrics **(ULTIMATE ALL)** @@ -21,14 +21,14 @@ DORA includes four key metrics, divided into two core areas of DevOps: For software leaders, tracking velocity alongside quality metrics ensures they're not sacrificing quality for speed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video explanation, see [DORA metrics: User analytics](https://www.youtube.com/watch?v=lM_FbVYuN8s) and [GitLab speed run: DORA metrics](https://www.youtube.com/watch?v=1BrcMV6rCDw). +For a video explanation, see [DORA metrics: User analytics](https://www.youtube.com/watch?v=jYQSH4EY6_U) and [GitLab speed run: DORA metrics](https://www.youtube.com/watch?v=1BrcMV6rCDw). ## DORA metrics in Value Stream Analytics The four DORA metrics are available out-of-the-box in the [Value Streams Dashboard](value_streams_dashboard.md). This helps you visualize the engineering work in the context of end-to-end value delivery. -The One DevOps Platform [Value Stream Management](https://gitlab.com/gitlab-org/gitlab/-/value_stream_analytics) provides end-to-end visibility to the entire software delivery lifecycle. +The One DevOps Platform [Value Stream Management](https://gitlab.com/gitlab-org/gitlab/-/value_stream_analytics) provides end-to-end visibility into the entire software delivery lifecycle. This enables teams and managers to understand all aspects of productivity, quality, and delivery, without the ["toolchain tax"](https://about.gitlab.com/solutions/value-stream-management/). ## Deployment frequency @@ -42,7 +42,7 @@ High deployment frequency means you can get feedback sooner and iterate faster t ### How deployment frequency is calculated -In GitLab, Deployment frequency is measured by the average number of deployments per day to a given environment, based on the deployment's end time (its `finished_at` property). +In GitLab, deployment frequency is measured by the average number of deployments per day to a given environment, based on the deployment's end time (its `finished_at` property). GitLab calculates the deployment frequency from the number of finished deployments on the given day. Only successful deployments (`Deployment.statuses = success`) are counted. The calculation takes into account the production `environment tier` or the environments named `production/prod`. The environment must be part of the production deployment tier for its deployment information to appear on the graphs. @@ -51,28 +51,29 @@ The calculation takes into account the production `environment tier` or the envi The first step is to benchmark the cadence of code releases between groups and projects. Next, you should consider: -- Add more automated testing. -- Add more automated code validation. -- Break the changes down into smaller iterations. +- Adding automated testing. +- Adding automated code validation. +- Breaking the changes down into smaller iterations. ## Lead time for changes Lead time for changes is the amount of time it takes a code change to get into production. -"Lead time for changes" is not the same as "Lead time". In the value stream, "Lead time" measures the time it takes for work on an issue to move from the moment it's requested (Issue created) to the moment it's fulfilled and delivered (Issue closed). +**Lead time for changes** is not the same as **Lead time**. In the value stream, lead time measures the time it takes for work on an issue to move from the moment it's requested (Issue created) to the moment it's fulfilled and delivered (Issue closed). -For software leaders, Lead time for changes reflects the efficiency of CI/CD pipelines and visualizes how quickly work is delivered to customers. +For software leaders, lead time for changes reflects the efficiency of CI/CD pipelines and visualizes how quickly work is delivered to customers. Over time, the lead time for changes should decrease, while your team's performance should increase. Low lead time for changes means more efficient CI/CD pipelines. -In GitLab, Lead time for changes is measure by the `Median time it takes for a merge request to get merged into production (from master)`. -By default, Lead time for changes measures only one-branch operations with multiple deployment jobs (for example, jobs moving from development to staging to production jobs on the main branch). +In GitLab, lead time for changes is measured by the `Median time it takes for a merge request to get merged into production (from master)`. + +By default, lead time for changes measures only one-branch operations with multiple deployment jobs (for example, jobs moving from development to staging to production jobs on the main branch). When a merge request gets merged in staging and then merge to production, GitLab processes them as two deployed merge requests, not one. ### How lead time for changes is calculated -GitLab calculates Lead time for changes based on the number of seconds to successfully deliver a commit into production - **from** code committed **to** code successfully running in production, without adding the `coding_time` to the calculation. +GitLab calculates lead time for changes based on the number of seconds to successfully deliver a commit into production - **from** code committed **to** code successfully running in production, without adding the `coding_time` to the calculation. -By default, Lead time for changes supports measuring only one branch operation with multiple deployment jobs (for example, from development to staging to production on the default branch). When a merge request gets merged on staging, and then on production, GitLab interprets them as two deployed merge requests, not one. +By default, lead time for changes supports measuring only one branch operation with multiple deployment jobs (for example, from development to staging to production on the default branch). When a merge request gets merged on staging, and then on production, GitLab interprets them as two deployed merge requests, not one. ### How to improve lead time for changes @@ -80,18 +81,18 @@ The first step is to benchmark the CI/CD pipelines' efficiency between groups an - Using Value Stream Analytics to identify bottlenecks in the processes. - Breaking the changes down into smaller iterations. -- Adding more automation. +- Adding automation. ## Time to restore service Time to restore service is the amount of time it takes an organization to recover from a failure in production. -For software leaders, Time to restore service reflects how long it takes an organization to recover from a failure in production. -Low Time to restore service means the organization can take risks with new innovative features to drive competitive advantages and increase business results. +For software leaders, time to restore service reflects how long it takes an organization to recover from a failure in production. +Low time to restore service means the organization can take risks with new innovative features to drive competitive advantages and increase business results. ### How time to restore service is calculated -In GitLab, Time to restore service is measured as the median time an incident was open for on a production environment. +In GitLab, time to restore service is measured as the median time an incident was open for on a production environment. GitLab calculates the number of seconds an incident was open on a production environment in the given time period. This assumes: - [GitLab incidents](../../operations/incident_management/incidents.md) are tracked. @@ -114,8 +115,8 @@ High change failure rate may indicate an inefficient deployment process or insuf ### How change failure rate is calculated -In GitLab, Change failure rate is measured as the percentage of deployments that cause an incident in production in the given time period. -GitLab calculates this by the number of incidents divided by the number of deployments to a production environment. This assumes: +In GitLab, change failure rate is measured as the percentage of deployments that cause an incident in production in the given time period. +GitLab calculates this as the number of incidents divided by the number of deployments to a production environment. This assumes: - [GitLab incidents](../../operations/incident_management/incidents.md) are tracked. - All incidents are related to a production environment. @@ -124,13 +125,11 @@ more than one incident. ### How to improve change failure rate -The first step is to benchmark the quality and stability, between groups and projects. - -To improve this metric, you should consider: +The first step is to benchmark the quality and stability, between groups and projects. Next, you should consider: - Finding the right balance between stability and throughput (Deployment frequency and Lead time for changes), and not sacrificing quality for speed. - Improving the efficacy of code review processes. -- Adding more automated testing. +- Adding automated testing. ## DORA custom calculation rules **(ULTIMATE ALL EXPERIMENT)** @@ -140,14 +139,14 @@ FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `dora_configuration`. On GitLab.com, this feature is not available. -This feature is an [Experiment](../../policy/experiment-beta-support.md). +This feature is an [Experiment](../../policy/experiment-beta-support.md). To join the list of users testing this feature, [here is a suggested test flow](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96561#steps-to-check-on-localhost). If you find a bug, [open an issue here](https://gitlab.com/groups/gitlab-org/-/epics/11490). To share your use cases and feedback, comment in [epic 11490](https://gitlab.com/groups/gitlab-org/-/epics/11490). -### DORA Lead Time For Changes - multi-branch rule +### Multi-branch rule for lead time for changes -Unlike the default [calculation of Lead time for changes](#how-lead-time-for-changes-is-calculated), this calculation rule allows measuring multi-branch operations with a single deployment job for each operation. +Unlike the default [calculation of lead time for changes](#how-lead-time-for-changes-is-calculated), this calculation rule allows measuring multi-branch operations with a single deployment job for each operation. For example, from development job on development branch, to staging job on staging branch, to production job on production branch. This calculation rule has been implemented by updating the `dora_configurations` table with the target branches that are part of the development flow. @@ -167,23 +166,22 @@ Dora::Configuration.create!(project: my_project, ltfc_target_branches: \['master To retrieve DORA data, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs. +## Measure DORA metrics + ### Measure DORA metrics without using GitLab CI/CD pipelines Deployment frequency is calculated based on the deployments record, which is created for typical push-based deployments. These deployment records are not created for pull-based deployments, for example when Container Images are connected to GitLab with an agent. -To track DORA metrics in these cases, you can [create a deployment record](../../api/deployments.md#create-a-deployment) using the Deployments API. See also the documentation page for [Track deployments of an external deployment tool](../../ci/environments/external_deployment_tools.md). +To track DORA metrics in these cases, you can [create a deployment record](../../api/deployments.md#create-a-deployment) using the Deployments API. For more information, see [Track deployments of an external deployment tool](../../ci/environments/external_deployment_tools.md). ### Measure DORA metrics with Jira -- Deployment frequency and Lead time for changes are calculated based on GitLab CI/CD and Merge Requests (MRs), and do not require Jira data. -- Time to restore service and Change failure rate require GitLab incidents for the calculation. For more information, see [Measure DORA Time to restore service and Change failure rate with external incidents](#measure-dora-time-to-restore-service-and-change-failure-rate-with-external-incidents). +- Deployment frequency and lead time for changes are calculated based on GitLab CI/CD and Merge Requests (MRs), and do not require Jira data. +- Time to restore service and change failure rate require [GitLab incidents](../../operations/incident_management/manage_incidents.md) for the calculation. For more information, see [Measure DORA Time to restore service and Change failure rate with external incidents](#measure-dora-time-to-restore-service-and-change-failure-rate-with-external-incidents). ### Measure DORA Time to restore service and Change failure rate with external incidents -[Time to restore service](#time-to-restore-service) and [Change failure rate](#change-failure-rate) -require [GitLab incidents](../../operations/incident_management/manage_incidents.md) to calculate the metrics. - For PagerDuty, you can set up a [webhook to automatically create a GitLab incident for each PagerDuty incident](../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook). This configuration requires you to make changes in both PagerDuty and GitLab. diff --git a/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png b/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png Binary files differnew file mode 100644 index 00000000000..519e56acaa5 --- /dev/null +++ b/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png diff --git a/doc/user/analytics/img/issues_closed_analytics_v16_4.png b/doc/user/analytics/img/issues_closed_analytics_v16_4.png Binary files differdeleted file mode 100644 index 5e1fe4eaa8c..00000000000 --- a/doc/user/analytics/img/issues_closed_analytics_v16_4.png +++ /dev/null diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index f096d1e2882..d58426bd76b 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,13 +1,13 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Analyze GitLab usage **(FREE ALL)** GitLab provides different types of analytics insights at the instance, group, and project level. -These insights appear on the left sidebar, under [**Analyze**](../project/settings/index.md#disable-project-analytics). +These insights appear on the left sidebar, under [**Analyze**](../project/settings/project_features_permissions.md#disable-project-analytics). ## Instance-level analytics @@ -33,12 +33,11 @@ Use group-level analytics to get insights into your groups': Use project-level analytics to get insights into your projects': -- [Analytics dashboards](analytics_dashboards.md), enabled with the `combined_analytics_dashboards_editor` - [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) +- [Analytics dashboards](analytics_dashboards.md) - [Security Dashboards](../application_security/security_dashboard/index.md) - [CI/CD analytics and DORA metrics](ci_cd_analytics.md) - [Code review analytics](code_review_analytics.md) -- [Contributor statistics](../../user/analytics/contributor_statistics.md) +- [Contributor analytics](../../user/analytics/contributor_analytics.md) - [Insights](../project/insights/index.md) - [Issue analytics](../../user/analytics/issue_analytics.md) - [Merge request analytics](merge_request_analytics.md), enabled with the `project_merge_request_analytics` diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 8f29c008d75..b8aa23a0af2 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue analytics for projects **(PREMIUM ALL)** @@ -50,7 +49,7 @@ available. This feature is not ready for production use. Enhanced issue analytics display the additional metric "Issues closed", which represents the total number of resolved issues in your project over a selected period. You can use this metric to improve the overall turn-around time and value delivered to your customers. - + ## Drill into the information diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 0f8eb9ac211..5b5b1ec002d 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -2,7 +2,7 @@ description: "Merge request analytics help you understand the efficiency of your code review process, and the productivity of your team." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request analytics **(PREMIUM ALL)** @@ -23,7 +23,7 @@ You can use merge request analytics to identify: ## View merge request analytics -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index a17eb08c53c..2644f8466c0 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Productivity analytics **(PREMIUM ALL)** @@ -22,14 +22,14 @@ To view merge request data for projects, use [Merge request analytics](../analyt ## View productivity analytics -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the group. 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. 1. Optional. Filter results: - 1. Select a project from the dropdown list. + 1. From the **Projects** dropdown list, select a project. 1. To filter results by author, milestone, or label, select **Filter results...** and enter a value. 1. To adjust the date range: @@ -38,19 +38,16 @@ Prerequisite: ## View time metrics for merge requests -Use the following charts in productivity analytics to view the velocity of your merge requests: - -- **Time to merge**: number of days it took for a -merge requests to merge after they were created. -- **Trendline**: number of merge requests that were merged in a specific time period. +To view time metrics for merge requests: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. - -To filter time metrics: - -1. To filter the **Trendline** chart, in the **Time to merge** chart, select a column. -1. To view a specific merge request, below the charts, select a merge request from the **List**. + Time metrics are displayed on the following charts: + - **Time to merge**: number of days it took for a merge requests to merge after they were created. + - **Trendline**: number of merge requests that were merged in a specific time period. +1. Optional. Filter the results: + - To filter the **Trendline** chart, in the **Time to merge** chart, select a bar. + - To view a specific merge request, below the charts, from the **List** table select a merge request. ## View commit statistics @@ -58,11 +55,9 @@ To view commit statistics for your group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. -1. Under the **Trendline** scatterplot, view the commit statistics: + Commit statistics are displayed under the **Trendline** scatterplot: - The left histogram shows the number of hours between commits, comments, and merges. - The right histogram shows the number of commits and changes per merge request. - -To filter commit statistics: - -1. To view different types of commit data, select the dropdown list next to each histogram. -1. To view a specific merge request, below the charts, select a merge request from the **List**. +1. Optional. Filter results: + - To view different types of commit data, from the dropdown list next to each histogram, select an option. + - To view a specific merge request, below the charts, from the **List** table select a merge request. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 26bce8a20c2..93171dc3136 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository analytics for projects **(FREE ALL)** diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index b5358cc81c8..a50eab42a2d 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Value Streams Dashboard **(ULTIMATE ALL)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Released in GitLab 15.11 as an Open [Beta](../../policy/experiment-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392734) in GitLab 16.0. Feature flag `group_analytics_dashboards_page` removed. -To help us improve the Value Streams Dashboard, please share feedback about your experience in this [survey](https://gitlab.fra1.qualtrics.com/jfe/form/SV_50guMGNU2HhLeT4). +To help us improve the Value Streams Dashboard, share feedback about your experience in this [survey](https://gitlab.fra1.qualtrics.com/jfe/form/SV_50guMGNU2HhLeT4). For more information, see also the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). The Value Streams Dashboard is a customizable dashboard you can use to identify trends, patterns, and opportunities for digital transformation improvements. @@ -29,6 +29,8 @@ With the Value Streams Dashboard, you can: - Understand security exposure. - Drill down into individual projects or metrics to take actions for improvement. +The Value Streams Dashboard has a default configuration, but you can also [customize the dashboard panels](#customize-the-dashboard-panels). + ## DevSecOps metrics comparison panel The DevSecOps metrics comparison displays DORA4, vulnerability, and flow metrics for a group or project in the @@ -71,6 +73,21 @@ For example, if a project has a high score for Deployment Frequency (Velocity), These scoring are based on Google's classifications in the [DORA 2022 Accelerate State of DevOps Report](https://cloud.google.com/blog/products/devops-sre/dora-2022-accelerate-state-of-devops-report-now-out). +### Filter by project topics + +When used in combination with a [YAML configuration](#using-yaml-configuration), you can filter the projects shown based on their assigned [topics](../project/settings/project_features_permissions.md#project-topics). + +```yaml +panels: + - data: + namespace: group/my-custom-group + filter_project_topics: + - JavaScript + - Vue.js +``` + +If multiple topics are provided, all topics will need to match for the project to be included in the results. + ## Enable or disable overview background aggregation **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120610) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `modify_value_stream_dashboard_settings`. Disabled by default. @@ -81,7 +98,7 @@ On self-managed GitLab, by default this feature is available. To hide the featur On GitLab.com, this feature is not available. This feature is not ready for production use. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. @@ -96,7 +113,7 @@ To retrieve aggregated usage counts in the group, use the [GraphQL API](../../ap ## View the value streams dashboard -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the group. - Overview background aggregation for Value Streams Dashboards must be enabled. @@ -115,6 +132,8 @@ To view the value streams dashboard: 1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. 1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL (for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards/value_streams_dashboard`). +You can also view the Value Streams Dashboard rendered as an analytics dashboard for a [group](analytics_dashboards.md#view-group-dashboards) or [project](analytics_dashboards.md#view-project-dashboards). + ## Customize the dashboard panels You can customize the Value Streams Dashboard and configure what subgroups and projects to include in the page. @@ -136,7 +155,7 @@ Query parameters can still be used to override the YAML configuration. First, you need to set up the project. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the group. @@ -203,6 +222,7 @@ panels: For an overview of editing label filters in the configuration file, see [GitLab Value Streams Dashboard - Label filters demo](https://www.youtube.com/watch?v=4qDAHCxCfik). Label filters are appended as query parameters to the URL of the drill-down report of each eligible metric and automatically applied. +If the comparison panel from the configuration file is enabled with `filter_labels`, the drill-down links inherit the labels from the panel filter. ## Dashboard metrics and drill-down reports diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index b82ea30b463..9c16c70c78f 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # HTTP Archive format **(ULTIMATE ALL)** diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 1bac636ac3f..735b2356780 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web API Fuzz Testing **(ULTIMATE ALL)** @@ -2724,7 +2723,7 @@ ERROR: Job failed: failed to pull image "registry.example.com/my-target-app:late **Solution** -Authentication credentials are provided using the methods outlined in the [Access an image from a private Container Registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a third party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. +Authentication credentials are provided using the methods outlined in the [Access an image from a private container registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a third party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. The following example uses the [statically defined credentials](../../../ci/docker/using_docker_images.md#use-statically-defined-credentials) authentication method. In this example the container registry is `registry.example.com` and image is `my-target-app:latest`. diff --git a/doc/user/application_security/api_security/api_discovery/index.md b/doc/user/application_security/api_security/api_discovery/index.md index 0d7bb2830e9..3e1e9d5bfc7 100644 --- a/doc/user/application_security/api_security/api_discovery/index.md +++ b/doc/user/application_security/api_security/api_discovery/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # API Discovery **(ULTIMATE ALL)** diff --git a/doc/user/application_security/api_security/index.md b/doc/user/application_security/api_security/index.md index 37549d5db51..da771b03335 100644 --- a/doc/user/application_security/api_security/index.md +++ b/doc/user/application_security/api_security/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # API Security **(ULTIMATE ALL)** diff --git a/doc/user/application_security/breach_and_attack_simulation/index.md b/doc/user/application_security/breach_and_attack_simulation/index.md index dab625bc169..61b9c8af59b 100644 --- a/doc/user/application_security/breach_and_attack_simulation/index.md +++ b/doc/user/application_security/breach_and_attack_simulation/index.md @@ -2,7 +2,6 @@ stage: Secure group: Incubation info: Breach and Attack Simulation is a GitLab Incubation Engineering program. No technical writer assigned to this group. -type: reference, howto --- # Breach and Attack Simulation **(ULTIMATE ALL)** @@ -91,7 +90,7 @@ To enable Breach and Attack Simulation features inside of an existing DAST job: extends: .dast_with_bas ``` -1. Disable the `dast+job` job included in the BAS template by setting `DAST_BAS_DISABLED`: +1. Disable the `dast_with_bas` job included in the BAS template by setting `DAST_BAS_DISABLED`: ```yaml variables: @@ -129,6 +128,9 @@ Perform Out-of-Band Application Security Testing (OAST) for certain [active chec services: # NOTE: services overwrites rather than merges so it must be referenced to merge. - !reference [.dast_with_bas_using_services, services] + # NOTE: Link your application container to the dast job and + # access it with the hostname yourapp. See more about Docker services at + # https://docs.gitlab.com/ee/user/application_security/dast/#docker-services - name: $CI_REGISTRY_IMAGE alias: yourapp ``` diff --git a/doc/user/application_security/comparison_dependency_and_container_scanning.md b/doc/user/application_security/comparison_dependency_and_container_scanning.md index d02d94b7a3e..43f7c04f99b 100644 --- a/doc/user/application_security/comparison_dependency_and_container_scanning.md +++ b/doc/user/application_security/comparison_dependency_and_container_scanning.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Scanning compared to Container Scanning diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 98b91ce584d..008b5b54cca 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Security configuration **(FREE ALL)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index ac03f08e23b..8af262e564b 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Container Scanning **(FREE ALL)** @@ -263,17 +262,17 @@ including a large number of false positives. | `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_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | +| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `CS_IGNORE_STATUSES` | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | | `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | -| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | -| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, and `CRITICAL`. | Trivy | | `CS_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | +| `CS_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | +| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | 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_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | -| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | -| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | 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 | | `CS_TRIVY_JAVA_DB` | `"ghcr.io/aquasecurity/trivy-java-db"` | Specify an alternate location for the [trivy-java-db](https://github.com/aquasecurity/trivy-java-db) vulnerability database. | Trivy | -| `CS_IGNORE_STATUSES` | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. | All | ### Supported distributions @@ -534,7 +533,7 @@ To use container scanning in an offline environment, you need: - To configure a local Docker container registry with copies of the container scanning images. You can find these images in their respective registries: -| GitLab Analyzer | Container Registry | +| GitLab Analyzer | Container registry | | --- | --- | | [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) | [Container-Scanning container registry](https://gitlab.com/security-products/container-scanning/container_registry/) | @@ -671,7 +670,10 @@ mirror trivy java db: - oras push $CI_REGISTRY_IMAGE:1 --config /dev/null:application/vnd.aquasec.trivy.config.v1+json javadb.tar.gz:application/vnd.aquasec.trivy.javadb.layer.v1.tar+gzip ``` -If the above container registry is `gitlab.example.com/trivy-java-db-mirror`, then the container scanning job should be configured in the following way: +The vulnerability database is not a regular Docker image, so it is not possible to pull it by using `docker pull`. +The image shows an error if you navigate to it in the GitLab UI. + +If the above container registry is `gitlab.example.com/trivy-java-db-mirror`, then the container scanning job should be configured in the following way. Do not add the tag `:1` at the end, it is added by `trivy`: ```yaml include: @@ -679,7 +681,7 @@ include: container_scanning: variables: - CS_TRIVY_JAVA_DB: gitlab.example.com/trivy-java-db-mirror:1 + CS_TRIVY_JAVA_DB: gitlab.example.com/trivy-java-db-mirror ``` ## Running the standalone container scanning tool diff --git a/doc/user/application_security/continuous_vulnerability_scanning/index.md b/doc/user/application_security/continuous_vulnerability_scanning/index.md index e31fc5f7eb0..4d6d48012ae 100644 --- a/doc/user/application_security/continuous_vulnerability_scanning/index.md +++ b/doc/user/application_security/continuous_vulnerability_scanning/index.md @@ -1,16 +1,13 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Continuous Vulnerability Scanning **(ULTIMATE EXPERIMENT)** +# Continuous Vulnerability Scanning **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) in GitLab 16.4 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) with two [features flags](../../../administration/feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. Enabled by default. - -NOTE: -This feature is an [Experiment](../../../policy/experiment-beta-support.md#experiment) and subject to change without notice. -If you have any feedback, you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/425072). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) in GitLab 16.4 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) with two [features flags](../../../administration/feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427424) in GitLab 16.7 with an additional feature flag named `global_dependency_scanning_on_advisory_ingestion`. Enabled by default. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flags](../../feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. @@ -27,9 +24,8 @@ Continuous Vulnerability Scanning detects vulnerabilities in the latest CycloneD To enable Continuous Vulnerability Scanning: -- Enable the Continuous Vulnerability Scanning setting in the project's [security configuration](../configuration/index.md). - Enable [Dependency Scanning](../dependency_scanning/index.md#configuration) and ensure that its prerequisites are met. -- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then please refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. +- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. ### Running in an offline environment diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 599203dedcc..8972d659c26 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Coverage-guided fuzz testing **(ULTIMATE ALL)** diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index bbe97081a55..efa1003fb4a 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -1,8 +1,7 @@ --- -type: tutorial stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CVE ID request **(FREE SAAS)** diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index c245361a731..854526c4235 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST authentication **(ULTIMATE ALL)** @@ -53,7 +52,7 @@ To run a DAST authenticated scan: #### Form authentication - You are using either the [DAST proxy-based analyzer](proxy-based.md) or the [DAST browser-based analyzer](browser_based.md). -- You know the URL of the login form of your application. Alternatively, you know how to go to the login form from the authentication URL (see [clicking to go to the login form](#clicking-to-go-to-the-login-form)). +- You know the URL of the login form of your application. Alternatively, you know how to go to the login form from the authentication URL (see [clicking to go to the login form](#click-to-go-to-the-login-form)). - You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST uses to input the respective values. - You know the element's [selector](#finding-an-elements-selector) that submits the login form when selected. @@ -81,6 +80,7 @@ To run a DAST authenticated scan: | `DAST_USERNAME` <sup>1</sup> | string | The username to authenticate to in the website. Example: `admin` | | `DAST_USERNAME_FIELD` <sup>1</sup> | [selector](#finding-an-elements-selector) | A selector describing the element used to enter the username on the login form. Example: `name:username` | | `DAST_AUTH_DISABLE_CLEAR_FIELDS` | boolean | Disables clearing of username and password fields before attempting manual login. Set to `false` by default. | +| `DAST_AFTER_LOGIN_ACTIONS` | string | Comma separated list of actions to be run after login but before login verification. Currently supports "click" actions. Example: `click(on=id:change_to_bar_graph),click(on=css:input[name=username])` | | 1. Available to an on-demand proxy-based DAST scan. 1. Not available to proxy-based scans. @@ -192,7 +192,7 @@ authentication using the [single-step](#configuration-for-a-single-step-login-fo DAST supports authentication processes where a user is redirected to an external Identity Provider's site to log in. Check the [known limitations](#known-limitations) of DAST authentication to determine if your SSO authentication process is supported. -### Clicking to go to the login form +### Click to go to the login form Define `DAST_BROWSER_PATH_TO_LOGIN_FORM` to provide a path of elements to click on from the `DAST_AUTH_URL` so that DAST can access the login form. This method is suitable for applications that show the login form in a pop-up (modal) window or when the login form does not @@ -211,6 +211,25 @@ dast: DAST_BROWSER_PATH_TO_LOGIN_FORM: "css:.navigation-menu,css:.login-menu-item" ``` +### Perform additional actions after submitting the username and password + +Define `DAST_AFTER_LOGIN_ACTIONS` to provide a sequence of actions required to complete the login process after the username and password forms have been submitted. For example, this can be used to dismiss a modal dialog (such as a "keep me signed in?" prompt) that appears after the submit button is pressed. + +DAST verifies authentication is successful and records authentication tokens once after-login actions have been executed. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_AUTH_URL: "https://example.com/login" + DAST_AFTER_LOGIN_ACTIONS: "click(on=id:modal-yes)" +``` + ### Excluding logout URLs If DAST crawls the logout URL while running an authenticated scan, the user is logged out, resulting in the remainder of the scan being unauthenticated. @@ -385,191 +404,4 @@ dast: ## Troubleshooting -The [logs](#read-the-logs) provide insight into what DAST is doing and expecting during the authentication process. For more detailed -information, configure the [authentication report](#configure-the-authentication-report). - -For more information about particular error messages or situations see [known problems](#known-problems). - -The browser-based analyzer is used to authenticate the user. For advanced troubleshooting, see [browser-based troubleshooting](browser_based_troubleshooting.md). - -### Read the logs - -The console output of the DAST CI/CD job shows information about the authentication process using the `AUTH` log module. -For example, the following log shows failed authentication for a multi-step login form. -Authentication failed because a home page should be displayed after login. Instead, the login form was still present. - -```plaintext -2022-11-16T13:43:02.000 INF AUTH attempting to authenticate -2022-11-16T13:43:02.000 INF AUTH loading login page LoginURL=https://example.com/login -2022-11-16T13:43:10.000 INF AUTH multi-step authentication detected -2022-11-16T13:43:15.000 INF AUTH verifying if user submit was successful true_when="HTTP status code < 400" -2022-11-16T13:43:15.000 INF AUTH requirement is satisfied, no login HTTP message detected want="HTTP status code < 400" -2022-11-16T13:43:20.000 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" -2022-11-24T14:43:20.000 INF AUTH requirement is satisfied, HTTP login request returned status code 200 url=https://example.com/user/login?error=invalid%20credentials want="HTTP status code < 400" -2022-11-16T13:43:21.000 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" -2022-11-16T13:43:21.000 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" -``` - -### Configure the authentication report - -WARNING: -The authentication report can contain sensitive information such as the credentials used to perform the login. - -An authentication report can be saved as a CI/CD job artifact to assist with understanding the cause of an authentication failure. - -The report contains steps performed during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots. - - - -An example configuration where the authentication debug report is exported may look like the following: - -```yaml -dast: - variables: - DAST_WEBSITE: "https://example.com" - DAST_AUTH_REPORT: "true" - artifacts: - paths: [gl-dast-debug-auth-report.html] - when: always -``` - -### Known problems - -#### Login form not found - -DAST failed to find a login form when loading the login page, often because the authentication URL could not be loaded. -The log reports a fatal error such as: - -```plaintext -2022-12-07T12:44:02.838 INF AUTH loading login page LoginURL=[authentication URL] -2022-12-07T12:44:11.119 FTL MAIN authentication failed: login form not found -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) to inspect HTTP response. -- Check the target application authentication is deployed and running. -- Check the `DAST_AUTH_URL` is correct. -- Check the GitLab Runner can access the `DAST_AUTH_URL`. -- Check the `DAST_BROWSER_PATH_TO_LOGIN_FORM` is valid if used. - -#### Scan doesn't crawl authenticated pages - -If DAST captures the wrong [authentication tokens](#authentication-tokens) during the authentication process then -the scan can't crawl authenticated pages. Names of cookies and storage authentication tokens are written to the log. For example: - -```plaintext -2022-11-24T14:42:31.492 INF AUTH authentication token cookies names=["sessionID"] -2022-11-24T14:42:31.492 INF AUTH authentication token storage events keys=["token"] -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. -- Verify the logged authentication tokens are those used by your application. -- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. - -#### Unable to find elements with selector - -DAST failed to find the username, password, first submit button, or submit button elements. The log reports a fatal error such as: - -```plaintext -2022-12-07T13:14:11.545 FTL MAIN authentication failed: unable to find elements with selector: css:#username -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) to use the screenshot from the `Login page` to verify that the page loaded correctly. -- Load the login page in a browser and verify the [selectors](#finding-an-elements-selector) configured in `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, and `DAST_SUBMIT_FIELD` are correct. - -#### Failed to authenticate user - -DAST failed to authenticate due to a failed login verification check. The log reports a fatal error such as: - -```plaintext -2022-12-07T06:39:49.483 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" -2022-12-07T06:39:49.484 INF AUTH requirement is satisfied, HTTP login request returned status code 303 url=http://auth-manual:8090/login want="HTTP status code < 400" -2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" -2022-12-07T06:39:49.589 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" -2022-12-07T06:39:53.626 FTL MAIN authentication failed: failed to authenticate user -``` - -Suggested actions: - -- Look in the log for the `requirement is unsatisfied`. Respond to the appropriate error. - -#### Requirement unsatisfied, login form was found - -Applications typically display a dashboard when the user logs in and the login form with an error message when the -username or password is incorrect. - -This error occurs when DAST detects the login form on the page displayed after authenticating the user, -indicating that the login attempt failed. - -```plaintext -2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" -``` - -Suggested actions: - -- Verify that the username and password/authentication credentials used are correct. -- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. -- It's possible that the authentication report `Login submit` request and response are empty. This occurs when there is no request that would result - in a full page reload, such as a request made when submitting a HTML form. This occurs when using websockets or AJAX to submit the login form. -- If the page displayed following user authentication genuinely has elements matching the login form selectors, configure `DAST_AUTH_VERIFICATION_URL` - or `DAST_AUTH_VERIFICATION_SELECTOR` to use an alternate method of verifying the login attempt. - -#### Requirement unsatisfied, selector returned no results - -DAST cannot find an element matching the selector provided in `DAST_AUTH_VERIFICATION_SELECTOR` on the page displayed following user login. - -```plaintext -2022-12-07T06:39:33.239 INF AUTH requirement is unsatisfied, searching DOM using selector returned no results want="has element css:[name=welcome]" -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. -- Ensure the `DAST_AUTH_VERIFICATION_SELECTOR` [selector](#finding-an-elements-selector) is correct. - -#### Requirement unsatisfied, browser not at URL - -DAST detected that the page displayed following user login has a URL different to what was expected according to `DAST_AUTH_VERIFICATION_URL`. - -```plaintext -2022-12-07T11:28:00.241 INF AUTH requirement is unsatisfied, browser is not at URL browser_url="https://example.com/home" want="is at url https://example.com/user/dashboard" -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. -- Ensure the `DAST_AUTH_VERIFICATION_URL` is correct. - -#### Requirement unsatisfied, HTTP login request status code - -The HTTP response when loading the login form or submitting the form had a status code of 400 (client error) -or 500 (server error). - -```plaintext -2022-12-07T06:39:53.626 INF AUTH requirement is unsatisfied, HTTP login request returned status code 502 url="https://example.com/user/login" want="HTTP status code < 400" -``` - -- Verify that the username and password/authentication credentials used are correct. -- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. -- Verify the target application works as expected. - -#### Requirement unsatisfied, no authentication token - -DAST could not detect an [authentication token](#authentication-tokens) created during the authentication process. - -```plaintext -2022-12-07T11:25:29.010 INF AUTH authentication token cookies names=[] -2022-12-07T11:25:29.010 INF AUTH authentication token storage events keys=[] -2022-12-07T11:25:29.010 INF AUTH requirement is unsatisfied, no basic authentication, cookie or storage event authentication token detected want="has authentication token" -``` - -Suggestion actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. -- Using the browser's developer tools, investigate the cookies and local/session storage objects created while logging in. Ensure there is an authentication token created with sufficiently random value. -- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. +See [troubleshooting](authentication_troubleshooting.md) for more information. diff --git a/doc/user/application_security/dast/authentication_troubleshooting.md b/doc/user/application_security/dast/authentication_troubleshooting.md new file mode 100644 index 00000000000..62894d89ff6 --- /dev/null +++ b/doc/user/application_security/dast/authentication_troubleshooting.md @@ -0,0 +1,196 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting **(ULTIMATE ALL)** + +The [logs](#read-the-logs) provide insight into what DAST is doing and expecting during the authentication process. For more detailed +information, configure the [authentication report](#configure-the-authentication-report). + +For more information about particular error messages or situations see [known problems](#known-problems). + +The browser-based analyzer is used to authenticate the user. For advanced troubleshooting, see [browser-based troubleshooting](browser_based_troubleshooting.md). + +## Read the logs + +The console output of the DAST CI/CD job shows information about the authentication process using the `AUTH` log module. +For example, the following log shows failed authentication for a multi-step login form. +Authentication failed because a home page should be displayed after login. Instead, the login form was still present. + +```plaintext +2022-11-16T13:43:02.000 INF AUTH attempting to authenticate +2022-11-16T13:43:02.000 INF AUTH loading login page LoginURL=https://example.com/login +2022-11-16T13:43:10.000 INF AUTH multi-step authentication detected +2022-11-16T13:43:15.000 INF AUTH verifying if user submit was successful true_when="HTTP status code < 400" +2022-11-16T13:43:15.000 INF AUTH requirement is satisfied, no login HTTP message detected want="HTTP status code < 400" +2022-11-16T13:43:20.000 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" +2022-11-24T14:43:20.000 INF AUTH requirement is satisfied, HTTP login request returned status code 200 url=https://example.com/user/login?error=invalid%20credentials want="HTTP status code < 400" +2022-11-16T13:43:21.000 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" +2022-11-16T13:43:21.000 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" +``` + +## Configure the authentication report + +WARNING: +The authentication report can contain sensitive information such as the credentials used to perform the login. + +An authentication report can be saved as a CI/CD job artifact to assist with understanding the cause of an authentication failure. + +The report contains steps performed during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots. + + + +An example configuration where the authentication debug report is exported may look like the following: + +```yaml +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_AUTH_REPORT: "true" + artifacts: + paths: [gl-dast-debug-auth-report.html] + when: always +``` + +## Known problems + +### Login form not found + +DAST failed to find a login form when loading the login page, often because the authentication URL could not be loaded. +The log reports a fatal error such as: + +```plaintext +2022-12-07T12:44:02.838 INF AUTH loading login page LoginURL=[authentication URL] +2022-12-07T12:44:11.119 FTL MAIN authentication failed: login form not found +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) to inspect HTTP response. +- Check the target application authentication is deployed and running. +- Check the `DAST_AUTH_URL` is correct. +- Check the GitLab Runner can access the `DAST_AUTH_URL`. +- Check the `DAST_BROWSER_PATH_TO_LOGIN_FORM` is valid if used. + +### Scan doesn't crawl authenticated pages + +If DAST captures the wrong [authentication tokens](authentication.md#authentication-tokens) during the authentication process then +the scan can't crawl authenticated pages. Names of cookies and storage authentication tokens are written to the log. For example: + +```plaintext +2022-11-24T14:42:31.492 INF AUTH authentication token cookies names=["sessionID"] +2022-11-24T14:42:31.492 INF AUTH authentication token storage events keys=["token"] +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. +- Verify the logged authentication tokens are those used by your application. +- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. + +### Unable to find elements with selector + +DAST failed to find the username, password, first submit button, or submit button elements. The log reports a fatal error such as: + +```plaintext +2022-12-07T13:14:11.545 FTL MAIN authentication failed: unable to find elements with selector: css:#username +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) to use the screenshot from the `Login page` to verify that the page loaded correctly. +- Load the login page in a browser and verify the [selectors](authentication.md#finding-an-elements-selector) configured in `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, and `DAST_SUBMIT_FIELD` are correct. + +### Failed to authenticate user + +DAST failed to authenticate due to a failed login verification check. The log reports a fatal error such as: + +```plaintext +2022-12-07T06:39:49.483 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" +2022-12-07T06:39:49.484 INF AUTH requirement is satisfied, HTTP login request returned status code 303 url=http://auth-manual:8090/login want="HTTP status code < 400" +2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" +2022-12-07T06:39:49.589 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" +2022-12-07T06:39:53.626 FTL MAIN authentication failed: failed to authenticate user +``` + +Suggested actions: + +- Look in the log for the `requirement is unsatisfied`. Respond to the appropriate error. + +### Requirement unsatisfied, login form was found + +Applications typically display a dashboard when the user logs in and the login form with an error message when the +username or password is incorrect. + +This error occurs when DAST detects the login form on the page displayed after authenticating the user, +indicating that the login attempt failed. + +```plaintext +2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" +``` + +Suggested actions: + +- Verify that the username and password/authentication credentials used are correct. +- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. +- It's possible that the authentication report `Login submit` request and response are empty. This occurs when there is no request that would result + in a full page reload, such as a request made when submitting a HTML form. This occurs when using websockets or AJAX to submit the login form. +- If the page displayed following user authentication genuinely has elements matching the login form selectors, configure `DAST_AUTH_VERIFICATION_URL` + or `DAST_AUTH_VERIFICATION_SELECTOR` to use an alternate method of verifying the login attempt. + +### Requirement unsatisfied, selector returned no results + +DAST cannot find an element matching the selector provided in `DAST_AUTH_VERIFICATION_SELECTOR` on the page displayed following user login. + +```plaintext +2022-12-07T06:39:33.239 INF AUTH requirement is unsatisfied, searching DOM using selector returned no results want="has element css:[name=welcome]" +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. +- Ensure the `DAST_AUTH_VERIFICATION_SELECTOR` [selector](authentication.md#finding-an-elements-selector) is correct. + +### Requirement unsatisfied, browser not at URL + +DAST detected that the page displayed following user login has a URL different to what was expected according to `DAST_AUTH_VERIFICATION_URL`. + +```plaintext +2022-12-07T11:28:00.241 INF AUTH requirement is unsatisfied, browser is not at URL browser_url="https://example.com/home" want="is at url https://example.com/user/dashboard" +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. +- Ensure the `DAST_AUTH_VERIFICATION_URL` is correct. + +### Requirement unsatisfied, HTTP login request status code + +The HTTP response when loading the login form or submitting the form had a status code of 400 (client error) +or 500 (server error). + +```plaintext +2022-12-07T06:39:53.626 INF AUTH requirement is unsatisfied, HTTP login request returned status code 502 url="https://example.com/user/login" want="HTTP status code < 400" +``` + +- Verify that the username and password/authentication credentials used are correct. +- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. +- Verify the target application works as expected. + +### Requirement unsatisfied, no authentication token + +DAST could not detect an [authentication token](authentication.md#authentication-tokens) created during the authentication process. + +```plaintext +2022-12-07T11:25:29.010 INF AUTH authentication token cookies names=[] +2022-12-07T11:25:29.010 INF AUTH authentication token storage events keys=[] +2022-12-07T11:25:29.010 INF AUTH requirement is unsatisfied, no basic authentication, cookie or storage event authentication token detected want="has authentication token" +``` + +Suggestion actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. +- Using the browser's developer tools, investigate the cookies and local/session storage objects created while logging in. Ensure there is an authentication token created with sufficiently random value. +- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 207db52ed71..c0d71a95f91 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST browser-based analyzer **(ULTIMATE ALL)** @@ -90,7 +89,7 @@ A simplified timing attack works as follows: Active scans do not use a browser to send HTTP requests in an effort to minimize scan time. -Anti-CSRF tokens are not regenerated for attacks that submit forms. Please disable anti-CSRF tokens when running an active scan. +Anti-CSRF tokens are not regenerated for attacks that submit forms. Disable anti-CSRF tokens when running an active scan. ## Getting started diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index 446cd0aaa92..9572c472284 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting DAST browser-based analyzer **(ULTIMATE ALL)** diff --git a/doc/user/application_security/dast/checks/1336.1.md b/doc/user/application_security/dast/checks/1336.1.md new file mode 100644 index 00000000000..d20a67d34d4 --- /dev/null +++ b/doc/user/application_security/dast/checks/1336.1.md @@ -0,0 +1,32 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# Server-Side Template Injection + +## Description + +The application is vulnerable to Server-Side Template Injection (SSTI), which enables attackers to +manipulate templates on the server side. This vulnerability arises when untrusted user input is +directly used in server-side templates without adequate sanitization. Attackers can exploit this +weakness to inject and execute arbitrary code in templates, potentially compromising the +system's integrity and confidentiality. + +## Remediation + +User-controlled data should always have special elements neutralized when used as part of +constructing Expression Language statements. Consult the documentation for the template +system in use on how properly neutralize user-controlled data. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 1336.1 | false | 1336 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/1336.html) +- [Testing for Server-side Template Injection](https://owasp.org/www-project-web-security-testing-guide/stable/4-Web_Application_Security_Testing/07-Input_Validation_Testing/18-Testing_for_Server-side_Template_Injection) diff --git a/doc/user/application_security/dast/checks/16.11.md b/doc/user/application_security/dast/checks/16.11.md new file mode 100644 index 00000000000..cdc0bd4e271 --- /dev/null +++ b/doc/user/application_security/dast/checks/16.11.md @@ -0,0 +1,40 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# TRACE HTTP method enabled + +## Description + +The debug TRACE method was found to be enabled on the target web server. This +HTTP method reflects HTTP request data back to the user in a response. In some circumstances +this information may include sensitive data that is applied by intermediary proxies. + +## Remediation + +The TRACE HTTP method is for debugging only and should not be enabled on production +sites. + +For Apache based web servers, ensure the `TraceEnable` directive is either removed or set to +`off`. + +For Microsoft Servers, remove the registry parameter named "EnableTraceMethod" found in the below +registry key: + +- `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters` + +For all other server types, consult your product's documentation on how to disable the TRACE method. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.11 | false | 16 | Active | high | + +## Links + +- [RFC](https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.8) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) +- [Apache TraceEnable](https://httpd.apache.org/docs/2.4/mod/core.html#traceenable) diff --git a/doc/user/application_security/dast/checks/16.2.md b/doc/user/application_security/dast/checks/16.2.md index 2051b118009..fe6a882e3c4 100644 --- a/doc/user/application_security/dast/checks/16.2.md +++ b/doc/user/application_security/dast/checks/16.2.md @@ -27,7 +27,7 @@ IIS: For IIS based websites version 10 and above you can use the `removeServerHeader` element to the `requestFiltering` section of the `Web.config` file. -For all other server types, please consult your product's documentation on how to redact the version information from +For all other server types, consult your product's documentation on how to redact the version information from the `Server` header. ## Details diff --git a/doc/user/application_security/dast/checks/16.3.md b/doc/user/application_security/dast/checks/16.3.md index d1799baa517..3179be7d691 100644 --- a/doc/user/application_security/dast/checks/16.3.md +++ b/doc/user/application_security/dast/checks/16.3.md @@ -20,7 +20,7 @@ We recommend that the version information be removed from the `X-Powered-By` hea PHP: For PHP based web sites, set the `expose_php` option to `off` in the `php.ini` configuration file. -For all other server types, please consult your product's documentation on how to redact the version +For all other server types, consult your product's documentation on how to redact the version information from the `X-Powered-By` header. ## Details diff --git a/doc/user/application_security/dast/checks/16.8.md b/doc/user/application_security/dast/checks/16.8.md index b8faef75de7..816bc8bd873 100644 --- a/doc/user/application_security/dast/checks/16.8.md +++ b/doc/user/application_security/dast/checks/16.8.md @@ -13,7 +13,7 @@ hardening a website against various client side attacks such as Cross-Site Scrip ## Remediation -If the target site is missing a CSP, please investigate the relevant URLs for enabling CSP. Otherwise, +If the target site is missing a CSP, investigate the relevant URLs for enabling CSP. Otherwise, follow the recommendations to determine if any actions are necessary. ## Details diff --git a/doc/user/application_security/dast/checks/548.1.md b/doc/user/application_security/dast/checks/548.1.md index 6cef8ccdb63..3bef3bdc744 100644 --- a/doc/user/application_security/dast/checks/548.1.md +++ b/doc/user/application_security/dast/checks/548.1.md @@ -28,7 +28,7 @@ IIS: For IIS based websites version 7.0 and above you can use the `<directoryBrowse enabled="false" />` element in the `applicationHost.config` or `Web.config` files. -For all other server types, please consult your product's documentation on how to disable directory +For all other server types, Consult your product's documentation on how to disable directory indexing. ## Details diff --git a/doc/user/application_security/dast/checks/74.1.md b/doc/user/application_security/dast/checks/74.1.md new file mode 100644 index 00000000000..f7f37f3f1c7 --- /dev/null +++ b/doc/user/application_security/dast/checks/74.1.md @@ -0,0 +1,31 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# XSLT Injection + +## Description + +It is possible to supply an XSL template to a server-side XSLT processor. XSLT processors can +be abused to read or write files, initiate outbound connections, and in some cases execute +arbitrary code. + +## Remediation + +Applications should never accept user-supplied style sheets. XSLT processors are not built to +handle potentially malicious stylesheet files. However, some processors do implement or offer +security features which may be available. Consult the documentation for the XSLT processor +used by the target application for security guidelines and hardening steps. It is recommended +that all XML parsers and processors at the very least disable external entity resolution. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 74.1 | false | 74 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/74.html) diff --git a/doc/user/application_security/dast/checks/78.1.md b/doc/user/application_security/dast/checks/78.1.md new file mode 100644 index 00000000000..bcb655f37ae --- /dev/null +++ b/doc/user/application_security/dast/checks/78.1.md @@ -0,0 +1,44 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# OS Command Injection + +## Description + +It is possible to execute arbitrary OS commands on the target application server. +OS Command Injection is a critical vulnerability that can lead to a full system +compromise. + +## Remediation + +User input should never be used in constructing commands or command arguments +to functions which execute OS commands. This includes filenames supplied by +user uploads or downloads. + +Ensure your application does not: + +- Use user-supplied information in the process name to execute. +- Use user-supplied information in an OS command execution function which does +not escape shell meta-characters. +- Use user-supplied information in arguments to OS commands. + +The application should have a hardcoded set of arguments that are to be passed +to OS commands. If file names are being passed to these functions, it is +recommended that a hash of the file name be used instead, or some other unique +identifier. It is strongly recommended that a native library that implements +the same functionality be used instead of using OS system commands due to the +risk of unknown attacks against third party commands. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 78.1 | false | 78 | Active | high | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/Command_Injection) +- [CWE](https://cwe.mitre.org/data/definitions/78.html) diff --git a/doc/user/application_security/dast/checks/89.1.md b/doc/user/application_security/dast/checks/89.1.md index ca7ff5e4593..688e2c49664 100644 --- a/doc/user/application_security/dast/checks/89.1.md +++ b/doc/user/application_security/dast/checks/89.1.md @@ -20,7 +20,7 @@ situations where dynamic queries must be created, never use direct user input, b instead use a map or dictionary of valid values and resolve them using a user-supplied key. For example, some database drivers do not allow parameterized queries for `>` or `<` comparison -operators. In these cases, do not use a user supplied `>` or `<` value, but rather have the user +operators. In these cases, do not use a user-supplied `>` or `<` value, but rather have the user supply a `gt` or `lt` value. The alphabetical values are then used to look up the `>` and `<` values to be used in the construction of the dynamic query. The same goes for other queries where column or table names are required but can not be parameterized. diff --git a/doc/user/application_security/dast/checks/917.1.md b/doc/user/application_security/dast/checks/917.1.md index 68b9665e393..853407afe30 100644 --- a/doc/user/application_security/dast/checks/917.1.md +++ b/doc/user/application_security/dast/checks/917.1.md @@ -17,7 +17,7 @@ intended EL statement prior to it being executed by an interpreter. ## Remediation User-controlled data should always have special elements neutralized when used as part of -constructing Expression Language statements. Please consult the documentation for the EL +constructing Expression Language statements. Consult the documentation for the EL interpreter in use on how properly neutralize user controlled data. ## Details diff --git a/doc/user/application_security/dast/checks/918.1.md b/doc/user/application_security/dast/checks/918.1.md new file mode 100644 index 00000000000..88a8a632547 --- /dev/null +++ b/doc/user/application_security/dast/checks/918.1.md @@ -0,0 +1,33 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# Server-Side Request Forgery + +## Description + +The application is susceptible to Server-Side Request Forgery (SSRF), a high-risk vulnerability +that allows attackers to make unauthorized requests to internal and external resources. This +vulnerability arises when user-controlled input is not properly validated or sanitized before +being used in requests to resources, enabling attackers to manipulate these requests for +malicious purposes. + +## Remediation + +Avoid using user-supplied data for constructing requests. If there is a business need for this, +consider an allowlist approach and/or block requests to internal resources using firewall +rules or a robust request library with anti-SSRF support. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 918.1 | false | 918 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/918.html) +- [OWASP](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery) +- [Server-Side Request Forgery Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html) diff --git a/doc/user/application_security/dast/checks/94.2.md b/doc/user/application_security/dast/checks/94.2.md index 666052807b5..d6e7c5f482f 100644 --- a/doc/user/application_security/dast/checks/94.2.md +++ b/doc/user/application_security/dast/checks/94.2.md @@ -15,10 +15,10 @@ stored secrets, injecting code to take over accounts, or executing OS commands. ## Remediation Never pass user input directly into functions which evaluate string data as code, such as `eval`, -`send`, `public_send`, `instance_eval` or `class_eval`. There is almost no benefit of passing string +`send`, `public_send`, `instance_eval` or `class_eval`. There is almost no benefit of passing string values to these methods, as such the best recommendation is to replace the current logic with more safe implementations of dynamically evaluating logic with user input. If using `send` or `public_send` ensure -the first argument is to a known, hardcoded method/symbol and does not come from user input. +the first argument is to a known, hardcoded method/symbol and does not come from user input. For `eval`, `instance_eval` and `class_eval`, user input should never be sent directly to these methods. One alternative is to store functions or methods in a Hash that can be looked up using a key. If the key diff --git a/doc/user/application_security/dast/checks/98.1.md b/doc/user/application_security/dast/checks/98.1.md new file mode 100644 index 00000000000..b30147f7969 --- /dev/null +++ b/doc/user/application_security/dast/checks/98.1.md @@ -0,0 +1,34 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# PHP Remote File Inclusion + +## Description + +The server is vulnerable to PHP Remote File Inclusion (RFI), which enables attackers to load +remote files and have them executed as PHP scripts on the server side. This vulnerability occurs +when untrusted user input is directly used in script inclusion without proper validation. Attackers +can leverage this vulnerability to include and execute arbitrary remote files, potentially +compromising the system's integrity and confidentiality. + +## Remediation + +Avoid using user-controlled data directly in `include` and `require` statements and instead consider +an allow-list approach for dynamically including scripts. + +If possible, also consider setting `allow_url_include=Off` in the server's PHP configuration to +ensure URLs cannot be used in `include` and `require` statements. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 98.1 | false | 98 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/98.html) +- [File inclusion Vulnerability - Wikipedia](https://en.wikipedia.org/wiki/File_inclusion_vulnerability) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index c239fdb5e74..0a4b16aaa1d 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -168,12 +168,18 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | ID | Check | Severity | Type | |:---|:------|:---------|:-----| | [113.1](113.1.md) | Improper Neutralization of CRLF Sequences in HTTP Headers | High | Active | +| [1336.1](1336.1.md) | Server-Side Template Injection | High | Active | +| [16.11](16.11.md) | TRACE HTTP method enabled | High | Active | | [22.1](22.1.md) | Improper limitation of a pathname to a restricted directory (Path traversal) | High | Active | | [611.1](611.1.md) | External XML Entity Injection (XXE) | High | Active | +| [74.1](74.1.md) | XSLT Injection | High | Active | +| [78.1](78.1.md) | OS Command Injection | High | Active | | [89.1](89.1.md) | SQL Injection | High | Active | | [917.1](917.1.md) | Expression Language Injection | High | Active | +| [918.1](918.1.md) | Server-Side Request Forgery | High | Active | | [94.1](94.1.md) | Server-side code injection (PHP) | High | Active | | [94.2](94.2.md) | Server-side code injection (Ruby) | High | Active | | [94.3](94.3.md) | Server-side code injection (Python) | High | Active | | [94.4](94.4.md) | Server-side code injection (NodeJS) | High | Active | | [943.1](943.1.md) | Improper neutralization of special elements in data query logic | High | Active | +| [98.1](98.1.md) | PHP Remote File Inclusion | High | Active | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 08f819e020c..9df98176c9a 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting DAST proxy-based analyzer **(ULTIMATE ALL)** diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 4ec693593fb..45b879dc53f 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dynamic Application Security Testing (DAST) **(ULTIMATE ALL)** diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 9e59ecc64d9..6127866b0a9 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -1,12 +1,16 @@ --- 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/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST proxy-based analyzer **(ULTIMATE ALL)** +WARNING: +Proxy-based DAST is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966). +We plan to [remove support for Proxy-based DAST](../../../update/deprecations.md#proxy-based-dast-deprecated). Migrate to [Browser-based DAST](browser_based.md) +to continue analyzing your projects for security findings via dynamic analysis. + The DAST proxy-based analyzer can be added to your [GitLab CI/CD](../../../ci/index.md) pipeline. This helps you discover vulnerabilities in web applications that do not use JavaScript heavily. For applications that do, see the [DAST browser-based analyzer](browser_based.md). diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 0101749be71..ac597c99b62 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run DAST in an offline environment **(ULTIMATE ALL)** @@ -16,7 +15,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](index.md#prerequisites). -- Docker Container Registry with a locally available copy of the DAST +- Docker container registry with a locally available copy of the DAST [container image](https://gitlab.com/security-products/dast), found in the [DAST container registry](https://gitlab.com/security-products/dast/container_registry). diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index ffa2e063535..df8fbff720b 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST API analyzer **(ULTIMATE ALL)** @@ -2600,7 +2599,7 @@ ERROR: Job failed: failed to pull image "registry.example.com/my-target-app:late **Solution** -Authentication credentials are provided using the methods outlined in the [Access an image from a private Container Registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a 3rd party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. +Authentication credentials are provided using the methods outlined in the [Access an image from a private container registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a 3rd party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. The following example uses the [statically defined credentials](../../../ci/docker/using_docker_images.md#use-statically-defined-credentials) authentication method. In this example the container registry is `registry.example.com` and image is `my-target-app:latest`. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 91145b10f81..7f4806a89f1 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency list **(ULTIMATE ALL)** @@ -38,7 +37,7 @@ To view your project's dependencies, ensure you meet the following requirements: To view the dependencies of a project or all projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Secure > Dependency list**. Details of each dependency are listed, sorted by decreasing severity of vulnerabilities (if any). You can sort the list instead by component name or packager. @@ -62,14 +61,38 @@ Details of each dependency are listed, sorted by decreasing severity of vulnerab  -### Vulnerabilities +## Filter dependency list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422356) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies_filtering`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies_filtering`. +On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. + +In the group-level dependency list you can filter by: + +- Project +- License + +To filter the dependency list: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Secure > Dependency list**. +1. Select the filter bar. +1. Select a filter, then from the dropdown list select one or more criteria. + To close the dropdown list, select outside of it. To add more filters, repeat this step. +1. To apply the selected filters, press <kbd>Enter</kbd>. + +The dependency list shows only dependencies that match your filters. + +## Vulnerabilities If a dependency has known vulnerabilities, view them by selecting the arrow next to the dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description appears below it. To view more details of a vulnerability, select the vulnerability's description. The [vulnerability's details](../vulnerabilities) page is opened. -### Dependency paths +## Dependency paths The dependency list shows the path between a dependency and a top-level dependency it's connected to, if any. Multiple paths may connect a transient dependency to top-level @@ -99,6 +122,6 @@ list shows only the results of the last successful pipeline that ran on the defa To download the dependency list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Secure > Dependency list**. 1. Select **Export**. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md deleted file mode 100644 index 0d7d495ba49..00000000000 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-09-22' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-09-22>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 683ba6ad19b..9d898ec0266 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,9 +1,46 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- +<style> +table.ds-table tr:nth-child(even) { + background-color: transparent; +} + +table.ds-table td { + border-left: 1px solid #dbdbdb; + border-right: 1px solid #dbdbdb; + border-bottom: 1px solid #dbdbdb; +} + +table.ds-table tr td:first-child { + border-left: 0; +} + +table.ds-table tr td:last-child { + border-right: 0; +} + +table.ds-table ul { + font-size: 1em; + list-style-type: none; + padding-left: 0px; + margin-bottom: 0px; +} + +table.no-vertical-table-lines td { + border-left: none; + border-right: none; + border-bottom: 1px solid #f0f0f0; +} + +table.no-vertical-table-lines tr { + border-top: none; +} +</style> + # Dependency Scanning **(ULTIMATE ALL)** Dependency Scanning analyzes your application's dependencies for known vulnerabilities. All @@ -42,35 +79,8 @@ For other interactive reading and how-to demos, see [Get Started With GitLab App The following languages and dependency managers are supported: -<style> -table.supported-languages tr:nth-child(even) { - background-color: transparent; -} - -table.supported-languages td { - border-left: 1px solid #dbdbdb; - border-right: 1px solid #dbdbdb; - border-bottom: 1px solid #dbdbdb; -} - -table.supported-languages tr td:first-child { - border-left: 0; -} - -table.supported-languages tr td:last-child { - border-right: 0; -} - -table.supported-languages ul { - font-size: 1em; - list-style-type: none; - padding-left: 0px; - margin-bottom: 0px; -} -</style> - <!-- markdownlint-disable MD044 --> -<table class="supported-languages"> +<table class="ds-table"> <thead> <tr> <th>Language</th> @@ -322,19 +332,88 @@ GitLab analyzers obtain dependency information using one of the following two me The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: -| Package Manager | Supported File Format Versions | Tested Package Manager Versions | -| ------ | ------ | ------ | -| Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | -| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | -| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | -| NuGet | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | -| pnpm | v5, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | -| yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup> | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2), [2.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock), [3.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock) | -| Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | - <!-- markdownlint-disable MD044 --> +<table class="ds-table no-vertical-table-lines"> + <thead> + <tr> + <th>Package Manager</th> + <th>Supported File Format Versions</th> + <th>Tested Package Manager Versions</th> + </tr> + </thead> + <tbody> + <tr> + <td>Bundler</td> + <td>Not applicable</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118">1.17.3</a>, + <a href="https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118">2.1.4</a> + </td> + </tr> + <tr> + <td>Composer</td> + <td>Not applicable</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock">1.x</a> + </td> + </tr> + <tr> + <td>Conan</td> + <td>0.4</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38">1.x</a> + </td> + </tr> + <tr> + <td>Go</td> + <td>Not applicable</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum">1.x</a><sup><b><a href="#notes-regarding-parsing-lockfiles-1">1</a></b></sup> + </td> + </tr> + <tr> + <td>NuGet</td> + <td>v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2">4.9</a> + </td> + </tr> + <tr> + <td>npm</td> + <td>v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4">6.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4">7.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4">9.x</a> + </td> + </tr> + <tr> + <td>pnpm</td> + <td>v5, v6</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1">7.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1">8.x</a> + </td> + </tr> + <tr> + <td>yarn</td> + <td>v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2">1.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock">2.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock">3.x</a> + </td> + </tr> + <tr> + <td>Poetry</td> + <td>v1</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock">1.x</a> + </td> + </tr> + </tbody> +</table> + <ol> <li> <a id="notes-regarding-parsing-lockfiles-1"></a> @@ -385,22 +464,99 @@ To support the following package managers, the GitLab analyzers proceed in two s 1. Execute the package manager or a specific task, to export the dependency information. 1. Parse the exported dependency information. -| Package Manager | Pre-installed Versions | Tested Versions | -| ------ | ------ | ------ | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L445-449), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L451-455), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L457-461), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L463-467), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L469-473), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L475-479), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L481-485) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L95-97)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L314-319), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L321-326), [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L328-333), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L335-339) | -| setuptools | [58.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [>= 65.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/spec/gemnasium-python_image_spec.rb#L249-271) | -| pip | [22.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L88-102) | -| Pipenv | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/requirements.txt#L13) | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L186-210)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L161-183) | -| Go | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91) | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91)<sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> | - <!-- markdownlint-disable MD044 --> +<table class="ds-table no-vertical-table-lines"> + <thead> + <tr> + <th>Package Manager</th> + <th>Pre-installed Versions</th> + <th>Tested Versions</th> + </tr> + </thead> + <tbody> + <tr> + <td>sbt</td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L4">1.6.2</a></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L726-730">1.0.4</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L732-736">1.1.6</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L738-742">1.2.8</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L662-666">1.3.12</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L668-672">1.4.6</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L674-678">1.5.8</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L680-694">1.6.2</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L696-700">1.7.3</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L702-706">1.8.3</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L708-713">1.9.6</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/.gitlab/ci/gemnasium-maven.gitlab-ci.yml#L109-119">1.9.7</a> + </td> + </tr> + <tr> + <td>maven</td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L3">3.6.3</a></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L83-85">3.6.3</a><sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> + </td> + </tr> + <tr> + <td>Gradle</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L5">6.7.1</a><sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L5">7.3.3</a><sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L285-290">5.6.4</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L292-297">6.7</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L299-304">6.9</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L306-310">7.3</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L312-316">8.4</a> + </td> + </tr> + <tr> + <td>setuptools</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17">58.1.0</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/spec/gemnasium-python_image_spec.rb#L249-271">>= 65.6.3</a> + </td> + </tr> + <tr> + <td>pip</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17">22.0.4</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L88-102">20.x</a> + </td> + </tr> + <tr> + <td>Pipenv</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/requirements.txt#L13">2022.1.8</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L186-210">2022.1.8</a><sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L161-183">2022.1.8</a> + </td> + </tr> + <tr> + <td>Go</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91">1.18</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91">1.18</a><sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> + </td> + </tr> + </tbody> +</table> + <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> - This test uses the default version of <code>maven</code> specified by the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3">`.tool-versions`</a> file. + This test uses the default version of <code>maven</code> specified by the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L3"><code>.tool-versions</code></a> file. </p> </li> <li> @@ -554,7 +710,7 @@ your GitLab CI/CD configuration file is complex. To enable dependency scanning: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipeline editor**. 1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file: @@ -961,7 +1117,7 @@ this information is removed from the resulting merged file. ## Versioning and release process -Check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). +Check the [Release Process documentation](../../../development/sec/analyzer_development_guide.md#versioning-and-release-process). ## Contributing to the vulnerability database @@ -979,7 +1135,7 @@ jobs to run successfully. For more information, see [Offline environments](../of Here are the requirements for using dependency scanning in an offline environment: - GitLab Runner with the `docker` or `kubernetes` executor. -- Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Docker container registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - If you have a limited access environment you need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` CI/CD variable to the URL of this repository. For more information on configuration variables, see [Customizing analyzer behavior](#customizing-analyzer-behavior). @@ -1176,217 +1332,3 @@ environment variable due to a possible exploit documented by [CVE-2018-20225](ht intended to obtain a private package from a private index. This only affects use of the `PIP_EXTRA_INDEX_URL` option, and exploitation requires that the package does not already exist in the public index (and thus the attacker can put the package there with an arbitrary version number). - -## Troubleshooting - -### Debug-level logging - -Debug-level logging can help when troubleshooting. For details, see -[debug-level logging](../index.md#debug-level-logging). - -### Working around missing support for certain languages or package managers - -As noted in the ["Supported languages" section](#supported-languages-and-package-managers) -some dependency definition files are not yet supported. -However, Dependency Scanning can be achieved if -the language, a package manager, or a third-party tool -can convert the definition file -into a supported format. - -Generally, the approach is the following: - -1. Define a dedicated converter job in your `.gitlab-ci.yml` file. - Use a suitable Docker image, script, or both to facilitate the conversion. -1. Let that job upload the converted, supported file as an artifact. -1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/index.md#dependencies) - to your `dependency_scanning` job to make use of the converted definitions files. - -For example, Poetry projects that _only_ have a `pyproject.toml` -file can generate the `poetry.lock` file as follows. - -```yaml -include: - - template: Security/Dependency-Scanning.gitlab-ci.yml - -stages: - - test - -gemnasium-python-dependency_scanning: - # Work around https://gitlab.com/gitlab-org/gitlab/-/issues/32774 - before_script: - - pip install "poetry>=1,<2" # Or via another method: https://python-poetry.org/docs/#installation - - poetry update --lock # Generates the lock file to be analyzed. -``` - -### `Error response from daemon: error processing tar file: docker-tar: relocation error` - -This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. -Consider updating to Docker `19.03.1` or greater. Older versions are not -affected. Read more in -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). - -### Getting warning message `gl-dependency-scanning-report.json: no matching files` - -For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). - -### Limitation when using rules:exists - -The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) -uses the [`rules:exists`](../../../ci/yaml/index.md#rulesexists) -syntax. This directive is limited to 10000 checks and always returns `true` after reaching this -number. Because of this, and depending on the number of files in your repository, a dependency -scanning job might be triggered even if the scanner doesn't support your project. - -### Error: `dependency_scanning is used for configuration only, and its script should not be executed` - -For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). - -### Import multiple certificates for Java-based projects - -The `gemnasium-maven` analyzer reads the contents of the `ADDITIONAL_CA_CERT_BUNDLE` variable using `keytool`, which imports either a single certificate or a certificate chain. Multiple unrelated certificates are ignored and only the first one is imported by `keytool`. - -To add multiple unrelated certificates to the analyzer, you can declare a `before_script` such as this in the definition of the `gemnasium-maven-dependency_scanning` job: - -```yaml -gemnasium-maven-dependency_scanning: - before_script: - - . $HOME/.bashrc # make the java tools available to the script - - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file - - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates - - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) - - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import -``` - -### Dependency Scanning job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` - -Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: - -- Disabled by default in GitLab 13.0 and later. -- Unsupported from GitLab 13.4 and later. - -To fix this error, disable Docker-in-Docker for dependency scanning. Individual -`<analyzer-name>-dependency_scanning` jobs are created for each analyzer that runs in your CI/CD -pipeline. - -```yaml -include: - - template: Dependency-Scanning.gitlab-ci.yml - -variables: - DS_DISABLE_DIND: "true" -``` - -### Message `<file> does not exist in <commit SHA>` - -When the `Location` of a dependency in a file is shown, the path in the link goes to a specific Git -SHA. - -If the lock file that our dependency scanning tools reviewed was cached, however, selecting that -link redirects you to the repository root, with the message: -`<file> does not exist in <commit SHA>`. - -The lock file is cached during the build phase and passed to the dependency scanning job before the -scan occurs. Because the cache is downloaded before the analyzer run occurs, the existence of a lock -file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. - -We recommend committing the lock files, which prevents this warning. - -### You 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 varies 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"`. - -### Dependency Scanning of setuptools project fails with `use_2to3 is invalid` error - -Support for [2to3](https://docs.python.org/3/library/2to3.html) -was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) -in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` -version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on -`lib2to3` fails with this message: - -```plaintext -error in <dependency name> setup command: use_2to3 is invalid -``` - -To work around this error, downgrade the analyzer's version of `setuptools` (for example, `v57.5.0`): - -```yaml -gemnasium-python-dependency_scanning: - before_script: - - pip install setuptools==57.5.0 -``` - -### Dependency Scanning of projects using psycopg2 fails with `pg_config executable not found` error - -Scanning a Python project that depends on `psycopg2` can fail with this message: - -```plaintext -Error: pg_config executable not found. -``` - -[psycopg2](https://pypi.org/project/psycopg2/) depends on the `libpq-dev` Debian package, -which is not installed in the `gemnasium-python` Docker image. To work around this error, -install the `libpq-dev` package in a `before_script`: - -```yaml -gemnasium-python-dependency_scanning: - before_script: - - apt-get update && apt-get install -y libpq-dev -``` - -### `NoSuchOptionException` when using `poetry config http-basic` with `CI_JOB_TOKEN` - -This error can occur when the automatically generated `CI_JOB_TOKEN` starts with a hyphen (`-`). -To avoid this error, follow [Poetry's configuration advice](https://python-poetry.org/docs/repositories/#configuring-credentials). - -### Error: Project has `<number>` unresolved dependencies - -The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, consult the [Gradle dependency resolution docs](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. - -### Setting build constraints when scanning Go projects - -Dependency scanning runs within a `linux/amd64` container. As a result, the build list generated -for a Go project contains dependencies that are compatible with this environment. If your deployment environment is not -`linux/amd64`, the final list of dependencies might contain additional incompatible -modules. The dependency list might also omit modules that are only compatible with your deployment environment. To prevent -this issue, you can configure the build process to target the operating system and architecture of the deployment -environment by setting the `GOOS` and `GOARCH` [environment variables](https://go.dev/ref/mod#minimal-version-selection) -of your `.gitlab-ci.yml` file. - -For example: - -```yaml -variables: - GOOS: "darwin" - GOARCH: "arm64" -``` - -You can also supply build tag constraints by using the `GOFLAGS` variable: - -```yaml -variables: - GOFLAGS: "-tags=test_feature" -``` - -### Dependency Scanning of Go projects returns false positives - -The `go.sum` file contains an entry of every module that was considered while generating the project's [build list](https://go.dev/ref/mod#glos-build-list). -Multiple versions of a module are included in the `go.sum` file, but the [MVS](https://go.dev/ref/mod#minimal-version-selection) -algorithm used by `go build` only selects one. As a result, when dependency scanning uses `go.sum`, it might report false positives. - -To prevent false positives, Gemnasium only uses `go.sum` if it is unable to generate the build list for the Go project. If `go.sum` is selected, a warning occurs: - -```shell -[WARN] [Gemnasium] [2022-09-14T20:59:38Z] ▶ Selecting "go.sum" parser for "/test-projects/gitlab-shell/go.sum". False positives may occur. See https://gitlab.com/gitlab-org/gitlab/-/issues/321081. -``` diff --git a/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md new file mode 100644 index 00000000000..77579a04c7e --- /dev/null +++ b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md @@ -0,0 +1,232 @@ +--- +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting Dependency Scanning **(FREE ALL)** + +When working with dependency scanning, you might encounter the following issues. + +## Debug-level logging + +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). + +### Working around missing support for certain languages or package managers + +As noted in the ["Supported languages" section](index.md#supported-languages-and-package-managers) +some dependency definition files are not yet supported. +However, Dependency Scanning can be achieved if +the language, a package manager, or a third-party tool +can convert the definition file +into a supported format. + +Generally, the approach is the following: + +1. Define a dedicated converter job in your `.gitlab-ci.yml` file. + Use a suitable Docker image, script, or both to facilitate the conversion. +1. Let that job upload the converted, supported file as an artifact. +1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/index.md#dependencies) + to your `dependency_scanning` job to make use of the converted definitions files. + +For example, Poetry projects that _only_ have a `pyproject.toml` +file can generate the `poetry.lock` file as follows. + +```yaml +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + +stages: + - test + +gemnasium-python-dependency_scanning: + # Work around https://gitlab.com/gitlab-org/gitlab/-/issues/32774 + before_script: + - pip install "poetry>=1,<2" # Or via another method: https://python-poetry.org/docs/#installation + - poetry update --lock # Generates the lock file to be analyzed. +``` + +### `Error response from daemon: error processing tar file: docker-tar: relocation error` + +This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. +Consider updating to Docker `19.03.1` or greater. Older versions are not +affected. Read more in +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). + +### Getting warning message `gl-dependency-scanning-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). + +## `Error response from daemon: error processing tar file: docker-tar: relocation error` + +This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. +Consider updating to Docker `19.03.1` or greater. Older versions are not +affected. Read more in +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). + +## Getting warning message `gl-dependency-scanning-report.json: no matching files` + +For information, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). + +## Limitation when using rules:exists + +The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +uses the [`rules:exists`](../../../ci/yaml/index.md#rulesexists) +syntax. This directive is limited to 10000 checks and always returns `true` after reaching this +number. Because of this, and depending on the number of files in your repository, a dependency +scanning job might be triggered even if the scanner doesn't support your project. + +## Error: `dependency_scanning is used for configuration only, and its script should not be executed` + +For information, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + +## Import multiple certificates for Java-based projects + +The `gemnasium-maven` analyzer reads the contents of the `ADDITIONAL_CA_CERT_BUNDLE` variable using `keytool`, which imports either a single certificate or a certificate chain. Multiple unrelated certificates are ignored and only the first one is imported by `keytool`. + +To add multiple unrelated certificates to the analyzer, you can declare a `before_script` such as this in the definition of the `gemnasium-maven-dependency_scanning` job: + +```yaml +gemnasium-maven-dependency_scanning: + before_script: + - . $HOME/.bashrc # make the java tools available to the script + - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file + - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates + - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) + - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import +``` + +## Dependency Scanning job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` + +Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: + +- Disabled by default in GitLab 13.0 and later. +- Unsupported from GitLab 13.4 and later. + +To fix this error, disable Docker-in-Docker for dependency scanning. Individual +`<analyzer-name>-dependency_scanning` jobs are created for each analyzer that runs in your CI/CD +pipeline. + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DISABLE_DIND: "true" +``` + +## Message `<file> does not exist in <commit SHA>` + +When the `Location` of a dependency in a file is shown, the path in the link goes to a specific Git +SHA. + +If the lock file that our dependency scanning tools reviewed was cached, however, selecting that +link redirects you to the repository root, with the message: +`<file> does not exist in <commit SHA>`. + +The lock file is cached during the build phase and passed to the dependency scanning job before the +scan occurs. Because the cache is downloaded before the analyzer run occurs, the existence of a lock +file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. + +To prevent this warning, lock files should be committed. + +## You 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 varies depending on which scanning job you edited. + + For example, 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"`. + +## Dependency Scanning of setuptools project fails with `use_2to3 is invalid` error + +Support for [2to3](https://docs.python.org/3/library/2to3.html) +was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) +in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` +version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on +`lib2to3` fails with this message: + +```plaintext +error in <dependency name> setup command: use_2to3 is invalid +``` + +To work around this error, downgrade the analyzer's version of `setuptools` (for example, `v57.5.0`): + +```yaml +gemnasium-python-dependency_scanning: + before_script: + - pip install setuptools==57.5.0 +``` + +## Dependency Scanning of projects using psycopg2 fails with `pg_config executable not found` error + +Scanning a Python project that depends on `psycopg2` can fail with this message: + +```plaintext +Error: pg_config executable not found. +``` + +[psycopg2](https://pypi.org/project/psycopg2/) depends on the `libpq-dev` Debian package, +which is not installed in the `gemnasium-python` Docker image. To work around this error, +install the `libpq-dev` package in a `before_script`: + +```yaml +gemnasium-python-dependency_scanning: + before_script: + - apt-get update && apt-get install -y libpq-dev +``` + +## `NoSuchOptionException` when using `poetry config http-basic` with `CI_JOB_TOKEN` + +This error can occur when the automatically generated `CI_JOB_TOKEN` starts with a hyphen (`-`). +To avoid this error, follow [Poetry's configuration advice](https://python-poetry.org/docs/repositories/#configuring-credentials). + +## Error: Project has `<number>` unresolved dependencies + +The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, consult the [Gradle dependency resolution documentation](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. + +## Setting build constraints when scanning Go projects + +Dependency scanning runs within a `linux/amd64` container. As a result, the build list generated +for a Go project contains dependencies that are compatible with this environment. If your deployment environment is not +`linux/amd64`, the final list of dependencies might contain additional incompatible +modules. The dependency list might also omit modules that are only compatible with your deployment environment. To prevent +this issue, you can configure the build process to target the operating system and architecture of the deployment +environment by setting the `GOOS` and `GOARCH` [environment variables](https://go.dev/ref/mod#minimal-version-selection) +of your `.gitlab-ci.yml` file. + +For example: + +```yaml +variables: + GOOS: "darwin" + GOARCH: "arm64" +``` + +You can also supply build tag constraints by using the `GOFLAGS` variable: + +```yaml +variables: + GOFLAGS: "-tags=test_feature" +``` + +## Dependency Scanning of Go projects returns false positives + +The `go.sum` file contains an entry of every module that was considered while generating the project's [build list](https://go.dev/ref/mod#glos-build-list). +Multiple versions of a module are included in the `go.sum` file, but the [MVS](https://go.dev/ref/mod#minimal-version-selection) +algorithm used by `go build` only selects one. As a result, when dependency scanning uses `go.sum`, it might report false positives. + +To prevent false positives, Gemnasium only uses `go.sum` if it is unable to generate the build list for the Go project. If `go.sum` is selected, a warning occurs: + +```shell +[WARN] [Gemnasium] [2022-09-14T20:59:38Z] ▶ Selecting "go.sum" parser for "/test-projects/gitlab-shell/go.sum". False positives may occur. See https://gitlab.com/gitlab-org/gitlab/-/issues/321081. +``` diff --git a/doc/user/application_security/generate_test_vulnerabilities/index.md b/doc/user/application_security/generate_test_vulnerabilities/index.md deleted file mode 100644 index f9f93b97baf..00000000000 --- a/doc/user/application_security/generate_test_vulnerabilities/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: '../../../development/sec/generate_test_vulnerabilities.md' -remove_date: '2023-11-01' ---- - -This document was moved to [another location](../../../development/sec/generate_test_vulnerabilities.md). diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index 6143dd59373..e84149b91e8 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -1,7 +1,7 @@ --- stage: DevSecOps group: Technical writing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Get started with GitLab application security **(ULTIMATE ALL)** diff --git a/doc/user/application_security/gitlab_advisory_database/index.md b/doc/user/application_security/gitlab_advisory_database/index.md index e59eaccf8f8..7e01cd7b2d5 100644 --- a/doc/user/application_security/gitlab_advisory_database/index.md +++ b/doc/user/application_security/gitlab_advisory_database/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Vulnerability Research -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Advisory Database diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index bca29420192..da4fee978d0 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure as Code scanning **(FREE ALL)** diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 25fa1f5cbaf..e31877d195a 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application security **(ULTIMATE ALL)** @@ -95,6 +95,12 @@ against this, infrastructure analysis occurs on every merge request. Checks are - Infrastructure as Code (IaC) configuration files that define your application's deployment environment - [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md). +## Data privacy + +Concerning data privacy in the domain of security scanners, GitLab processes the source code and performs analysis locally on the GitLab Runner. No data is transmitted outside GitLab infrastructure (server and runners). + +Our scanners access the internet only to download the latest sets of signatures, rules, and patches. If you prefer the scanners do not access the internet, consider using an [offline environment](offline_deployments/index.md). + ## Vulnerability scanner maintenance The following vulnerability scanners and their databases are regularly updated: @@ -270,7 +276,9 @@ In the Free tier, the reports above aren't parsed by GitLab. As a result, the wi A merge request contains a security widget which displays a summary of the _new_ results. New results are determined by comparing the findings of the merge request against the findings of the most recent completed pipeline (`success`, `failed`, `canceled` or `skipped`) for the commit when the feature branch was created from the target branch. -GitLab checks the last 10 pipelines for the commit when the feature was created from the target branch to find one with security reports to use in comparison logic. If security scans have not run for the last 10 completed pipelines in the target branch when the feature branch was created, there is no base for comparison. The vulnerabilities from the merge request findings are listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. +GitLab checks the last 10 pipelines for the commit when the feature branch was created from the target branch to find one with security reports to use in comparison logic. If security scans have not run for the last 10 completed pipelines in the target branch when the feature branch was created, there is no base for comparison. The vulnerabilities from the merge request findings are listed as _new_ in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. + +The MR security widget considers all supported pipeline sources (based on the [`CI_PIPELINE_SOURCE` variable](../../ci/variables/predefined_variables.md)) when comparing results from both the source and target branches when determining if a merge request requires approval. Pipeline sources `webide` and `parent_pipeline` are not supported. The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both new and existing findings. @@ -283,9 +291,11 @@ findings, select **View full report** to go directly to the **Security** tab in ### Pipeline security tab -A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch -and existing vulnerabilities already present when you created the branch. These results likely do not match the findings -displayed in the Merge Request security widget, as those do not include the existing vulnerabilities. Refer to [View vulnerabilities in a pipeline](vulnerability_report/pipeline.md) for more information. +A pipeline's security tab lists all findings in the current branch. It includes findings introduced +by this branch and vulnerabilities already present in the base branch. These results likely do not +match the findings displayed in the Merge Request security widget, as those do not include the +existing vulnerabilities. For more information see +[Vulnerabilities in a pipeline](vulnerability_report/pipeline.md). ### Security dashboard @@ -588,7 +598,7 @@ variables: This indicates to all GitLab analyzers that they are to output **all** messages. For more details, see [logging level](#logging-level). -<!-- NOTE: The below subsection(`### Secure job failing with exit code 1`) documentation URL is referred in the [/gitlab-org/security-products/analyzers/command](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/command.go#L19) repository. If this section/subsection changes, please ensure to update the corresponding URL in the mentioned repository. +<!-- NOTE: The below subsection(`### Secure job failing with exit code 1`) documentation URL is referred in the [/gitlab-org/security-products/analyzers/command](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/command.go#L19) repository. If this section/subsection changes, ensure to update the corresponding URL in the mentioned repository. --> ### Secure job failing with exit code 1 diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 1ab26229b50..46d2313b1fe 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Offline environments **(FREE SELF)** @@ -124,7 +123,7 @@ include: ``` The pipeline downloads the Docker images needed for the Security Scanners and saves them as -[job artifacts](../../../ci/jobs/job_artifacts.md) or pushes them to the [Container Registry](../../packages/container_registry/index.md) +[job artifacts](../../../ci/jobs/job_artifacts.md) or pushes them to the [container registry](../../packages/container_registry/index.md) of the project where the pipeline is executed. These archives can be transferred to another location and [loaded](https://docs.docker.com/engine/reference/commandline/load/) in a Docker daemon. This method requires a runner with access to both `gitlab.com` (including diff --git a/doc/user/application_security/policies/img/association_diagram.png b/doc/user/application_security/policies/img/association_diagram.png Binary files differdeleted file mode 100644 index 3a56aeba91b..00000000000 --- a/doc/user/application_security/policies/img/association_diagram.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png b/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png Binary files differnew file mode 100644 index 00000000000..d2f5466e383 --- /dev/null +++ b/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png 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 differdeleted file mode 100644 index feea1b1b01c..00000000000 --- a/doc/user/application_security/policies/img/security_policy_project_v14_6.png +++ /dev/null diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index a86d9b63c63..bd40209320d 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -1,19 +1,23 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Policies **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in GitLab 13.10 with a flag named `security_orchestration_policies_configuration`. Disabled by default. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.3. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.4. +> [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.4. Feature flag `security_orchestration_policies_configuration` removed. -Policies in GitLab provide security teams a way to require scans of their choice to be run -whenever a project pipeline runs according to the configuration specified. Security teams can -therefore be confident that the scans they set up have not been changed, altered, or disabled. You -can access these by navigating to your project's **Secure > Policies** page. +Policies in GitLab provide security and compliance teams with a way to enforce controls globally in +their organization. Security teams can ensure: + +- Security scanners are enforced in development team pipelines with proper configuration. +- That all scan jobs execute without any changes or alterations. +- That proper approvals are provided on merge requests based on results from those findings. + +Compliance teams can centrally enforce multiple approvers on all merge requests and ensure various +settings are enabled on projects in scope of organizational requirements, such as enabling or +locking merge request and repository settings. GitLab supports the following security policies: @@ -22,65 +26,221 @@ GitLab supports the following security policies: ## Security policy project -All security policies are stored as YAML in a separate security policy project that gets linked to -the development project, group, or sub-group. This association can be a one-to-many relationship, allowing one security -policy project to apply to multiple development projects, groups, or sub-groups: +A security policy project (SPP) is a special type of project used only to contain policies. The +policies are stored in the `.gitlab/security-policies/policy.yml` YAML file. + +To enforce the policies contained in an SPP you link it to a project, subgroup, group, or multiples +of each. An SPP can contain multiple policies but they are enforced together. An +SPP enforced on a group or subgroup applies to everything below in the hierarchy, including all +subgroups and their projects. -- For self-managed GitLab instances, linked projects are not required to be in the same group - or the same subgroup as the development projects to which they are linked. -- For GitLab SaaS, the security policy project is required to be in the same top-level group - as the development project, although, it is not necessary for the project to be in the same subgroup. +Policy changes made in a merge request take effect as soon as the merge request is merged. Those +that do not go through a merge request, but instead are committed directly to the default branch, may +require up to 10 minutes before the policy changes take effect. - +## Policy design guidelines -Although it is possible to have one project linked to itself and to serve as both the development -project and the security policy project, this is not recommended. Keeping the security policy -project separate from the development project allows for complete separation of duties between -security/compliance teams and development teams. +When designing your policies, your goals should be: -All security policies are stored in the `.gitlab/security-policies/policy.yml` YAML file inside the -linked security policy project. The format for this YAML is specific to the type of policy that is -stored there. Examples and schema information are available for the following policy types: +- Designing policy enforcement for minimum overhead but maximum coverage +- Separation of duties -- [Scan execution policy](scan-execution-policies.md#example-security-policies-project) -- [Scan result policy](scan-result-policies.md#example-security-scan-result-policies-project) +### Policy enforcement design -Most policy changes take effect as soon as the merge request is merged. Any changes that -do not go through a merge request and are committed directly to the default branch may require up to 10 minutes -before the policy changes take effect. +To maximize policy coverage, link an SPP at the highest level that achieves your objectives: group +level, subgroup level, or project level. Enforcement at the highest level minimizes the number of +SPPs and therefore the management overhead. Policies cascade down from each level to a project, such that policies may be enforced from the group level, each subgroup above it, and then for any policies created at the project level itself. -### Managing the linked security policy project +Policy inheritance of policies not only ensures maximum coverage with the minimum +number of SPPs, but also helps when implementing policy changes. For example, to test a policy change +you could copy an existing policy and enforce the modified policy first to a project, then to a +subgroup, and, if applicable, to a group. NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select, edit, and unlink a security policy project. +GitLab SaaS users may enforce policies against their top-level group or across subgroups, but cannot enforce policies across GitLab SaaS top-level groups. GitLab self-managed users can enforce policies across multiple top-level groups in their instance. -As a project owner, take the following steps to create or edit an association between your current -project and a project that you would like to designate as the security policy project: +The following example illustrates two groups and their structure: + +- Alpha group contains two subgroups, each of which contains multiple projects. +- Security and Compliance group contains two policies. -1. On the left sidebar, select **Search or go to** and find your project. +**Alpha** group (contains code projects) + +- **Finance** (subgroup) + - Project A + - Accounts receiving (subgroup) + - Project B + - Project C +- **Engineering** (subgroup) + - Project K + - Project L + - Project M + +**Security and Compliance** group (contains SPPs) + +- Security Policy Management +- Security Policy Management - security policy project + - SAST policy + - Secret Detection policy + +Assuming no policies have already been enforced, consider the following examples: + +- If the "SAST" policy is enforced at group Alpha, it applies to its subgroups, Finance and + Engineering, and all their projects and subgroups. If the "Secret Detection" policy is enforced + also at subgroup "Accounts receiving", both policies apply to projects B and C. However, only the + "SAST" policy applies to project A. +- If the "SAST policy is enforced at subgroup "Accounts receiving", it applies only to projects B + and C. No policy applies to project A. +- If the "Secret Detection" is enforced at project K, it applies only to project K. No other + subgroups or projects have a policy apply to them. + +### Separation of duties + +Separation of duties is vital to successfully implementing policies. Security and compliance teams +should be responsible for defining policies and working with development teams. Development teams +should not be able to disable, modify, or circumvent the policies, in any way, or for any +exceptions. The policies should be implemented to achieve the necessary compliance and security +requirements, while allowing development teams to achieve their goals. + +The role required to enforce an SPP depends on the hierarchy level at which it's being linked: + +| Organization unit | Group owner | Subgroup owner | Project owner | +|-------------------|------------------------|------------------------|------------------------| +| Group | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| Subgroup | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| Project | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | + +## Policy implementation + +Implementation options for SPPs differ slightly between GitLab SaaS and GitLab self-managed. The +main difference is that on GitLab SaaS it's only possible to create subgroups. Ensuring separation +of duties requires more granular permission configuration. + +### Enforce policies across subgroups and projects **(ULTIMATE SAAS)** + +To enforce policies against subgroups and projects, create a subgroup to contain the SPPs, separate +to the subgroups containing the projects. Using separate subgroups allows for separation of duties, +with the SPP managed by the security team, and the projects' subgroups managed by the development +team. The security team can add or change policies without intervention from the subgroups' owners. +Subgroup and project owners cannot override policies. + +Prerequisites: + +- You must have the Owner role to link to the SPP. For details see + [Separation of duties](#separation-of-duties). + +The high-level workflow for enforcing policies across multiple subgroups: + +1. Create a subgroup to contain your policies and ensure separation of duties. + + By creating a separate standalone subgroup, you can minimize the number of users who inherit + permissions. +1. In the new group or subgroup, create a new project for managing your policies, such as "Security + Policy Management". + + This serves as the primary location of the policy editor, allowing you to create and manage + policies in the UI. +1. Create a test policy. (you can create a policy as disabled for testing.) + + Creating the policy automatically creates a new SPP under your group or subgroup. This project is + used to store your `policy.yml` or policy-as-code. +1. Check and set project permissions in the newly-created project so that only members of the security team have the Owner role. +1. If additional restrictions are needed to block inherited permissions or require additional review + or approval of policy changes, you can create an additional and separate set of policies to + enforce against the first. For example, you may define a single set of individual users + responsible for approving policy changes. +1. In the SPP just created, create the policies required. You can use the policy editor in the `Security Policy Management` project you created, under the Policies tab. Or you can directly update the policies in the `policy.yml` file stored in the newly-created security policy project `Security Policy Management - security policy project`. +1. Link up groups, subgroups, or projects to the SPP. As a subgroup owner, or project + owner, you can visit the Policies page and create a link to the SPP. Include the full + path and the project's name should end with "- security policy project". For details, see + [Link to a security policy project](#link-to-a-security-policy-project). + +### Enforce policies across groups, subgroups, and projects **(ULTIMATE SELF)** + +To enforce policies against multiple groups, create a group to contain the SPPs, separate to the +groups containing the projects. Using separate groups allows for separation of duties, with the SPP +managed by the security team, and the projects' groups managed by the development team. The security +team can add or change policies without intervention from the groups' owners. Subgroup and project +owners cannot override policies. + +Prerequisites: + +- You must have the Owner role to link to the SPP. For details see + [Separation of duties](#separation-of-duties). +- To support approval groups globally across your instance, enable `security_policy_global_group_approvers_enabled` in your [GitLab instance application settings](../../../api/settings.md). + +The high-level workflow for enforcing policies across multiple groups: + +1. Create a separate group to contain your policies and ensure separation of duties. + + By creating a separate standalone group, you can minimize the number of users who inherit + permissions. +1. In the new group, create a new project for managing your policies, such as "Security Policy + Management". + + This serves as the primary location of the policy editor, allowing you to + create and manage policies in the UI. +1. Create a test policy (you can create a policy as disabled for testing). + + Creating the policy automatically creates a new SPP under your group. This project is + used to store your `policy.yml` or policy-as-code. +1. Check and set permissions in the newly created project as desired. By default, Owners and + Maintainers are able to create, edit, and delete policies. +1. If additional restrictions are needed to block inherited permissions or require additional review + or approval of policy changes, you can create an additional and separate set of policies to + enforce against the first. For example, you may define a single set of individual users + responsible for approving policy changes. +1. Set the permissions of the SPP so that only members of the security team have the Owner role. +1. In the SPP just created, create the policies required. +1. Link up groups, subgroups, or projects to the SPP. As a group owner, subgroup owner, or project + owner, you can visit the Policies page and create a link to the SPP. Include the full path and + the project's name should end with "- security policy project". For details, see + [Link to a security policy project](#link-to-a-security-policy-project). + +### Enforce policies across multiple projects + +When linking a group or subgroup to your policies is not granular enough, it is possible to link up +to the SPP per project. This allows you to filter projects from enforcement that are not applicable. +To enforce an SPP policies at the project level, create a security policy project and link them. Use +project permissions to ensure only the security team has the Owner role in the security policy +project. + +To enforce policies against a project: + +1. Create a security policy project at the same level as the target project. +1. In the security policy project, create the policies required. +1. Link the target project to the security policy project. + +## Link to a security policy project + +To enforce the policies contained in an SPP against a project, subgroup, or group, you link them. + +Prerequisites: + +- You must have the Owner role to link to the SPP. For details, see + [Separation of duties](#separation-of-duties). + +To link a project, subgroup, or group to an SPP: + +1. On the left sidebar, select **Search or go to** and find your project, subgroup, or group. 1. Select **Secure > Policies**. -1. Select **Edit Policy Project**, and search for and select the - project you would like to link from the dropdown list. +1. Select **Edit Policy Project**, then search for and select the project you would like to link + from the dropdown list. 1. Select **Save**. To unlink a security policy project, follow the same steps but instead select the trash can icon in -the modal. - - +the dialog. ### Viewing the linked security policy project -All users who have access to the project policy page and are not project owners will instead view a -button linking out to the associated security policy project. If no security policy project has been -associated then the linking button does not appear. +All users who have access to the project policy page and are not project owners instead view a +button linking out to the associated security policy project. ## Policy management -The Policies page displays deployed -policies for all available environments. You can check a -policy's information (for example, description or enforcement -status), and create and edit deployed policies: +The Policies page displays deployed policies for all available environments. You can check a +policy's information (for example, description or enforcement status), and create and edit deployed +policies: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. @@ -141,16 +301,43 @@ The workaround is to amend your group or instance push rules to allow branches f ### Troubleshooting common issues configuring security policies -- Confirm that scanners are properly configured and producing results for the latest branch. Security Policies are designed to require approval when there are no results (no security report), as this ensures that no vulnerabilities are introduced. We cannot know if there are any vulnerabilities unless the scans enforced by the policy complete successfully and are evaluated. -- For scan result policies, we require artifacts for each scanner defined in the policy for both the source and target branch. To ensure scan result policies capture the necessary results, confirm your scan execution is properly implemented and enforced. If using scan execution policies, enforcing on `all branches` often address this need. -- When running scan execution policies based on a SAST action, ensure target repositories contain proper code files. SAST runs different analyzers [based on the types of files in the repository](../sast/index.md#supported-languages-and-frameworks), and if no supported files are found it will not run any jobs. See the [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) for more details. -- Check for any branch configuration conflicts. If your policy is configured to enforce rules on `main` but some projects within the scope are using `master` as their default branch, the policy is not applied for the latter. You can define policies to enforce rules generically on `default` branches regardless of the name used in the project or on `all protected branches` to address this issue. -- Scan result policies created at the group or sub-group level can take some time to apply to all the merge requests in the group. +- Confirm that scanners are properly configured and producing results for the latest branch. + Security Policies are designed to require approval when there are no results (no security report), + as this ensures that no vulnerabilities are introduced. We cannot know if there are any + vulnerabilities unless the scans enforced by the policy complete successfully and are evaluated. +- For scan result policies, we require artifacts for each scanner defined in the policy for both the + source and target branch. To ensure scan result policies capture the necessary results, confirm + your scan execution is properly implemented and enforced. If using scan execution policies, + enforcing on `all branches` often addresses this need. +- When running scan execution policies based on a SAST action, ensure target repositories contain + proper code files. SAST runs different analyzers + [based on the types of files in the repository](../sast/index.md#supported-languages-and-frameworks), + and if no supported files are found it does not run any jobs. See the + [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) + for more details. +- Check for any branch configuration conflicts. For example, if your policy is configured to enforce rules on + `main` but some projects in the scope are using `master` as their default branch, the policy + is not applied for the latter. You can define policies to enforce rules generically on `default` + branches regardless of the name used in the project or on `all protected branches` to address this + issue. +- Scan result policies created at the group or subgroup level can take some time to apply to all + the merge requests in the group. - Scheduled scan execution policies run with a minimum 15 minute cadence. Learn more [about the schedule rule type](../policies/scan-execution-policies.md#schedule-rule-type). -- When scheduling pipelines, keep in mind that CRON scheduling is based on UTC on GitLab SaaS and is based on your server time for self managed instances. When testing new policies, it may appear pipelines are not running properly when in fact they are scheduled in your server's timezone. -- When enforcing scan execution policies, security policies use a bot in the target project that will trigger scheduled pipelines to ensure enforcement. When the bot is missing, it will be automatically created, and the following scheduled scan will use it. -- You should not link a security policy project to a development project and to the group or sub-group the development project belongs to at the same time. Linking this way will result in approval rules from the Scan Result Policy not being applied to merge requests in the development project. -- When creating a Scan Result Policy, neither the array `severity_levels` nor the array `vulnerability_states` in the [`scan_finding` rule](../policies/scan-result-policies.md#scan_finding-rule-type) can be left empty; for a working rule, at least one entry must exist. -- When configuring pipeline and scan result policies, it's important to remember that security scans performed in manual jobs aren't verified to determine whether MR approval is required. When you run a manual job with security scans, it won't ensure approval even if vulnerabilities are introduced. +- When scheduling pipelines, keep in mind that CRON scheduling is based on UTC on GitLab SaaS and is + based on your server time for self managed instances. When testing new policies, it may appear + pipelines are not running properly when in fact they are scheduled in your server's time zone. +- When enforcing scan execution policies, security policies use a bot in the target project to + trigger scheduled pipelines to ensure enforcement. When the bot is missing, it is automatically + created, and the following scheduled scan uses it. +- You should not link a security policy project to a development project and to the group or + subgroup the development project belongs to at the same time. Linking this way results in approval + rules from the Scan Result Policy not being applied to merge requests in the development project. +- When creating a Scan Result Policy, neither the array `severity_levels` nor the array + `vulnerability_states` in the [`scan_finding` rule](../policies/scan-result-policies.md#scan_finding-rule-type) + can be left empty. For a working rule, at least one entry must exist. +- When configuring pipeline and scan result policies, it's important to remember that security scans + performed in manual jobs are not verified to determine whether MR approval is required. When you + run a manual job with security scans, it does not ensure approval even if vulnerabilities are + introduced. If you are still experiencing issues, you can [view recent reported bugs](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=popularity&state=opened&label_name%5B%5D=group%3A%3Asecurity%20policies&label_name%5B%5D=type%3A%3Abug&first_page_size=20) and raise new unreported issues. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index f6ef8a2c49e..f299a38dff1 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -1,7 +1,7 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scan execution policies **(ULTIMATE ALL)** @@ -201,16 +201,23 @@ The keys for a schedule rule are: ## `scan` action type +> - Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. +> - The `custom` scan action type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126457) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. On GitLab.com, this feature is not available. On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. + This action executes the selected `scan` with additional parameters when conditions for at least one rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning` | The action's type. | +| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning`, `custom` | The action's type. | | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/proxy-based.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/proxy-based.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| | `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | | `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs are run by runner with the specified tags. | +| `ci_configuration` <sup>1</sup> | `string` | | GitLab CI YAML as formatted as string. | +| `ci_configuration_path` <sup>1</sup> | object | Object with project path and file name pointing to a CI configuration. | + +1. For `custom` scans, you must specify one of `ci_configuration` or `ci_configuration_path`. Note the following: @@ -224,13 +231,22 @@ Note the following: policy project's repository must have access to the scanner and site profiles. Otherwise, the scan is not scheduled successfully. - For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) - are not supported. -- A secret detection scan runs in `default` 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. + are not supported. Alternatively, you may configure a [remote configuration file](../secret_detection/index.md#specify-a-remote-configuration-file) and set the `SECRET_DETECTION_RULESET_GIT_REFERENCE` variable. +- By default, for `scheduled` scan execution policies, secret detection scans configured without any CI variables defined run first in `historic` mode (`SECRET_DETECTION_HISTORIC_SCAN` = `true`). All subsequent scheduled scans run in default mode with `SECRET_DETECTION_LOG_OPTIONS` set to the commit range between last run and current SHA. CI variables provided in the scan execution policy can override this behavior. Learn more about [historic mode](../secret_detection/index.md#full-history-secret-detection). +- For `triggered` scan execution policies, secret detection works just like regular scan [configured manually in the `.gitlab-ci.yml`](../secret_detection/index.md#edit-the-gitlab-ciyml-file-manually). - A container scanning scan that is configured for the `pipeline` rule type ignores the agent defined in the `agents` object. The `agents` object is only considered for `schedule` rule types. An agent with a name provided in the `agents` object must be created and configured for the project. - Variables defined in a Scan Execution Policy follow the standard [CI/CD variable precedence](../../../ci/variables/index.md#cicd-variable-precedence). +- `custom` scans are be executed for scheduled rules. +- Jobs variables and stages definitions from `custom` scans take precedence over the project's CI/CD configuration. + +### `ci_configuration_path` object + +| Field | Type | Description | +|-------|------|-------------| +| `project` | `string` | A project namespace path. | +| `file` | `string` | The filename of the CI/CD YAML file. | +| `ref` | `string` (optional) | The branch name, tag name, or commit SHA. | ## Example security policies project @@ -251,6 +267,12 @@ scan_execution_policy: - scan: dast scanner_profile: Scanner Profile A site_profile: Site Profile B + - scan: custom + ci_configuration: |- + test job: + stage: test + script: + - echo "Hello World" - name: Enforce DAST and secret detection scans every 10 minutes description: This policy enforces DAST and secret detection scans to run every 10 minutes enabled: true @@ -282,7 +304,9 @@ scan_execution_policy: In this example: - For every pipeline executed on branches that match the `release/*` wildcard (for example, branch - `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. + `release/v1.2.1`) + - DAST scans run with `Scanner Profile A` and `Site Profile B`. + - A `test job` is injected into the `test` stage of the pipeline, printing `Hello World`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. - Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index d0d3cb2ca03..0fadd761fe4 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -1,7 +1,7 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scan result policies **(ULTIMATE ALL)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use scan result policies to take action based on scan results. For example, one type of scan result policy is a security approval policy that allows approval to be required based on the -findings of one or more security scan jobs. Scan result policies are evaluated after a CI scanning job is fully executed. +findings of one or more security scan jobs. Scan result policies are evaluated after a CI scanning job is fully executed and both vulnerability and license type policies are evaluated based on the job artifact reports that are published in the completed pipeline. NOTE: Scan result policies are applicable only to [protected](../../project/protected_branches.md) target branches. @@ -34,6 +34,7 @@ The following video gives you an overview of GitLab scan result policies: - The maximum number of policies is five. - Each policy can have a maximum of five rules. - All configured scanners must be present in the merge request's latest pipeline. If not, approvals are required even if some vulnerability criteria have not been met. +- Scan result policies evaluate findings and determine approval requirements based on the job artifact reports published in a completed pipeline. However, scan result policies do not check the integrity or authenticity of the scan results generated in the artifact reports. ## Merge request with multiple pipelines @@ -84,24 +85,24 @@ If you're not familiar with how to read [JSON schemas](https://json-schema.org/) the following sections and tables provide an alternative. | Field | Type | Required | Possible values | Description | -|----------------------|-------------------------------|----------|-----------------|------------------------------------------| +|----------------------|-------------------------------|----------|-----------------|-------------------------------------------| | `scan_result_policy` | `array` of Scan Result Policy | true | | List of scan result policies (maximum 5). | ## Scan result policy schema -> The `approval_settings` fields was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. All are disabled by default. +> The `approval_settings` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. FLAG: -On self-managed GitLab, by default the `approval_settings` field is unavailable. To show the feature, an administrator can [enable the feature flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. +On self-managed GitLab, by default the `approval_settings` field is available. To hide the feature, an administrator can [disable the feature flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request` and `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. On GitLab.com, the `approval_settings` field is available. -| Field | Type | Required |Possible values | Description | -|--------|------|----------|----------------|-------------| -| `name` | `string` | true | | Name of the policy. Maximum of 255 characters.| -| `description` | `string` | false | | Description of the policy. | -| `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | -| `rules` | `array` of rules | true | | List of rules that the policy applies. | -| `actions` | `array` of actions | false | | List of actions that the policy enforces. | -| `approval_settings` | `object` | false | | Project settings that the policy overrides. | +| Field | Type | Required | Possible values | Description | +|---------------------|--------------------|----------|-----------------|----------------------------------------------------------| +| `name` | `string` | true | | Name of the policy. Maximum of 255 characters. | +| `description` | `string` | false | | Description of the policy. | +| `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | true | | List of rules that the policy applies. | +| `actions` | `array` of actions | false | | List of actions that the policy enforces. | +| `approval_settings` | `object` | false | | Project settings that the policy overrides. | ## `scan_finding` rule type @@ -115,7 +116,7 @@ This rule enforces the defined actions based on security scan findings. |-------|------|----------|-----------------|-------------| | `type` | `string` | true | `scan_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of protected branches the given policy applies to. Cannot be used with the `branches` field. Default branches must also be `protected`. | | `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `scanners` | `array` of `string` | true | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. `sast` includes results from both SAST and SAST IaC scanners. | | `vulnerabilities_allowed` | `integer` | true | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | @@ -136,7 +137,7 @@ This rule enforces the defined actions based on license findings. |------------|------|----------|-----------------|-------------| | `type` | `string` | true | `license_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of protected branches the given policy applies to. Cannot be used with the `branches` field. Default branches must also be `protected`. | | `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `match_on_inclusion` | `boolean` | true | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | | `license_types` | `array` of `string` | true | license types | [SPDX license names](https://spdx.org/licenses) to match on, for example `Affero General Public License v1.0` or `MIT License`. | @@ -145,10 +146,11 @@ This rule enforces the defined actions based on license findings. ## `any_merge_request` rule type > - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed. -> - The `any_merge_request` rule type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. Disabled by default. +> - The `any_merge_request` rule type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136298) in GitLab 16.6. FLAG: -On self-managed GitLab, by default the `any_merge_request` field is not available. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `any_merge_request`. +On self-managed GitLab, by default the `any_merge_request` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `any_merge_request`. +On GitLab.com, this feature is available. This rule enforces the defined actions for any merge request based on the commits signature. @@ -156,7 +158,7 @@ This rule enforces the defined actions for any merge request based on the commit |---------------|---------------------|--------------------------------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | `string` | true | `any_merge_request` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of protected branches the given policy applies to. Cannot be used with the `branches` field. Default branches must also be `protected`. | | `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `commits` | `string` | true | `any`, `unsigned` | Whether the rule matches for any commits, or only if unsigned commits are detected in the merge request. | @@ -179,24 +181,31 @@ the defined policy. > - The `block_unprotecting_branches` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423101) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. Disabled by default. > - The `scan_result_policy_settings` feature flag was replaced by the `scan_result_policies_block_unprotecting_branches` feature flag in 16.4. +> - The `block_unprotecting_branches` field was [replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137153) by `block_branch_modification` field in GitLab 16.7. +> - The above field was [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423901) in GitLab 16.7. +> - The above field was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423901) in GitLab 16.7. > - The `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. Disabled by default. -> - The `prevent_force_pushing` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420629) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. Disabled by default. +> - The above fields were [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.6. +> - The above fields were [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.7. +> - The `prevent_pushing_and_force_pushing` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420629) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. Disabled by default. +> - The above field was [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.6. +> - The above field was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.7. FLAG: -On self-managed GitLab, by default the `block_unprotecting_branches` field is unavailable. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`. On GitLab.com, this feature is unavailable. -On self-managed GitLab, by default the `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields are unavailable. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. On GitLab.com, this feature is available. -On self-managed GitLab, by default the `prevent_force_pushing` field is unavailable. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. On GitLab.com, this feature is unavailable. +On self-managed GitLab, by default the `block_branch_modification` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`. On GitLab.com, this feature is available. +On self-managed GitLab, by default the `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields are available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. On GitLab.com, this feature is available. +On self-managed GitLab, by default the `prevent_pushing_and_force_pushing` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. On GitLab.com, this feature is available. The settings set in the policy overwrite settings in the project. -| Field | Type | Required | Possible values | Description | -|-------|------|----------|-----------------|-------------| -| `block_unprotecting_branches` | `boolean` | false | `true`, `false` | Prevent a user from removing a branch from the protected branches list, deleting a protected branch, or changing the default branch if that branch is included in the security policy. | -| `prevent_approval_by_author` | `boolean` | false | `true`, `false` | When enabled, two person approval is required on all MRs as merge request authors cannot approve their own MRs and merge them unilaterally. | -| `prevent_approval_by_commit_author` | `boolean` | false | `true`, `false` | When enabled, users who have contributed code to the MR are ineligible for approval, ensuring code committers cannot introduce vulnerabilities and approve code to merge. | -| `remove_approvals_with_new_commit` | `boolean` | false | `true`, `false` | If an MR receives all necessary approvals to merge, but then a new commit is added, new approvals are required. This ensures new commits that may include vulnerabilities cannot be introduced. | -| `require_password_to_approve` | `boolean` | false | `true`, `false` | Password confirmation on approvals provides an additional level of security. Enabling this enforces the setting on all projects targeted by this policy. | -| `prevent_force_pushing` | `boolean` | false | `true`, `false` | Prevent pushing and force pushing to a protected branch. | +| Field | Type | Required | Possible values | Applicable rule type | Description | +|-------------------------------------|-----------|----------|-----------------|----------------------|-------------| +| `block_branch_modification` | `boolean` | false | `true`, `false` | All | When enabled, prevents a user from removing a branch from the protected branches list, deleting a protected branch, or changing the default branch if that branch is included in the security policy. This ensures users cannot remove protection status from a branch to merge vulnerable code. | +| `prevent_approval_by_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, merge request authors cannot approve their own MRs. This ensures code authors cannot introduce vulnerabilities and approve code to merge. | +| `prevent_approval_by_commit_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, users who have contributed code to the MR are ineligible for approval. This ensures code committers cannot introduce vulnerabilities and approve code to merge. | +| `remove_approvals_with_new_commit` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, if an MR receives all necessary approvals to merge, but then a new commit is added, new approvals are required. This ensures new commits that may include vulnerabilities cannot be introduced. | +| `require_password_to_approve` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, there will be password confirmation on approvals. Password confirmation adds an extra layer of security. | +| `prevent_pushing_and_force_pushing` | `boolean` | false | `true`, `false` | All | When enabled, prevents users from pushing and force pushing to a protected branch if that branch is included in the security policy. This ensures users do not bypass the merge request process to add vulnerable code to a branch. | ## Example security scan result policies project @@ -325,6 +334,16 @@ There are several situations where the scan result policy requires an additional - A job in a merge request fails and is configured with `allow_failure: false`. As a result, the pipeline is in a blocked state. - A pipeline has a manual job that must run successfully for the entire pipeline to pass. +### Managing scan findings used to evaluate approval requirements + +Scan result policies evaluate the artifact reports generated by scanners in your pipelines after the pipeline has completed. Scan result policies focus on evaluating the results and determining approvals based on the scan result findings to identify potential risks, block merge requests, and require approval. + +Scan result policies do not extend beyond that scope to reach into artifact files or scanners. Instead, we trust the results from artifact reports. This gives teams flexibility in managing their scan execution and supply chain, and customizing scan results generated in artifact reports (for example, to filter out false positives) if needed. + +Lock file tampering, for example, is outside of the scope of security policy management, but may be mitigated through use of [Code owners](../../project/codeowners/index.md#codeowners-file) or [external status checks](../../project/merge_requests/status_checks.md). For more information, see [issue 433029](https://gitlab.com/gitlab-org/gitlab/-/issues/433029). + + + ### Known issues We have identified in [epic 11020](https://gitlab.com/groups/gitlab-org/-/epics/11020) common areas of confusion in scan result findings that need to be addressed. Below are a few of the known issues: @@ -364,3 +383,30 @@ end.each do |project, configuration_ids| Security::ScanResultPolicies::SyncProjectWorker.perform_async(project.id) end ``` + +### Debugging security approval policy approvals + +GitLab SaaS users may submit a [support ticket](https://about.gitlab.com/support/) titled "Scan result approval policy debugging". Provide the following details: + +- Group path, project path and optionally merge request ID +- Severity +- Current behavior +- Expected behavior + +Support teams will investigate [logs](https://log.gprd.gitlab.net/) (`pubsub-sidekiq-inf-gprd*`) to identify the failure `reason`. Below is an example response snippet from logs. You can use this query to find logs related to approvals: `json.event.keyword: "update_approvals"` and `json.project_path: "group-path/project-path"`. Optionally, you can further filter by the merge request identifier using `json.merge_request_iid`: + +```json +"json": { + "project_path": "group-path/project-path", + "merge_request_iid": 2, + "missing_scans": [ + "api_fuzzing" + ], + "reason": "Scanner removed by MR", + "event": "update_approvals", +} +``` + +Common failure reasons: + +- Scanner removed by MR: Scan result policy expect that the scanners defined in the policy are present and that they successfully produce an artifact for comparison. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index f896616d537..a813ac9888d 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAST analyzers **(FREE ALL)** diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index ed3b33fc35b..992e99f1cc7 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize rulesets **(ULTIMATE ALL)** diff --git a/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png b/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png Binary files differnew file mode 100644 index 00000000000..c86f536afc4 --- /dev/null +++ b/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png diff --git a/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png b/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png Binary files differnew file mode 100644 index 00000000000..199f8b6d322 --- /dev/null +++ b/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 770e24d87ca..ab6d5212227 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Static Application Security Testing (SAST) **(FREE ALL)** @@ -17,7 +17,6 @@ any GitLab tier. The analyzers output JSON-formatted reports as job artifacts. With GitLab Ultimate, SAST results are also processed so you can: -- See them in merge requests. - Use them in approval workflows. - Review them in the security dashboard. @@ -208,7 +207,8 @@ include: A FIPS-compliant image is only available for the Semgrep-based analyzer. -To use SAST in a FIPS-compliant manner, you must [exclude other analyzers from running](analyzers.md#customize-analyzers). +WARNING: +To use SAST in a FIPS-compliant manner, you must [exclude other analyzers from running](analyzers.md#customize-analyzers). If you use a FIPS-enabled image to run Semgrep in [a runner with non-root user](https://docs.gitlab.com/runner/install/kubernetes.html#running-with-non-root-user), you must update the `run_as_user` attribute under `runners.kubernetes.pod_security_context` to use the ID of `gitlab` user [created by the image](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/a5d822401014f400b24450c92df93467d5bbc6fd/Dockerfile.fips#L58), which is `1000`. ## Summary of features per tier @@ -222,6 +222,7 @@ as shown in the following table: | [Customize SAST settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | | Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | +| See new findings in merge request changes | **{dotted-circle}** | **{check-circle}** | | [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | | [Configure SAST by using the UI](#configure-sast-by-using-the-ui) | **{dotted-circle}** | **{check-circle}** | @@ -229,6 +230,35 @@ as shown in the following table: | [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | | [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** | +## View SAST results + +SAST results are shown in the: + +- Merge request widget +- Merge request changes view +- Vulnerability Report + +### Merge request widget **(ULTIMATE ALL)** + +SAST results display in the merge request widget area if a report from the target +branch is available for comparison. The merge request widget displays SAST findings and resolutions that +were introduced by the changes made in the merge request. + + + +### Merge request changes view **(ULTIMATE ALL)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10959) in GitLab 16.6 with a [flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. +On GitLab.com, this feature is available. + +SAST results display in the merge request **Changes** view. Lines containing SAST +issues are marked by a symbol beside the gutter. Select the symbol to see the list of issues, then select an issue to see its details. + + + ## Contribute your scanner The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. @@ -642,7 +672,7 @@ run successfully. For more information, see [Offline environments](../offline_de To use SAST in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- A Docker container registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Configure certificate checking of packages (optional). GitLab Runner has a [default `pull_policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), diff --git a/doc/user/application_security/sast/rules.md b/doc/user/application_security/sast/rules.md index 3fb24bcd66b..187f8b940b2 100644 --- a/doc/user/application_security/sast/rules.md +++ b/doc/user/application_security/sast/rules.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAST rules **(FREE)** diff --git a/doc/user/application_security/sast/troubleshooting.md b/doc/user/application_security/sast/troubleshooting.md index 77a2f20c934..0ac94db4f47 100644 --- a/doc/user/application_security/sast/troubleshooting.md +++ b/doc/user/application_security/sast/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting SAST **(FREE ALL)** diff --git a/doc/user/application_security/secret_detection/automatic_response.md b/doc/user/application_security/secret_detection/automatic_response.md index 1a5ab913b29..762d42d7614 100644 --- a/doc/user/application_security/secret_detection/automatic_response.md +++ b/doc/user/application_security/secret_detection/automatic_response.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automatic response to leaked secrets **(ULTIMATE ALL)** diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 4332b91c0f9..bf7375a58d7 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secret Detection **(FREE ALL)** diff --git a/doc/user/application_security/secret_detection/pre_receive.md b/doc/user/application_security/secret_detection/pre_receive.md new file mode 100644 index 00000000000..1e7ea4aaaeb --- /dev/null +++ b/doc/user/application_security/secret_detection/pre_receive.md @@ -0,0 +1,73 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Pre-receive secret detection **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11439) in GitLab 16.7 as an [Experiment](../../../policy/experiment-beta-support.md) for GitLab Dedicated customers. + +NOTE: +This feature is an [Experiment](../../../policy/experiment-beta-support.md), available only on GitLab Dedicated, and is subject to the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). + +Pre-receive secret detection scans the contents of committed files when they are pushed to a remote repository to prevent the accidental exposure of secrets like keys or API tokens to your repositories. If any secrets are detected, the push is blocked, ensuring that the secrets do not reach your instance. + +Pre-receive secret detection is an Experiment, and only available on GitLab Dedicated. To use secret detection in your instance, use [pipeline secret detection](../index.md) instead. + +## Enable pre-receive secret detection + +Prerequisites: + +- You must be an administrator for your GitLab Dedicated instance. + +1. Sign into your GitLab Dedicated instance as an administrator. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Security and Compliance**. +1. Expand **Secret Detection**. +1. Select the **Enable pre-receive secret detection** checkbox. + +## Limitations + +This feature only scans non-binary blobs under 1 MiB in size. Binary blobs and blobs larger than 1 MiB are not scanned. + +## Resolve a blocked push + +If the blocked secret was added with the most recent commit on your branch: + +1. Remove the secrets from the files. +1. Stage the changes with `git add <file-name>`. +1. Modify the most recent commit to include the changed files with `git commit --amend`. +1. Push your changes with `git push`. + +If the blocked secret appears earlier in your Git history: + +1. Identify the commit SHA from the push error message. If there are multiple, find the earliest using `git log`. +1. Use `git rebase -i <commit-sha>~1` to start an interactive rebase. +1. Mark the offending commits for editing by changing the `pick` command to `edit` in the editor. +1. Remove the secrets from the files. +1. Stage the changes with `git add <file-name>`. +1. Commit the changed files with `git commit --amend`. +1. Continue the rebase with `git rebase --continue` until all secrets are removed. +1. Push your changes with `git push`. + +## Skip secret detection + +In some cases, it may be necessary to skip pre-receive secret detection. For example, a developer may need to commit a placeholder secret for testing, or a user may want to bypass secret detection due to a Git operation timeout. To skip secret detection for a particular secret, add `# gitleaks:allow` to the end of the line. To skip secret detection for all commits in a push, add `[skip secret detection]` to one of the commit messages. For example: + +```ruby +# This secret will be skipped due to gitleaks:allow. +FAKE_TOKEN = allowfaketoken123 # gitleaks:allow + +# This secret will be scanned, and the push will be rejected. +REAL_TOKEN = rejectrealtoken123 +``` + +```shell +# These commits are in the same push. Both will not be scanned. +Add real secret by accident +Add placeholder token to test file [skip secret detection] +``` + +NOTE: +[Pipeline secret detection](../index.md) still scans the bypassed secrets when using `[skip secret detection]` in one of your commit messages. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md index f4fb8c49277..b35de7827e8 100644 --- a/doc/user/application_security/secure_your_application.md +++ b/doc/user/application_security/secure_your_application.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure your application **(FREE ALL)** diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png Binary files differindex 1d324b8207a..f2dcf22f5ab 100644 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png Binary files differindex 46fdebca9cd..6491c99e31c 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 89c950f2473..405017ab023 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Security Dashboards and Security Center **(ULTIMATE ALL)** @@ -19,7 +18,7 @@ you with a collection of metrics, ratings, and charts for the vulnerabilities de The data provided by the Security Dashboards can be used supply to insight on what decisions can be made to improve your security posture. For example, using the 365 day trend view, you can see on which days a significant number of vulnerabilities were introduced. Then you can examine the code changes performed on those particular days in order perform a root-cause analysis to create better policies for preventing the introduction of vulnerabilities in the future. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Security Dashboard](https://www.youtube.com/watch?v=QHQHN4luNpc). +For an overview, see [Security Dashboard](https://www.youtube.com/watch?v=Uo-pDns1OpQ). ## Prerequisites diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index f09672685de..ba501baefb0 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure and Govern glossary **(FREE ALL)** diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 476b2411621..0fda401194d 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Page **(ULTIMATE ALL)** @@ -77,6 +77,47 @@ The following data is shared with third-party AI APIs: record). - Filename. +## Vulnerability resolution **(ULTIMATE SAAS EXPERIMENT)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10779) in GitLab 16.7 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) on GitLab.com. + +Use GitLab Duo Vulnerability resolution to automatically create a merge request that +resolves the vulnerability. + +On GitLab.com this feature is available. By default, it is powered by Google's `code-bison-001` +model. + +We cannot guarantee that the large language model produces results that are correct. Use the +explanation with caution. + +Prerequisites: + +- You must have the GitLab Ultimate subscription tier. +- You must be a member of the project. +- The vulnerability must be a SAST finding. + +Learn more about [how to enable all GitLab Duo features](../../ai_features.md#enable-aiml-features). + +To resolve the vulnerability: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Security and Compliance > Vulnerability report**. +1. In the **Tool** dropdown list, select **SAST**. +1. Select the SAST vulnerability you want resolved. +1. At the top of the vulnerability's page, from the **Resolve with merge request** dropdown list, select **Resolve with AI**. + +A merge request containing the AI remediation suggestions is opened. Review the suggested changes, +then process the merge request according to your standard workflow. + +### Data shared with third-party AI APIs + +The following data is shared with third-party AI APIs: + +- Vulnerability title (which might contain the file name, depending on which scanner is used). +- Vulnerability identifiers. +- Code block. +- File name. + ## Vulnerability status values A vulnerability's status can be: @@ -126,17 +167,9 @@ To change a vulnerability's status from its Vulnerability Page: Details of the status change, including who made the change and when, are recorded in the vulnerability's action log. -## Creating an issue for a vulnerability +## Create a GitLab issue for a vulnerability -From a vulnerability's page you can create an issue to track all action taken to resolve or -mitigate it. - -You can create either: - -- [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). -- [A Jira issue](#create-a-jira-issue-for-a-vulnerability). - -### Create a GitLab issue for a vulnerability +You can create a GitLab issue to track any action taken to resolve or mitigate a vulnerability. To create a GitLab issue for a vulnerability: @@ -145,42 +178,19 @@ To create a GitLab issue for a vulnerability: 1. Select the vulnerability's description. 1. Select **Create issue**. -An issue is created in the project, pre-populated with information from the vulnerability report. -The issue is then opened so you can take further action. +A GitLab issue is created in the project with information from the vulnerability report. -### Create a Jira issue for a vulnerability - -Prerequisites: - -- [Enable Jira integration](../../../integration/jira/configure.md). The - **Enable Jira issue creation from vulnerabilities** option must be selected as part - of the configuration. -- Each user must have a personal Jira user account with permission to create issues in the target - project. - -To create a Jira issue for a vulnerability: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Vulnerability report**. -1. Select the vulnerability's description. -1. Select **Create Jira issue**. -1. If you're not already logged in to Jira, sign in. - -The Jira issue is created and opened in a new browser tab. The **Summary** and **Description** -fields are pre-populated from the vulnerability's details. - -Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the -GitLab user interface. +To create a Jira issue, see [Create a Jira issue for a vulnerability](../../../integration/jira/configure.md#create-a-jira-issue-for-a-vulnerability). ## Linking a vulnerability to GitLab and Jira issues You can link a vulnerability to one or more existing [GitLab](#create-a-gitlab-issue-for-a-vulnerability) -or [Jira](#create-a-jira-issue-for-a-vulnerability) issues. Only one linking feature is available at the same time. +or [Jira](../../../integration/jira/configure.md#create-a-jira-issue-for-a-vulnerability) issues. Only one linking feature is available at the same time. Adding a link helps track the issue that resolves or mitigates a vulnerability. ### Link a vulnerability to existing GitLab issues -Prerequisite: +Prerequisites: - [Jira issue integration](../../../integration/jira/configure.md) must not be enabled. @@ -209,7 +219,7 @@ Be aware of the following conditions between a vulnerability and a linked GitLab ### Link a vulnerability to existing Jira issues -Prerequisite: +Prerequisites: - [Jira issue integration](../../../integration/jira/configure.md) must be enabled, with option **Enable Jira issue creation from vulnerabilities** also enabled. @@ -282,7 +292,7 @@ To manually apply the patch that GitLab generated for a vulnerability: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. NOTE: -Security training is not accessible in an environment that is offline, meaning computers that are isolated from the public internet as a security measure. Some third-party training vendors may require you to sign up for a _free_ account. Sign up for an account by going to +Security training is not accessible in an environment that is offline, meaning computers that are isolated from the public internet as a security measure. Specifically, the GitLab server needs the ability to query the API endpoints for any training provider you choose to enable. Some third-party training vendors may require you to sign up for a _free_ account. Sign up for an account by going to any of [Secure Code Warrior](https://www.securecodewarrior.com/), [Kontra](https://application.security/), or [SecureFlag](https://www.secureflag.com/). GitLab does not send any user information to these third-party vendors; we do send the CWE or OWASP identifier and the language name of the file extension. diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index db6b4e0f4a8..0db848d6d11 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability severity levels **(ULTIMATE ALL)** diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index e71aab5839e..23454bf387a 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Report **(ULTIMATE ALL)** @@ -12,7 +11,7 @@ cumulative results of all successful jobs, regardless of whether the pipeline wa pipeline are only ingested after all the jobs in the pipeline complete. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Vulnerability Management](https://www.youtube.com/watch?v=8SJHz6BCgXM). +For an overview, see [Vulnerability Management](https://www.youtube.com/watch?v=alMRIq5UPbw). At all levels, the Vulnerability Report contains: @@ -29,8 +28,8 @@ At the project level, the Vulnerability Report also contains: The **Activity** column contains icons to indicate the activity, if any, taken on the vulnerability in that row: -- Issues **{issues}**: Links to issues created for the vulnerability. For more details, read - [Create an issue for a vulnerability](../vulnerabilities/index.md#creating-an-issue-for-a-vulnerability). +- Issues **{issues}**: Links to issues created for the vulnerability. For more information, see + [Create a GitLab issue for a vulnerability](../vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability). - Wrench **{admin}**: The vulnerability has been remediated. - False positive **{false-positive}**: The scanner determined this vulnerability to be a false positive. @@ -81,6 +80,8 @@ Additionally, the [project filter](#project-filter) is available at the group le To filter the list of vulnerabilities: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Vulnerability report**. 1. Select a filter. 1. Select values from the dropdown list. 1. Repeat the above steps for each desired filter. @@ -92,13 +93,33 @@ After each filter is selected: ### Tool filter -The tool filter allows you to focus on vulnerabilities detected by selected tools. +> Project-level tool filter [introduced](https://gitlab.com/groups/gitlab-org/-/epics/11237) in GitLab 16.6. + +You can filter vulnerabilities by the tool that detected them. By default, the +vulnerability report lists vulnerabilities from all tools. When you select a heading, you select all the tools +under that heading. + +::Tabs + +:::TabTitle GitLab 16.6 and later + +The content of the tool filter for both projects and groups depends on the following: + +- If you've integrated and enabled third-party analyzers, the tool filter is grouped by + scanning category (for example, container scanning, DAST, and dependency scanning). Scanner + entries are only shown if the scanner detected vulnerabilities. +- If you have not integrated any third-party analyzers, see GitLab 16.5 and + earlier. -When using the tool filter, you can choose: +:::TabTitle GitLab 16.5 and earlier -- **All tools** (default). -- Individual GitLab-provided tools. -- Any integrated third-party tool. +The content of the tool filter at all levels is categorized first by the analyzer's vendor, then by +scanning category. If you've only enabled GitLab analyzers, only those analyzers are listed in the +tool filter. + +::EndTabs + +To filter vulnerabilities that were added manually, use the **Manually added** filter. For details of each of the available tools, see [Security scanning tools](../index.md#application-coverage). @@ -113,7 +134,7 @@ The content of the Project filter depends on the current level: ### Activity filter The activity filter behaves differently from the other filters. You can select only one value in -each category. +each category. To remove a filter, from the activity filter dropdown list select the filter you want to remove. Selection behavior when using the activity filter: @@ -146,12 +167,19 @@ To view the relevant file, select the filename in the vulnerability's details. > Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0. -From the Vulnerability Report you can change the status of one or more vulnerabilities. +As you triage vulnerabilities you can change their status, including dismissing vulnerabilities. + +When a vulnerability is dismissed, the audit log includes a note of who dismissed it, when it was +dismissed, and the reason it was dismissed. You cannot delete vulnerability records, so a permanent +record always remains. -To change the status of vulnerabilities in the table: +To change the status of vulnerabilities: -1. Select the checkbox beside each vulnerability you want to update the status of. To select all, - select the checkbox in the table header. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Vulnerability report**. +1. To select: + - One or more vulnerabilities, select the checkbox beside each vulnerability. + - All vulnerabilities on the page, select the checkbox in the table header. 1. In the **Set status** dropdown list, select the desired status. 1. If the **Dismissed** status is chosen, select the desired reason in the **Set dismissal reason** dropdown list. 1. In the **Add a comment** input, you can provide a comment. For the **Dismissed** status, a comment is required. @@ -173,11 +201,11 @@ apply to the export. Fields included are: +- Status (See the following table for details of how the status value is exported.) - Group name - Project name - Tool - Scanner name -- Status - Vulnerability - Basic details - Additional information @@ -198,6 +226,16 @@ Full details are available through our Use one of the `gl-*-report.json` report filenames in place of `*artifact_path` to obtain, for example, the path of files in which vulnerabilities were detected. +The Status field's values shown in the vulnerability report are different to those contained +in the vulnerability export. Use the following reference table to match them. + +| Vulnerability report | Vulnerability export | +|:---------------------|:---------------------| +| Needs triage | detected | +| Dismissed | dismissed | +| Resolved | resolved | +| Confirmed | confirmed | + ### Export details in CSV format To export details of all vulnerabilities listed in the Vulnerability Report, select **Export**. @@ -209,57 +247,41 @@ NOTE: It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Do not close the page until the download finishes. -## Dismiss a vulnerability - -When you evaluate a vulnerability and decide it requires no more action, -you can mark it as **Dismissed**. -Dismissed vulnerabilities do not appear in the merge request security widget -when detected in future scans. - -When a vulnerability is dismissed in a project or group, a record is made of: - -- Who dismissed it. -- Date and time when it was dismissed. -- Optionally, a reason why it was dismissed. - -Vulnerability records cannot be deleted, so a permanent record always remains. - -You can dismiss a vulnerability in projects and groups: - -1. Select the vulnerability in the Security Dashboard. -1. In the upper-right corner, from the **Status** dropdown list, select **Dismissed**. -1. Optional. Add a reason for the dismissal and select **Save comment**. - -To undo this action, select a different status from the same menu. - -## Manually add a vulnerability finding +## Manually add a vulnerability > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353796) in GitLab 14.10. > - [Feature flag `new_vulnerability_form`](https://gitlab.com/gitlab-org/gitlab/-/issues/359049) removed in GitLab 15.0. -To add a new vulnerability finding from your project level Vulnerability Report page: +Add a vulnerability manually when it is not available in the GitLab vulnerabilities database. You +can add a vulnerability only in a project's vulnerability report. + +To add a vulnerability manually: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. -You are brought to the newly created vulnerability's detail page. Manually created records appear in the -Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. +The newly-created vulnerability's detail page is opened. ## Group vulnerabilities -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420055) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_grouping`. Disabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10164) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_grouping`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/422509) in GitLab 16.6. Feature flag `vulnerability_report_grouping` removed. -To group the Vulnerability Report: +In the project-level vulnerability report you can group vulnerabilities, enabling more efficient +triaging. -1. Below the **Vulnerability Report** filters, select the **Group By** dropdown list. -1. Select the attribute you want to group by: status or severity. +To group vulnerabilities in the vulnerability report: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Vulnerability report**. +1. From the **Group By** dropdown list, select an attribute. -To see what is included in a group, select a category to expand the report and see related -vulnerabilities. +Vulnerabilities are grouped according to the attribute you selected. Each group is collapsed, with +totals per group displayed beside their name. To see the vulnerabilities in each group, select the group's +name. ## Operational vulnerabilities diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index ef66925b9c9..e60ac7d4c21 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -1,54 +1,45 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# View vulnerabilities in a pipeline +# Vulnerabilities in a pipeline -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. +All enabled security analyzers run in the pipeline and output their results as artifacts. These +artifacts are processed, including [deduplication](#deduplication-process), and the results are +listed on the pipeline **Security** tab. By identifying vulnerability +[findings](../terminology/index.md#finding) in a pipeline, you can address the risks +proactively. + +The following criteria apply to the pipeline security tab: + +- The results of only successful security scan jobs are shown. For example, if a pipeline contains + SAST and DAST jobs, but the DAST job fails, only the SAST results are shown. +- If the pipeline has a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), + the pipeline waits for the manual job, and the vulnerabilities cannot be displayed if the blocking + manual job did not run. +- Findings have an expiry period. Expired findings are not shown on the pipeline security tab. For + details, see [Retention period for findings](#retention-period-for-findings). + +## View vulnerabilities in a pipeline To view vulnerabilities in a pipeline: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipelines**. -1. From the list, select the pipeline you want to check for vulnerabilities. +1. Select the pipeline. 1. Select the **Security** tab. -A pipeline consists of multiple jobs, which may include security scans. When a job declares and produces security scan -reports using [`artifacts:reports`](../../../ci/yaml/artifacts_reports.md), GitLab parses and ingests the contents of -these reports to create vulnerabilities associated with the project the pipeline belongs to. - -If a job fails to finish, the pipeline vulnerability report doesn't show vulnerability findings detected by this job. -For example, if a pipeline contains DAST and SAST jobs, but the DAST job fails by returning a non-zero -[exit code](../../../development/integrations/secure.md#exit-code), the report doesn't show DAST results. - -The pipeline vulnerability report only shows results contained in the security report artifacts. This report differs from -the [vulnerability report](index.md), which contains cumulative results of all successful jobs, and from the merge request -[security widget](../index.md#merge-request), which contains new vulnerability findings that don't already exist on the default branch. - -NOTE: -If a new advisory is added to our advisory database and the last pipeline for the default branch is stale, the resulting vulnerability may appear in the MR widget as "New" when it is already in the default branch. This will be resolved by [Continuous Vulnerability Scans](https://gitlab.com/groups/gitlab-org/-/epics/7886). - -The pipeline vulnerability report only displays after the pipeline is complete. If the pipeline has a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), the pipeline waits for the manual job and the vulnerabilities cannot be displayed if the blocking manual job did not run. - -Before GitLab displays results, the vulnerability findings in all pipeline reports are [deduplicated](#deduplication-process). - ## Scan details -**Scan details** shows a summary of vulnerability findings in the pipeline and the source reports. - -GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) artifact present in -the pipeline. +The **Scan details** section shows a summary of vulnerability findings in the pipeline and the +source reports. -Each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings -in the report doesn't match the number in **Scan details**, ensure that **Hide dismissed** is disabled. +GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) +artifact present in the pipeline. -### Download security scan outputs - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/333660) in GitLab 14.2. +## Downloading security scan results Depending on the type of security scanner, you can download: @@ -57,22 +48,32 @@ Depending on the type of security scanner, you can download: To download a security scan output: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Build > Pipelines**. +1. Select the pipeline. +1. Select the **Security** tab. 1. In **Scan details**, select **Download results**: - - To download a JSON file, select the JSON artifact. - - To download a CSV file, select **Download scanned resources**. + - To download a JSON file, select the JSON artifact. + - To download a CSV file, select **Download scanned resources**. ## Scan results -This shows a list of the combined results for all security report artifacts. The filters work like the -[Vulnerability Report filters](index.md#vulnerability-report-filters), but they are limited to **Severity** and **Tool**, with -the addition of a **Hide dismissed** toggle. +Findings present in the source branch are listed in descending order of severity. You can filter the +list of findings by severity and tool. You can also download the results of the security scans, for +analysis outside GitLab. + +Findings that are dismissed are hidden by default. To see these findings, turn off the +**Hide dismissed** toggle. + +For each finding you can: -When you review the vulnerability findings reported in the pipeline, you can select one or more entries for dismissal, -similar to [Dismissing a vulnerability](index.md#dismiss-a-vulnerability) in the Vulnerability Report. +- Get more information about the finding. +- Create an issue for the finding. +- Dismiss the finding. -When you merge the branch corresponding to the pipeline into the default branch, all reported findings are combined into -the [Vulnerability Report](index.md). Scan results in pipelines executed on the default branch are -incorporated once the pipeline finishes. +When you merge the merge request's branch into the target branch, all reported findings are +in the [vulnerability report](index.md). Scan results in pipelines executed on the +default branch are incorporated after the pipeline finishes, according to the following table: | Existing vulnerability status | Dismissed in pipeline? | New vulnerability status | |:------------------------------|:-----------------------|:-------------------------| @@ -81,18 +82,18 @@ incorporated once the pipeline finishes. | Confirmed | No | Confirmed | | Needs triage (Detected) | No | Needs triage (Detected) | | Resolved | No | Needs triage (Detected) | -| N/A (That is: new vulnerability) | No | Needs triage (Detected) | +| N/A (New vulnerability) | No | Needs triage (Detected) | -## Retention period for vulnerabilities +## Retention period for findings > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351524) in GitLab 15.5. -GitLab has the following retention policies for vulnerabilities on non-default branches. Vulnerabilities are no longer available: +Findings are no longer available: - When the related CI job artifact expires. - 90 days after the pipeline is created, even if the related CI job artifacts are locked. -To view vulnerabilities, either: +To view findings, either: - Run a new pipeline. - Download the related CI job artifacts if they are available. @@ -104,7 +105,7 @@ This does not apply for the vulnerabilities existing on the default branch. When a pipeline contains jobs that produce multiple security reports of the same type, it is possible that the same vulnerability finding is present in multiple reports. This duplication is common when different scanners are used to -increase coverage, but can also exist within a single report. The deduplication process allows you to maximize the vulnerability scanning coverage while reducing +increase coverage, but can also exist in a single report. The deduplication process allows you to maximize the vulnerability scanning coverage while reducing the number of findings you need to manage. A finding is considered a duplicate of another finding when their [scan type](../terminology/index.md#scan-type-report-type), diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index b481c0458aa..ea62384b35e 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # AsciiDoc **(FREE ALL)** diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index a1281d3d75c..9ff3837653e 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a Kubernetes cluster **(FREE ALL)** @@ -114,7 +114,7 @@ Choose the context to run `kubectl` commands from your CI/CD scripts. In the project where you want to run Kubernetes commands, edit your project's `.gitlab-ci.yml` file. In the first command under the `script` keyword, set your agent's context. -Use the format `path/to/agent/repository:agent-name`. For example: +Use the format `<path/to/agent/project>:<agent-name>`. For example: ```yaml deploy: @@ -123,7 +123,7 @@ deploy: entrypoint: [''] script: - kubectl config get-contexts - - kubectl config use-context path/to/agent/repository:agent-name + - kubectl config use-context path/to/agent/project:agent-name - kubectl get pods ``` @@ -138,7 +138,7 @@ Set the value of `KUBE_CONTEXT` to the context of the agent you want Auto DevOps ```yaml deploy: variables: - KUBE_CONTEXT: <path_to_agent_config_repository>:<agent_name> + KUBE_CONTEXT: path/to/agent/project:agent-name ``` You can assign different agents to separate Auto DevOps jobs. For instance, @@ -162,7 +162,7 @@ When you deploy to an environment that has both a - The certificate-based cluster's context is called `gitlab-deploy`. This context is always selected by default. - In GitLab 14.9 and later, agent contexts are included in `$KUBECONFIG`. - You can select them by using `kubectl config use-context path/to/agent/repository:agent-name`. + You can select them by using `kubectl config use-context <path/to/agent/project>:<agent-name>`. - In GitLab 14.8 and earlier, you can still use agent connections, but for environments that already have a certificate-based cluster, the agent connections are not included in `$KUBECONFIG`. diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index d79d32a1234..df63d8ce7be 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitOps with a Kubernetes cluster **(FREE ALL)** diff --git a/doc/user/clusters/agent/gitops/agent.md b/doc/user/clusters/agent/gitops/agent.md index a4e83916acb..2eba00f0c78 100644 --- a/doc/user/clusters/agent/gitops/agent.md +++ b/doc/user/clusters/agent/gitops/agent.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitOps with the agent for Kubernetes (deprecated) **(FREE ALL)** diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md deleted file mode 100644 index 13fcfeb28e9..00000000000 --- a/doc/user/clusters/agent/gitops/flux.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../gitops.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../gitops.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md index 2c4796adf2b..e1832de51af 100644 --- a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md @@ -8,7 +8,7 @@ info: A tutorial for deploying an OCI artifact using Flux This tutorial teaches you how to package your Kubernetes manifests into an [OCI](https://opencontainers.org/) artifact and deploy them to your cluster using Flux. You'll set up a sample manifest project, configure it to -store manifests as an artifact in the project's Container Registry, and configure Flux to sync the artifact. With this +store manifests as an artifact in the project's container registry, and configure Flux to sync the artifact. With this setup, you can run additional steps in GitLab pipelines before Flux picks up the changes from the OCI image. @@ -63,7 +63,7 @@ First, create a repository for your Kubernetes manifests: ## Configure the manifest repository to create an OCI artifact Next, configure [GitLab CI/CD](../../../../ci/index.md) to package your manifests into an OCI artifact, -and push the artifact to the [GitLab Container Registry](../../../packages/container_registry/index.md): +and push the artifact to the [GitLab container registry](../../../packages/container_registry/index.md): 1. In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/index.md#the-gitlab-ciyml-file) file with the following contents: @@ -92,9 +92,9 @@ and push the artifact to the [GitLab Container Registry](../../../packages/conta - Uses `kustomization.yaml` to render your final Kubernetes manifests. - Packages your manifests into an OCI artifact. - - Pushes the OCI artifact to the Container Registry. + - Pushes the OCI artifact to the container registry. - After the pipeline has completed, you can check your OCI artifact with the Container Registry UI. + After the pipeline has completed, you can check your OCI artifact with the container registry UI. ## Configure Flux to sync your artifact diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md deleted file mode 100644 index 22587cd0e5d..00000000000 --- a/doc/user/clusters/agent/gitops/helm.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../gitops.md' -remove_date: '2023-10-22' ---- - -This document was moved to [another location](../gitops.md). - -<!-- This redirect file can be deleted after 2023-10-22. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/clusters/agent/gitops/secrets_management.md b/doc/user/clusters/agent/gitops/secrets_management.md index a9590f34183..52aa046a01a 100644 --- a/doc/user/clusters/agent/gitops/secrets_management.md +++ b/doc/user/clusters/agent/gitops/secrets_management.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing Kubernetes secrets in a GitOps workflow (deprecated) @@ -13,7 +13,7 @@ To manage cluster resources with GitOps, you should use the [Flux integration](. You should never store Kubernetes secrets in unencrypted form in a `git` repository. If you use a GitOps workflow, you can follow these steps to securely manage your secrets. 1. Set up the Sealed Secrets controller to manage secrets. -1. Deploy Docker credentials so the cluster can pull images from the GitLab Container Registry. +1. Deploy Docker credentials so the cluster can pull images from the GitLab container registry. ## Prerequisites @@ -49,7 +49,7 @@ For more details on how the Sealed Secrets controller works, view [the usage ins ## Deploy Docker credentials -To deploy containers from the GitLab Container Registry, you must configure the cluster with the proper Docker registry credentials. You can achieve this by deploying a `docker-registry` type secret. +To deploy containers from the GitLab container registry, you must configure the cluster with the proper Docker registry credentials. You can achieve this by deploying a `docker-registry` type secret. 1. Generate a GitLab token with at least `read-registry` rights. The token can be either a Personal or a Project Access Token. 1. Create a Kubernetes secret manifest YAML file. Update the values as needed: diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 140ac060dc7..66e67f56172 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connecting a Kubernetes cluster with GitLab @@ -63,13 +63,20 @@ GitLab in a Kubernetes cluster, you might need a different version of Kubernetes You can upgrade your Kubernetes version to a supported version at any time: -- 1.27 (support ends on July 22, 2024 or when 1.30 becomes supported) -- 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported) +- 1.27 (support ends on July 18, 2024 or when 1.30 becomes supported) +- 1.26 (support ends on March 21, 2024 or when 1.29 becomes supported) - 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported) GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor versions at any given time. +When a new version of Kubernetes is released, we will: + +- Update this page with the results of our early smoke tests within approximately + four weeks. +- If we expect a delay in releasing new version support, we will update this page + with the expected GitLab support version within approximately eight weeks. + When installing the agent, use a Helm version compatible with your Kubernetes version. Other versions of Helm might not work. For a list of compatible versions, see the [Helm version support policy](https://helm.sh/docs/topics/version_skew/). Support for deprecated APIs can be removed from the GitLab codebase when we drop support for the Kubernetes version that only supports the deprecated API. diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 588be3a1223..5b07dbd56d9 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Installing the agent for Kubernetes **(FREE ALL)** diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index c01b1337aca..f9c3ab93906 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting the GitLab agent for Kubernetes diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index b3735770a97..80ee7303dfc 100644 --- a/doc/user/clusters/agent/user_access.md +++ b/doc/user/clusters/agent/user_access.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Grant users Kubernetes access **(FREE ALL BETA)** @@ -147,7 +147,7 @@ subjects: You can configure an agent to allow GitLab users to access a cluster with the Kubernetes API. -Prerequisite: +Prerequisites: - You have an agent configured with the `user_access` entry. diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index e57551fc8c1..18f46878eb4 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operational Container Scanning **(ULTIMATE ALL)** diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 70abbebaaad..e1f84197405 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing the agent for Kubernetes instances **(FREE ALL)** @@ -12,7 +12,7 @@ Use the following tasks when you work with the agent for Kubernetes. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, the installed `agentk` version is displayed on the **Agent** tab. -Prerequisite: +Prerequisites: - You must have at least the Developer role. diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md index 8dfeafeb48e..d6a07d26c09 100644 --- a/doc/user/clusters/create/index.md +++ b/doc/user/clusters/create/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create Kubernetes clusters diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 4a6fa8d4862..96281f2fa50 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster Environments (deprecated) **(PREMIUM ALL)** diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f2f9aceda69..178f1bd7705 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster management project (deprecated) **(FREE ALL)** @@ -62,8 +62,7 @@ To associate a cluster management project with your cluster: - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - [Instance-level cluster](../instance/clusters/index.md): - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Kubernetes**. 1. Expand **Advanced settings**. 1. From the **Cluster management project** dropdown list, select the cluster management project diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index a40fc5a262e..2b5ccd92566 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage cluster applications **(FREE ALL)** 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 4bd42abb9e8..e9c32eaad43 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE ALL)** diff --git a/doc/user/compliance/compliance_center/index.md b/doc/user/compliance/compliance_center/index.md index 4a42a70a7e7..63b4560a498 100644 --- a/doc/user/compliance/compliance_center/index.md +++ b/doc/user/compliance/compliance_center/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance center **(ULTIMATE ALL)** @@ -16,14 +15,14 @@ See report and manage standards adherence, violations, and compliance frameworks > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125875) GraphQL APIs in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `compliance_adherence_report`. Disabled by default. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125444) standards adherence dashboard in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `adherence_report_ui`. Disabled by default. > - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/414495) in GitLab 16.5. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can -[disable the feature flags](../../../administration/feature_flags.md) named `compliance_adherence_report` and `adherence_report_ui`. On GitLab.com, -this feature is available. +> - [Feature flag `compliance_adherence_report` and `adherence_report_ui`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137398) removed in GitLab 16.7. +> - Standards adherence filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413734) in GitLab 16.7. Standards adherence dashboard lists the adherence status of projects complying to GitLab standard. +When a project is added or an associated project or group setting is changed, an adherence scan is run on that project to update the standards adherence for that project. The date in the +**Last Scanned** column reflects any changes. + ### View the standards adherence dashboard Prerequisites: @@ -33,7 +32,13 @@ Prerequisites: To view the standards adherence dashboard for a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. + +You can filter the standards adherence dashboard on: + +- The project that the check was performed on. +- The type of check that was performed on a project. +- The standard that the check belongs to. ### GitLab standard @@ -101,7 +106,7 @@ Prerequisites: To view the compliance violations report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. You can sort the compliance report on: @@ -188,9 +193,9 @@ Prerequisites: To export a report of merge request compliance violations for projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. On the page, select the **Violations** tab. -1. On the Violations tab, select the **Export full report as CSV** action in the top right corner +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export violations report**. A report is compiled and delivered to your email inbox as an attachment. @@ -235,8 +240,9 @@ If the commit has a related merge commit, then the following are also included: To generate the Chain of Custody report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. Select **List of all merge commits**. +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export chain of custody report**. Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. @@ -251,10 +257,10 @@ details for the provided commit SHA. To generate a commit-specific Chain of Custody report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. At the top of the compliance report, to the right of **List of all commits**, select the down arrow - (**{chevron-lg-down}**). -1. Enter the commit SHA, and then select **Export commit custody report**. +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export custody report of a specific commit**. +1. Enter the commit SHA, and then select **Export custody report**. Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. @@ -283,7 +289,7 @@ Prerequisites: To view the compliance projects report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. ### Apply a compliance framework to projects in a group @@ -300,7 +306,7 @@ Prerequisites: To apply a compliance framework to one project in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Next to the project you want to add the compliance framework to, select **{plus}** **Add framework**. 1. Select an existing compliance framework or create a new one. @@ -308,7 +314,7 @@ To apply a compliance framework to one project in a group: To apply a compliance framework to multiple projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Select multiple projects. 1. From the **Choose one bulk action** dropdown list, select **Apply framework to selected projects**. @@ -329,14 +335,14 @@ Prerequisites: To remove a compliance framework from one project in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Next to the compliance framework to remove from the project, select **{close}** on the framework label. To remove a compliance framework from multiple projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Select multiple projects. 1. From the **Choose one bulk action** dropdown list, select **Remove framework from selected projects**. @@ -358,9 +364,9 @@ Prerequisites: To export a report of compliance frameworks on projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. On the page, select the **Projects** tab. -1. On the Frameworks tab, select the **Export as CSV** action in the top right corner +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export list of project frameworks**. A report is compiled and delivered to your email inbox as an attachment. @@ -371,13 +377,13 @@ A report is compiled and delivered to your email inbox as an attachment. To filter the list of compliance frameworks: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. In the search field: 1. Select the attribute you want to filter by. 1. Select an operator. 1. Select from the list of options or enter text for the search. -1. Select **Search** (**{search}**). +1. Select **Search**. Repeat this process to filter by multiple attributes. @@ -406,5 +412,5 @@ Prerequisites: To view the compliance projects report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md deleted file mode 100644 index 998e9c81d18..00000000000 --- a/doc/user/compliance/compliance_report/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../compliance_center/index.md' -remove_date: '2023-09-20' ---- - -This document was moved to [another location](../compliance_center/index.md). - -<!-- This redirect file can be deleted after <2023-09-20>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index 51053c03d8c..167eeddc00d 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance **(ULTIMATE ALL)** diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md index cf5f340c0f6..9ec48e74aa9 100644 --- a/doc/user/compliance/license_approval_policies.md +++ b/doc/user/compliance/license_approval_policies.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License approval policies **(ULTIMATE ALL)** @@ -40,7 +39,7 @@ Create a license approval policy to enforce license compliance. To create a license approval policy: -1. [Link a security policy project](../application_security/policies/index.md#managing-the-linked-security-policy-project) to your development group, subgroup, or project (the Owner role is required). +1. [Link a security policy project](../application_security/policies/index.md#policy-implementation) to your development group, subgroup, or project (the Owner role is required). 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. 1. Create a new [Scan Result Policy](../application_security/policies/scan-result-policies.md). diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md index 7ad19775509..43d76845ffa 100644 --- a/doc/user/compliance/license_list.md +++ b/doc/user/compliance/license_list.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License list **(ULTIMATE ALL)** diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md index 5d7a689e610..120d0ebcc31 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License scanning of CycloneDX files **(ULTIMATE ALL)** @@ -11,14 +10,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385176) in GitLab 16.4. Feature flags `license_scanning_sbom_scanner` and `package_metadata_synchronization` removed. NOTE: -The legacy License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. To continue using GitLab for License Compliance, remove the License Compliance template from your CI/CD pipeline and add the [Dependency Scanning template](../../application_security/dependency_scanning/index.md#configuration). The Dependency Scanning template is now capable of gathering the required license information so it is no longer necessary to run a separate License Compliance job. The License Compliance CI/CD template should not be removed prior to verifying that the instance has been upgraded to a version that supports the new method of license scanning. To begin using the Dependency Scanner quickly at scale, you may set up a [scan execution policy](../../application_security/policies/scan-execution-policies.md) at the group level to enforce the SBOM-based license scan for all projects in the group. Then, you may remove the inclusion of the `Jobs/License-Scanning.gitlab-ci.yml` template from your CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do so by setting the `LICENSE_MANAGEMENT_VERSION CI` variable to `4`. This variable can be set at the [project](../../../ci/variables/index.md#for-a-project), [group](../../../ci/variables/index.md#for-a-group) or [instance](../../../ci/variables/index.md#for-an-instance) level. This configuration change will allow you to continue using the existing version of License Compliance to generate [license scanning report](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) artifacts in your pipelines. However, since legacy license scanning support is being removed from our codebase, switching back to this legacy analyzer prevents other License Compliance features from working as expected, so this approach is not recommended. In addition to this, **bugs and vulnerabilities in this legacy analyzer will no longer be fixed.** +The legacy License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. +To continue using GitLab for License Compliance, remove the License Compliance template from your +CI/CD pipeline and add the [Dependency Scanning template](../../application_security/dependency_scanning/index.md#configuration). +The Dependency Scanning template is now capable of gathering the required license information so it +is no longer necessary to run a separate License Compliance job. The License Compliance CI/CD +template should not be removed prior to verifying that the instance has been upgraded to a version +that supports the new method of license scanning. To begin using the Dependency Scanner quickly at +scale, you may set up a [scan execution policy](../../application_security/policies/scan-execution-policies.md) +at the group level to enforce the SBOM-based license scan for all projects in the group. +Then, you may remove the inclusion of the `Jobs/License-Scanning.gitlab-ci.yml` template from your +CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do +so by setting the `LICENSE_MANAGEMENT_VERSION CI` variable to `4`. This variable can be set at the +[project](../../../ci/variables/index.md#for-a-project), [group](../../../ci/variables/index.md#for-a-group) +or [instance](../../../ci/variables/index.md#for-an-instance) level. To detect the licenses in use, License Compliance relies on running the [Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), and analyzing the [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) generated by those jobs. -Other 3rd party scanners may also be used as long as they produce a CycloneDX file with a list of dependencies for [one of our supported languages](#supported-languages-and-package-managers). -This method of scanning is also capable of parsing and identifying over 500 different types of licenses, as defined in [the SPDX list](https://spdx.org/licenses/). -Licenses not in the SPDX list are reported as "Unknown". License information can also be extracted from packages that are dual-licensed, or have multiple different licenses that apply. +This method of scanning is capable of parsing and identifying over 500 different types of licenses, as defined in [the SPDX list](https://spdx.org/licenses/). +Third-party scanners may be used to generate the list of dependencies, as long as they produce a CycloneDX report artifact for [one of our supported languages](#supported-languages-and-package-managers) and follow the [GitLab CycloneDX property taxonomy](../../../development/sec/cyclonedx_property_taxonomy.md). Note that it is not yet possible to use a CI report artifact as a source of data for license information, and licenses that are not in the SPDX list are reported as "Unknown". +The ability to provide other licenses is tracked in [epic 10861](https://gitlab.com/groups/gitlab-org/-/epics/10861). + +NOTE: +The License Scanning feature relies on publicly available package metadata collected in an +external database and synced with the GitLab instance automatically. This database is a multi-region Google Cloud Storage bucket hosted in the United States. +The scan is executed exclusively within the GitLab instance. +No contextual information (for example, a list of project dependencies) is sent to the external service. ## Configuration @@ -26,7 +44,7 @@ To enable License scanning of CycloneDX files: - Enable [Dependency Scanning](../../application_security/dependency_scanning/index.md#enabling-the-analyzer) and ensure that its prerequisites are met. -- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then please refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. +- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. ## Supported languages and package managers @@ -110,12 +128,8 @@ The supported files and versions are the ones supported by ## License expressions -GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). -License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, -if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](../license_approval_policies.md), -GitLab evaluates the composite license as _denied_, as this is the safer option. -The ability to support other license expression operators (like `OR`, `WITH`) is tracked -in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). +The License Scanning of CycloneDX files does not support [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). +Adding this capability is tracked in issue [336878](https://gitlab.com/gitlab-org/gitlab/-/issues/336878). ## Blocking merge requests based on detected licenses diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 46e395af5bc..4f1eeb3578c 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customer relations management (CRM) **(FREE ALL)** diff --git a/doc/user/custom_roles.md b/doc/user/custom_roles.md index bbb48724078..1f3628efa39 100644 --- a/doc/user/custom_roles.md +++ b/doc/user/custom_roles.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom roles **(ULTIMATE ALL)** @@ -15,7 +15,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Ability to create and remove a custom role with the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393235) in GitLab 16.4. > - Ability to manage group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) in GitLab 16.5. > - Ability to manage project access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `manage_project_access_tokens`. -> - Ability to archive projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.6 in [with a flag](../administration/feature_flags.md) named `archive_project`. Disabled by default. +> - Ability to archive projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.7. +> - Ability to use the UI to add a user to your group with a custom role, change a user's custom role, or remove a custom role from a group member [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393239) in GitLab 16.7. Custom roles allow group Owners or instance administrators to create roles specific to the needs of their organization. @@ -50,7 +51,7 @@ with the ability to: ### GitLab SaaS -Prerequisite: +Prerequisites: - You must have the Owner role in the group you are creating the custom role in. @@ -59,25 +60,40 @@ Prerequisite: 1. Select **Add new role**. 1. In **Base role to use as template**, select an existing non-custom role. 1. In **Role name**, enter the custom role's title. +1. Optional. In **Description**, enter a description for the custom role. 1. Select the **Permissions** for the new custom role. 1. Select **Create new role**. +In **Settings > Roles and Permissions**, the list of all custom roles displays the: + +- Custom role name. +- Role ID. +- Base role that the custom role uses as a template. +- Permissions. + ### Self Managed GitLab Instances -Prerequisite: +Prerequisites: - You must be an administrator for the self-managed instance you are creating the custom role in. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Roles and Permissions**. 1. From the top dropdown list, select the group you want to create a custom role in. 1. Select **Add new role**. 1. In **Base role to use as template**, select an existing non-custom role. 1. In **Role name**, enter the custom role's title. +1. Optional. In **Description**, enter a description for the custom role. 1. Select the **Permissions** for the new custom role. 1. Select **Create new role**. +In **Settings > Roles and Permissions**, the list of all custom roles displays the: + +- Custom role name. +- Role ID. +- Base role that the custom role uses as a template. +- Permissions. + To create a custom role, you can also [use the API](../api/member_roles.md#add-a-member-role-to-a-group). ### Available permissions @@ -95,10 +111,10 @@ These requirements are documented in the `Required permission` column in the fol | `read_vulnerability` | GitLab 16.1 and later | Not applicable | View [vulnerability reports](application_security/vulnerability_report/index.md). | | `admin_vulnerability` | GitLab 16.1 and later | `read_vulnerability` | Change the [status of vulnerabilities](application_security/vulnerabilities/index.md#vulnerability-status-values). | | `read_dependency` | GitLab 16.3 and later | Not applicable | View [project dependencies](application_security/dependency_list/index.md). | -| `admin_merge_request` | GitLab 16.4 and later | Not applicable | View and approve [merge requests](project/merge_requests/index.md), and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules. | +| `admin_merge_request` | GitLab 16.4 and later | Not applicable | View and approve [merge requests](project/merge_requests/index.md), revoke merge request approval, and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules. | | `manage_project_access_tokens` | GitLab 16.5 and later | Not applicable | Create, delete, and list [project access tokens](project/settings/project_access_tokens.md). | | `admin_group_member` | GitLab 16.5 and later | Not applicable | Add or remove [group members](group/manage.md). | -| `archive_project` | GitLab 16.6 and later | Not applicable | Archive and unarchive [projects](project/settings/index.md#archive-a-project). | +| `archive_project` | GitLab 16.6 and later | Not applicable | Archive and unarchive [projects](project/settings/migrate_projects.md#archive-a-project). | ## Billing and seat usage @@ -112,7 +128,50 @@ This does not apply when the user's custom role only has the `read_code` permiss enabled. Guest users with that specific permission only are not considered billable users and do not use a seat. -## Associate a custom role with an existing group member +## Add a user to your group with a custom role + +Prerequisites: + +- You must be an administrator, or have the Owner role in the group you are creating the custom role in. + +To add a user to your group with a custom role: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select **Invite members**. +1. In **Username or email address**, if the user: + - Has a GitLab account, enter their username. + - Does not have a GitLab account, enter their email address. +1. In **Select a role**, select a static or custom role. +1. Optional. In **Access expiration date (optional)**, enter or select a date. + From that date onward, the user can no longer access the group. +1. Select **Invite**. If you invite the user by their: + - GitLab username, the user is added to the member list. + - Email address, the user receives an email invitation and is prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. + +The new member with custom role and custom permissions appears on the [group's members list](group/index.md#view-group-members). + +NOTE: +Most custom roles are considered [billable users that use a seat](#billing-and-seat-usage). When you add a user to your group with a custom role, a warning is displayed if you are about to incur additional charges for having more seats than are included in your subscription. + +### Change a member's custom role + +To change a group member's custom role: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select the **Max role** dropdown list for the member you want to select a custom role for. +1. On the **Change role** dialog, select a different custom role. + +### Associate a custom role with an existing group member + +You can use the API to associate a custom role with an existing group member. + +Prerequisites: + +- You must have the Owner role for the group. To associate a custom role with an existing group member, a group member with the Owner role: @@ -143,9 +202,9 @@ the Owner role: ## Remove a custom role -Prerequisite: +Prerequisites: -- You must be an administrator or have the Owner role in the group you are removing the custom role from. +- You must be an administrator, or have the Owner role in the group you are removing the custom role from. You can remove a custom role from a group only if no group members have that role. @@ -153,7 +212,14 @@ To do this, you can either remove the custom role from all group members with th ### Remove a custom role from a group member -To remove a custom role from a group member, use the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) +To remove a custom role from a group member: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select the **Max role** dropdown list for the member you want to remove a custom role from. +1. On the **Change role** dialog, select a static role. + +You can update or remove a custom role from a group member also with the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project). and pass an empty `member_role_id` value: ```shell @@ -178,8 +244,7 @@ curl --request PUT --header "Content-Type: application/json" --header "Authoriza After you have made sure no group members have that custom role, delete the custom role. -1. On the left sidebar, select **Search or go to**. -1. GitLab.com only. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Roles and Permissions**. 1. Select **Custom Roles**. 1. In the **Actions** column, select **Delete role** (**{remove}**) and confirm. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index a3ed888ed53..034e2e45127 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Comments and threads **(FREE ALL)** @@ -78,13 +77,17 @@ Notifications and mentions can be disabled in When you mention a group in a comment, every member of the group gets a to-do item added to their To-do list. -1. Open the MR or issue. +1. On the left sidebar, select **Search or go to** and find your project. +1. For merge requests, select **Code > Merge requests**, and find your merge request. +1. For issues, select **Plan > Issues**, and find your issue. 1. In a comment, type `@` followed by the user, group, or subgroup namespace. For example, `@alex`, `@alex-team`, or `@alex-team/marketing`. 1. Select **Comment**. A to-do item is created for all the group and subgroup members. +For more information on mentioning subgroups see [Mention subgroups](../group/subgroups/index.md#mention-subgroups). + ## Add a comment to a merge request diff You can add comments to a merge request diff. These comments @@ -95,8 +98,9 @@ persist, even when you: To add a commit diff comment: -1. To select a specific commit, on the merge request, select the **Commits** tab, select the commit - message. To view the latest commit, select the **Changes** tab. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests**, and find your merge request. +1. Select the **Commits** tab, then select the commit message. 1. By the line you want to comment on, hover over the line number and select **Comment** (**{comment}**). You can select multiple lines by dragging the **Comment** (**{comment}**) icon. 1. Enter your comment and select **Start a review** or **Add comment now**. @@ -149,17 +153,19 @@ If you edit an existing comment to add a user mention that wasn't there before, You can prevent public comments in an issue or merge request. When you do, only project members can add and edit comments. -Prerequisite: +Prerequisites: - In merge requests, you must have at least the Developer role. - In issues, you must have at least the Reporter role. To lock an issue or merge request: -1. On the right sidebar, next to **Lock discussion**, select **Edit**. -1. On the confirmation dialog, select **Lock**. +1. On the left sidebar, select **Search or go to** and find your project. +1. For merge requests, select **Code > Merge requests**, and find your merge request. +1. For issues, select **Plan > Issues**, and find your issue. +1. On the top right, select **Merge request actions** or **Issue actions** (**{ellipsis_v}**), then select **Lock discussion**. -Notes are added to the page details. +A system note is added to the page details. If an issue or merge request is closed with a locked discussion, then you cannot reopen it until the discussion is unlocked. @@ -188,7 +194,7 @@ Prerequisites: To add an internal note: -1. Start adding a new comment. +1. On the issue or epic, in the **Comment** text box, type a comment. 1. Below the comment, select the **Make this an internal note** checkbox. 1. Select **Add internal note**. @@ -203,7 +209,7 @@ changes ([system notes](../project/system_notes.md)). System notes include chang objects, or changes to labels, assignees, and the milestone. GitLab saves your preference, and applies it to every issue, merge request, or epic you view. -1. Open the **Overview** tab in a merge request, issue, or epic. +1. On a merge request, issue, or epic, select the **Overview** tab. 1. On the right side of the page, from the **Sort or filter** dropdown list, select a filter: - **Show all activity**: Display all user comments and system notes. - **Show comments only**: Display only user comments. @@ -280,12 +286,7 @@ A threaded comment is created. > - Resolvable threads for issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. Disabled by default. > - Resolvable threads for issues [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.4. - -FLAG: -On self-managed GitLab, resolvable threads _for issues_ are available by default. -To hide the feature, an administrator can -[disable the feature flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. -On GitLab.com, this feature is available. +> - Resolvable threads for issues [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.7. Feature flag `resolvable_issue_threads` removed. You can resolve a thread when you want to finish a conversation. diff --git a/doc/user/emoji_reactions.md b/doc/user/emoji_reactions.md index 1b2c1bcd2e5..10385da7cdc 100644 --- a/doc/user/emoji_reactions.md +++ b/doc/user/emoji_reactions.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Emoji reactions **(FREE ALL)** @@ -48,8 +48,15 @@ To remove an emoji reaction, select the emoji again. > - [Introduced for GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../administration/feature_flags.md) named `custom_emoji`. Disabled by default. > - Enabled on GitLab.com in GitLab 14.0. > - UI to add emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333095) in GitLab 16.2. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138969) in GitLab 16.7. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `custom_emoji`. +On GitLab.com, this feature is available. +This feature is ready for production use. Custom emoji show in the emoji picker everywhere you can react with emoji. + To add an emoji reaction to a comment or description: 1. Select **Add reaction** (**{slight-smile}**). @@ -66,3 +73,23 @@ For more information, see [Use custom emoji with GraphQL](../api/graphql/custom_ For a list of custom emoji available for GitLab.com, see [the `custom_emoji` project](https://gitlab.com/custom_emoji/custom_emoji/-/tree/main/img). + +### Upload custom emoji to a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128355) in GitLab 16.5. + +Upload your custom emoji to a group to use them in all its subgroups and projects. + +Prerequisites: + +- You must at least have the developer role for the group. + +To upload custom emoji: + +1. On a description or a comment, select **Add reaction** (**{slight-smile}**). +1. At the bottom of the emoji picker, select **Create new emoji**. +1. Enter a name and URL for the custom emoji. +1. Select **Save**. + +You can also upload custom emoji to a GitLab instance with the GraphQL API. +For more information, see [Use custom emoji with GraphQL](../api/graphql/custom_emoji.md). diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index 2909c06046e..cc7e0e3b499 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -1,14 +1,13 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Enterprise users **(PREMIUM SAAS)** Enterprise users have user accounts that are administered by an organization that -has purchased a [GitLab subscription](../../subscriptions/index.md). +has [verified their email domain](../project/pages/custom_domains_ssl_tls_certification/index.md) and purchased a [GitLab subscription](../../subscriptions/index.md). Enterprise users are identified by the **Enterprise** badge next to their names on the [Members list](../group/index.md#filter-and-sort-members-in-a-group). @@ -55,11 +54,6 @@ Only GitLab administrators can change enterprise users' primary email address to Providing the ability to group Owners to change their enterprise users' primary email to an email with a non-verified domain is proposed in [issue 412966](https://gitlab.com/gitlab-org/gitlab/-/issues/412966). -## Dissociation of the user from their enterprise group - -Changing an enterprise user's primary email to an email with a non-verified domain automatically disassociates them from their enterprise group. -However, there are [primary email change restrictions](#primary-email-change). - ## Verified domains for groups The following automated processes use [verified domains](../project/pages/custom_domains_ssl_tls_certification/index.md) to run: @@ -193,14 +187,14 @@ To disable 2FA: 1. Find a user with the **Enterprise** and **2FA** badges. 1. Select **More actions** (**{ellipsis_v}**) and select **Disable two-factor authentication**. -### Prevent users from creating groups and projects outside the corporate group +### Prevent enterprise users from creating groups and projects outside the corporate group A SAML identity administrator can configure the SAML response to set: -- Whether users can create groups. -- The maximum number of personal projects users can create. +- Whether enterprise users can create groups. +- The maximum number of personal projects enterprise users can create. -For more information, see the [supported user attributes for SAML responses](../group/saml_sso/index.md#supported-user-attributes). +For more information, see how to [configure enterprise user settings from the SAML response](../group/saml_sso/index.md#configure-enterprise-user-settings-from-saml-response). ### Bypass email confirmation for provisioned users @@ -208,8 +202,15 @@ A top-level group Owner can [set up verified domains to bypass confirmation emai ### Get users' email addresses through the API -A top-level group Owner can use the [group and project members API](../../api/members.md) -to access users' information, including email addresses. +A top-level group Owner can use the [group and project members API](../../api/members.md) to access +users' information. For users provisioned by the group with [SCIM](../group/saml_sso/scim_setup.md), +this information includes users' email addresses. + +[Issue 391453](https://gitlab.com/gitlab-org/gitlab/-/issues/391453) proposes to change the criteria for access to email addresses from provisioned users to enterprise users. + +### Remove enterprise management features from an account + +Changing an enterprise user's primary email to any email with a non-verified domain automatically removes the enterprise badge from the account. This does not alter any account roles or permissions for the user, but does limit the group Owner's ability to manage this account. ## Troubleshooting diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index 88928ab6d47..83e2926e8e3 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "View a list of all the flags available in the GitLab application." layout: 'feature_flags' --- diff --git a/doc/user/free_push_limit.md b/doc/user/free_push_limit.md index c1be8287eb1..53088cd4445 100644 --- a/doc/user/free_push_limit.md +++ b/doc/user/free_push_limit.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Free push limit **(FREE SAAS)** @@ -39,7 +39,7 @@ Git LFS is designed to work with Git to track large files. ## Feedback -If you have any feedback to share about this limit, please do so in +If you have any feedback to share about this limit, do so in [issue 428188](https://gitlab.com/gitlab-org/gitlab/-/issues/428188). ## Related topics diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index c978105c13b..330f041b430 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Free user limit **(FREE SAAS)** @@ -15,24 +15,18 @@ namespaces cannot write new data to repositories, Git Large File Storage (LFS), packages, or registries. For the full list of restricted actions, see [Read-only namespaces](read_only_namespaces.md). -## Manage members in your namespace +In the Free tier of GitLab SaaS, user limits do not apply to users in: -To help manage your free user limit, -you can view and manage the total number of members across all projects and groups -in your namespace. - -Prerequisite: +- Public top-level groups +- Paid tiers +- Self-managed Free tier +- [Community programs](https://about.gitlab.com/community/): + - GitLab for Open Source + - GitLab for Education + - GitLab for Startups users -- You must have the Owner role for the group. - -1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > Usage Quotas**. -1. To view all members, select the **Seats** tab. -1. To remove a member, select **Remove user**. - -If you need more time to manage your members, or to try GitLab features -with a team of more than five members, you can [start a trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com&glm_content=free-user-limit). -A trial lasts for 30 days and includes an unlimited number of members. +NOTE: +Personal namespaces are public by default and are excluded from the user limit. ## Determining namespace user counts @@ -62,6 +56,78 @@ The group `example-2` has: The namespace `example-2` has six unique members: `A`, `B`, `C`, `D`, `E`, and `F`. Because `example-2` has six unique users, it is impacted by the five-user limit. -## Related topics +## Manage members in your group namespace + +To help manage your Free user limit, +you can view and manage the total number of members across all projects and groups +in your namespace. + +Prerequisite: + +- You must have the Owner role for the group. + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > Usage Quotas**. +1. To view all members, select the **Seats** tab. +1. To remove a member, select **Remove user**. + +If you need more time to manage your members, or to try GitLab features +with a team of more than five members, you can [start a trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com?&glm_content=free-user-limit-faq/ee/user/free_user_limit.html). +A trial lasts for 30 days and includes an unlimited number of members. + +## Include a group in an organization's subscription + +If there are multiple groups in your organization, they might have a +combination of Paid and Free subscriptions. When a group +with a Free subscription exceeds the user limit, their namespace becomes [read-only](../user/read_only_namespaces.md). + +To avoid user limits on groups with Free subscriptions, you can +include them in your organization's subscription. To check if a group is included in the subscription, +[view the group's subscription details](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription). +If the group is on the Free tier, it is not included in your organization's subscription. + +To include the group in your Paid subscription, [transfer the group](../user/group/manage.md#transfer-a-group) to your organization's +top-level namespace. + +NOTE: +If you previously purchased a subscription and the 5-user limit was applied to a group, +ensure that [your subscription is linked](../subscriptions/gitlab_com/index.md#change-the-linked-namespace) +to the correct top-level namespace, or that it has been +linked to your Customers Portal account. + +### Impact on seat count by transferred groups + +When you transfer a group, there might be an increase in your seat count, +which could incur additional costs for your subscription. + +For example, a company has Group A and Group B: + +- Group A is on a Paid tier and has five users. +- Group B is on the Free tier and has eight users, four of which are members of Group A. +- Group B is placed in a read-only state when it exceeds the user limit. +- Group B is transferred to the company's subscription to remove the read-only state. +- The company incurs an additional cost of four seats for the + four members of Group B that are not members of Group A. + +Users that are not part of the top-level namespace require additional seats to remain active. For more information, see [Add seats to your subscription](../subscriptions/gitlab_com/index.md#add-seats-to-your-subscription). + +## Increase the five-user limit + +On the Free tier on GitLab SaaS, you cannot increase the limit of five users on top-level groups with private visibility. + +For larger teams, you should upgrade to the Premium or Ultimate tier, which +has no user limits and offers more features to increase team productivity. To experience the +value of Paid features and unlimited users, you should start a [free trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com/ee/user/free_user_limit.html) for GitLab Ultimate. + +## Manage members in personal projects outside a group namespace + +Personal projects are not located in top-level group namespaces. You can manage the users in each of your +personal projects, but you cannot have more than five users in all of your personal projects. + +You should [move your personal project to a group](../tutorials/move_personal_project_to_group/index.md) so that +you can: -- [GitLab SaaS Free tier frequently asked questions](https://about.gitlab.com/pricing/faq-efficient-free-tier/) +- Increase the amount of users to more than five. +- Purchase a paid tier subscription, additional compute minutes, or storage. +- Use GitLab features in the group. +- Start a trial. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 6f809ae867a..70ac1f737e6 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab.com settings **(FREE SAAS)** @@ -191,7 +191,7 @@ the related documentation. ## 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) +for a package uploaded to the [GitLab package registry](../../user/packages/package_registry/index.md) varies by format: | Package type | GitLab.com | @@ -214,6 +214,7 @@ the default value [is the same as for self-managed instances](../../administrati |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------| | [Repository size including LFS](../../administration/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | | [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GiB | +| [Maximum export size](../project/settings/import_export.md#export-a-project-and-its-data) | 40 GiB | | [Maximum remote file size for imports from external object storages](../../administration/settings/import_and_export_settings.md#maximum-remote-file-size-for-imports) | 10 GiB | | [Maximum download file size when importing from source GitLab instances by direct transfer](../../administration/settings/import_and_export_settings.md#maximum-download-file-size-for-imports-by-direct-transfer) | 5 GiB | | Maximum attachment size | 100 MiB | @@ -390,7 +391,7 @@ user confirmation, user sign in, and password reset. [User and IP rate limits](../../administration/settings/user_and_ip_rate_limits.md#response-headers) includes a list of the headers responded to blocked requests. -See [Protected Paths](../admin_area/settings/protected_paths.md) for more details. +See [Protected Paths](../../administration/settings/protected_paths.md) for more details. ### IP blocks @@ -422,6 +423,11 @@ This limit: No response headers are provided. +`git` requests over `https` always send an unauthenticated request first, which for private repositories results in a `401` error. +`git` then attempts an authenticated request with a username, password, or access token (if available). +These requests might lead to a temporary IP block if too many requests are sent simultaneously. +To resolve this issue, use [SSH keys to communicate with GitLab](../ssh.md). + ### Pagination response headers For performance reasons, if a query returns more than 10,000 records, [GitLab excludes some headers](../../api/rest/index.md#pagination-response-headers). @@ -463,7 +469,7 @@ used on GitLab.com. Per-repository Gitaly RPC concurrency and queuing limits are configured for different types of Git operations such as `git clone`. When these limits are exceeded, a `fatal: remote error: GitLab is currently unable to handle this request due to load` message is returned to the client. -For administrator documentation, see [limit RPC concurrency](../../administration/gitaly/configure_gitaly.md#limit-rpc-concurrency). +For administrator documentation, see [limit RPC concurrency](../../administration/gitaly/concurrency_limiting.md#limit-rpc-concurrency). ## GitLab.com logging diff --git a/doc/user/gitlab_duo_chat.md b/doc/user/gitlab_duo_chat.md index ba6cd9b8f21..ebcb4c69e64 100644 --- a/doc/user/gitlab_duo_chat.md +++ b/doc/user/gitlab_duo_chat.md @@ -1,48 +1,70 @@ --- stage: AI-powered group: Duo Chat -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Answer questions with GitLab Duo Chat **(ULTIMATE SAAS EXPERIMENT)** +# Answer questions with GitLab Duo Chat **(ULTIMATE SAAS BETA)** -> Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +> Introduced in GitLab 16.6 as a [Beta](../policy/experiment-beta-support.md#beta). -You can get AI generated support from GitLab Duo Chat about the following topics: +You can get AI-generated support from GitLab Duo Chat about: - How to use GitLab. -- Questions about an issue. -- Question about an epic. -- Questions about a code file. -- Follow-up questions to answers from the chat. +- The contents of an issue or issue. +- The contents of a code or CI/CD configuration file. -Example questions you might ask: +You can also use GitLab Duo Chat to create code and CI/CD files. + +When you get an answer, you can ask follow-up questions to learn more. + +This is a Beta feature. We're continuously extending the capabilities and reliability of the responses. + +## Ask about GitLab + +You can ask questions about how GitLab works. Things like: - `Explain the concept of a 'fork' in a concise manner.` - `Provide step-by-step instructions on how to reset a user's password.` + +## Ask about your work + +You can ask about GitLab issues and epics. For example: + - `Generate a summary for the issue identified via this link: <link to your issue>` -- `Generate a concise summary of the description of the current issue.` +- `Generate a concise summary of the current issue.` -The examples above all use data from either the issue or the GitLab documentation. However, you can also ask to generate code, CI/CD configurations, or to explain code. For example: +## Ask about code + +You can also ask GitLab Duo Chat to generate code: - `Write a Ruby function that prints 'Hello, World!' when called.` - `Develop a JavaScript program that simulates a two-player Tic-Tac-Toe game. Provide both game logic and user interface, if applicable.` -- `Create a .gitlab-ci.yml configuration file for testing and building a Ruby on Rails application in a GitLab CI/CD pipeline.` + +And you can ask GitLab Duo Chat to explain code: + - `Provide a clear explanation of the given Ruby code: def sum(a, b) a + b end. Describe what this code does and how it works.` -In addition to the provided prompts, feel free to ask follow-up questions to delve deeper into the topic or task at hand. This helps you get more detailed and precise responses tailored to your specific needs, whether it's for further clarification, elaboration, or additional assistance. +## Ask about CI/CD -- A follow-up to the question `Write a Ruby function that prints 'Hello, World!' when called.` could be: - - `Could you also explain how I can call and execute this Ruby function in a typical Ruby environment, such as the command line?` +You can ask GitLab Duo Chat to create a CI/CD configuration: -This is an experimental feature and we're continuously extending the capabilities and reliability of the chat. +- `Create a .gitlab-ci.yml configuration file for testing and building a Ruby on Rails application in a GitLab CI/CD pipeline.` -## Enable GitLab Duo Chat +## Ask follow up questions + +You can ask follow-up questions to delve deeper into the topic or task at hand. +This helps you get more detailed and precise responses tailored to your specific needs, +whether it's for further clarification, elaboration, or additional assistance. -To use this feature, at least one group you're a member of must: +A follow-up to the question `Write a Ruby function that prints 'Hello, World!' when called` could be: -- Have the [experiment and beta features setting](group/manage.md#enable-experiment-and-beta-features) enabled. +- `Can you also explain how I can call and execute this Ruby function in a typical Ruby environment, such as the command line?` + +## Enable GitLab Duo Chat + +To use this feature, at least one group you're a member of must +have the [experiment and beta features setting](group/manage.md#enable-experiment-and-beta-features) enabled. ## Use GitLab Duo Chat @@ -56,12 +78,65 @@ To use this feature, at least one group you're a member of must: NOTE: Only the last 50 messages are retained in the chat history. The chat history expires 3 days after last use. -## Give Feedback +### Delete all conversations + +To delete all previous conversations: + +1. In the text box, type `/clean` and select **Send**. + +## Use GitLab Duo Chat in the Web IDE and VS Code **(ULTIMATE SAAS EXPERIMENT)** + +> Introduced in GitLab 16.6 as an [EXPERIMENT](../policy/experiment-beta-support.md#experiment). + +### Web IDE + +To use GitLab Duo Chat in the Web IDE on GitLab.com: + +1. Open the Web IDE: + 1. On the left sidebar, select **Search or go to** and find your project. + 1. Select a file. Then in the upper right, select **Edit > Open in Web IDE**. +1. Then open Chat by using one of the following methods: + - On the left sidebar, select **GitLab Duo Chat**. + - In the file that you have open in the editor, select some code. + 1. Right-click and select **GitLab Duo Chat**. + 1. Select **Explain selected code** or **Generate Tests**. + + - Use the keyboard shortcut: <kbd>ALT</kbd>+<kbd>d</kbd> (on Windows and Linux) or <kbd>Option</kbd>+<kbd>d</kbd> (on Mac) + +1. In the message box, enter your question and press **Enter** or select **Send**. + +If you have selected code in the editor, this selection is sent along with your question to the AI. This way you can ask questions about this code selection. For instance, `Could you simplify this?`. + +### GitLab Workflow extension for VS Code + +To use GitLab Duo Chat in VS Code: + +1. Install and set up the Workflow extension for VS Code: + 1. In VS Code, download and Install the [GitLab Workflow extension for VS Code](../editor_extensions/visual_studio_code/index.md#download-the-extension). + 1. Configure the [GitLab Workflow extension](../editor_extensions/visual_studio_code/index.md#configure-the-extension). +1. In VS Code, open a file. The file does not need to be a file in a Git repository. +1. Open Chat by using one of the following methods: + - On the left sidebar, select **GitLab Duo Chat**. + - In the file that you have open in the editor, select some code. + 1. Right-click and select **GitLab Duo Chat**. + 1. Select **Explain selected code** or **Generate Tests**. + - Use the keyboard shortcut: <kbd>ALT</kbd>+<kbd>d</kbd> (on Windows and Linux) or <kbd>Option</kbd>+<kbd>d</kbd> (on Mac) +1. In the message box, enter your question and press **Enter** or select **Send**. + +If you have selected code in the editor, this selection is sent along with your question to the AI. This way you can ask questions about this code selection. For instance, `Could you simplify this?`. + +### Disable Chat in Web IDE and VS Code + +To disable GitLab Duo Chat in the Web IDE and VS Code: + +1. Go to **Settings > Extensions > GitLab Workflow (GitLab VSCode Extension)**. +1. Clear the **Enable GitLab Duo Chat assistant** checkbox. + +## Give feedback Your feedback is important to us as we continually enhance your GitLab Duo Chat experience: - **Enhance Your Experience**: Leaving feedback helps us customize the Chat for your needs and improve its performance for everyone. -- **Privacy Assurance**: Rest assured, we don't collect your prompts. Your privacy is respected, and your interactions remain private. To give feedback about a specific response, use the feedback buttons in the response message. -Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/415591). +Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/430124). diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 53a62a60157..e08cfea7095 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group access and permissions @@ -303,7 +303,7 @@ To create group links via filter: LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Manage > Members**. If LDAP synchronization +1. Select **Manage > Members**. If LDAP synchronization has granted a user a role with: - More permissions than the parent group membership, that user is displayed as having [direct membership](../project/members/index.md#display-direct-members) of the group. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 5c0844dff92..ded99f7c936 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 7258791a983..4a03db33a86 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance frameworks **(PREMIUM ALL)** @@ -25,7 +25,7 @@ or deleted at the subgroup or project level. Project owners can choose a framewo ## Add a compliance framework to a project -Prerequisite: +Prerequisites: - The group to which the project belongs must have a compliance framework. @@ -336,7 +336,7 @@ cannot change them: non-modifiable and are always run. - Explicitly set any [variables](../../ci/yaml/index.md#variables) the job references. This: - Ensures that project-level pipeline configurations do not set them and alter their - behavior. + behavior. For example, see `before_script` and `after_script` configuration in the [example configuration](#example-configuration). - Includes any jobs that drive the logic of your job. - Explicitly set the [container image](../../ci/yaml/index.md#image) to run the job in. This ensures that your script steps execute in the correct environment. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 96cc9ce974c..6d8d209986c 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Contribution analytics **(PREMIUM ALL)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 967ba4e05d0..07158a0c06f 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom group-level project templates **(PREMIUM ALL)** @@ -21,7 +21,7 @@ You can also configure [custom templates for the instance](../../administration/ ## Set up group-level project templates -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -40,7 +40,7 @@ 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 authenticated user as a template for a new project, - if all [project features](../project/settings/index.md#configure-project-features-and-permissions) + if all [project features](../project/settings/project_features_permissions.md#configure-project-features-and-permissions) except for **GitLab Pages** and **Security and Compliance** are set to **Everyone With Access**. - Private projects can be selected only by users who are members of the projects. diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 5359d7b52a0..cdb11bb0548 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group DevOps Adoption **(ULTIMATE ALL)** @@ -30,7 +30,7 @@ how to use those features. ## View DevOps Adoption -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the group. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 69b64861bd5..0547f947419 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epic boards **(PREMIUM ALL)** @@ -17,10 +17,10 @@ labels. On the top of each list, you can see the number of epics in the list (**{epic}**) and the total weight of all its epics (**{weight}**). <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=I1bFIAQBHB8">Epics and Issue Boards - Project Management</a>. + See the video: <a href="https://www.youtube.com/watch?v=eQUnHwbKEkY">Epics and Issue Boards - Project Management</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/I1bFIAQBHB8" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/eQUnHwbKEkY" frameborder="0" allowfullscreen> </iframe> </figure> To view an epic board: diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 83d38dbc70b..c524490eb0b 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epics **(PREMIUM ALL)** @@ -20,10 +20,10 @@ Use epics: - To discuss and collaborate on feature ideas and scope at a high level. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=kdE-yb6Puuo">GitLab Epics - Setting up your Organization with GitLab</a>. + See the video: <a href="https://www.youtube.com/watch?v=c0EwYYUZppw">GitLab Epics - Setting up your Organization with GitLab</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/kdE-yb6Puuo" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/c0EwYYUZppw" frameborder="0" allowfullscreen> </iframe> </figure> ## Relationships between epics and issues diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 8b57c1b4d1f..fb63e851a69 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked epics **(ULTIMATE ALL)** diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index a5cc3ad9070..9cdebdd7d9d 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -1,8 +1,7 @@ --- -type: 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage epics **(PREMIUM ALL)** diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 24d5ca5b214..28878855098 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating GitLab groups **(FREE ALL)** @@ -76,7 +76,7 @@ Estimating the duration of migration by direct transfer is difficult. The follow very different amounts of time to migrate if one of the projects has a lot more attachments, comments, and other items on the merge requests. Therefore, the number of merge requests on a project is a poor predictor of how long a project will take to migrate. -There’s no exact formula to reliably estimate a migration. However, the average durations of each pipeline worker importing a project relation can help you to get an idea of how long importing your projects might take: +There's no exact formula to reliably estimate a migration. However, the average durations of each pipeline worker importing a project relation can help you to get an idea of how long importing your projects might take: | Project resource type | Average time (in seconds) to import a record | |:----------------------------|:---------------------------------------------| @@ -113,6 +113,8 @@ If you are migrating large projects and encounter problems with timeouts or dura ### Limits +> Eight hour time limit on migrations [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/429867) in GitLab 16.7. + Hardcoded limits apply on migration by direct transfer. | Limit | Description | @@ -121,7 +123,6 @@ Hardcoded limits apply on migration by direct transfer. | 210 seconds | Maximum number of seconds to wait for decompressing an archive file. | | 50 MB | Maximum length an NDJSON row can have. | | 5 minutes | Maximum number of seconds until an empty export status on source instance is raised. | -| 8 hours | Time until migration times out. | [Configurable limits](../../../administration/settings/account_and_limit_settings.md) are also available. @@ -173,9 +174,12 @@ To migrate groups by direct transfer: - For GitLab 15.0 and earlier source instances, the personal access token must have both the `api` and `read_repository` scopes. - You must have the Owner role on the source group to migrate from. -- Your must have a role on the destination namespace the enables you to +- You must have a role in the destination namespace that enables you to [create a subgroup](../../group/subgroups/index.md#create-a-subgroup) in that namespace. +- To import items stored in object storage, you must either: + - [Configure `proxy_download`](../../../administration/object_storage.md#configure-the-common-parameters). + - Ensure that the destination GitLab instance has access to the object storage of the source GitLab instance. ### Prepare user accounts @@ -201,7 +205,7 @@ Create the group you want to import to and connect the source GitLab instance: - A new subgroup. On existing group's page, either: - Select **New subgroup**. - On the left sidebar, at the top, select **Create new** (**{plus}**) and **New subgroup**. Then select the **import an existing group** link. -1. Enter the URL of a GitLab instance running GitLab 14.0 or later. +1. Enter the base URL of a GitLab instance running GitLab 14.0 or later. 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. @@ -226,6 +230,8 @@ ready for production use. ### Group import history +> **Partially completed** status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394727) in GitLab 16.7. + You can view all groups migrated by you by direct transfer listed on the group import history page. This list includes: - Paths of source groups. @@ -249,7 +255,7 @@ To view group import history: To review the results of an import: 1. Go to the [Group import history page](#group-import-history). -1. To see the details of a failed import, select the **See failures** link on any import with a **Failed** status. +1. To see the details of a failed import, select the **See failures** link on any import with a **Failed** or **Partially completed** status. ### Migrated group items @@ -433,7 +439,7 @@ Some project items are excluded from migration because they either: - Environments - Feature flags - Infrastructure Registry - - Package Registry + - Package registry - Pages domains - Remote mirrors @@ -613,15 +619,14 @@ sure these users exist before importing the desired groups. ### Enable export for a group -Prerequisite: +Prerequisites: - You must have the Owner role for the group. To enable import and export for a group: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. In the **Import sources** section, select the checkboxes for the sources you want. @@ -662,7 +667,7 @@ 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 Area](../../admin_area/settings/account_and_limit_settings.md). +[Admin Area](../../../administration/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to 0 in GitLab 13.8. ### Rate limits diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 1a4fa9df305..f4b4f9f2d39 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Groups **(FREE ALL)** @@ -32,7 +32,7 @@ A single top-level group provides insights in your entire organization via a com ## Group visibility -Like projects, a group can be configured to limit the visibility of it to: +Like projects, a group can be configured to be visible to: - Anonymous users. - All authenticated users. @@ -42,30 +42,30 @@ The restriction for [visibility levels](../../administration/settings/visibility on the application setting level also applies to groups. If set to internal, the explore page is empty for anonymous users. The group page has a visibility level icon. -Administrator users cannot create a subgroup or project with a higher visibility level than that of +Users cannot create a subgroup or project with a higher visibility level than that of the immediate parent group. ## View groups -To explore all public groups: +To explore all public groups you are a member of: 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. -1. At the top right, select **Explore groups**. +1. In the upper right, select **Explore groups**. -To view groups where you have a direct or indirect membership: +To view groups where you have direct or indirect membership: 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. -This page shows groups that you are a member of: +This page shows groups that you are a member of through: -- Through membership of a subgroup's parent group. -- Through direct or inherited membership of a project in the group or subgroup. +- Membership of a subgroup's parent group. +- Direct or inherited membership of a project in the group or subgroup. ## View group activity -To view the activity of a project: +To view the activity of a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Activity**. @@ -75,7 +75,6 @@ To view the activity of a project: - **Push events**: Push events in the group's projects. - **Merge events**: Accepted merge requests in the group's projects. - **Issue events**: Issues opened and closed in the group's projects. - - **Epic events**: Epics opened and closed in the group. - **Comments**: Comments posted by group members in the group's projects. - **Wiki**: Updates to wiki pages in the group. - **Designs**: Designs added, updated, and removed in the group's projects. @@ -87,19 +86,52 @@ To create a group: 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**. 1. Select **Create group**. -1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see +1. In the **Group name** text box, enter the name of the group. For a list of words that cannot be used as group names, see [reserved names](../reserved_names.md). -1. Enter a path for the group in **Group URL**, which is used for the [namespace](../namespace/index.md). -1. Choose the [visibility level](../public_access.md). -1. Personalize your GitLab experience by answering the following questions: - - What is your role? - - Who is using this group? - - What are you using this group for? -1. Invite GitLab members or other users to join the group. +1. In the **Group URL** text box, enter the path for the group used for the [namespace](../namespace/index.md). +1. Select the [**Visibility level**](../public_access.md) of the group. +1. Optional. To personalize your GitLab experience: + - From the **Role** dropdown list, select your role. + - For **Who will be using this group?**, select an option. + - From the **What will you use this group for?** dropdown list, select an option. +1. Optional. To invite members to the group, in the **Email 1** text box, enter the email address of the user you want to invite. To invite more users, select **Invite another member** and enter the user's email address. +1. Select **Create group**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For details about groups, watch [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A). +## Edit group name and description + +You can edit your group details from the group general settings. + +Prerequisites: + +- You must have the Owner role for the group. + +To edit group details: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. In the **Group name** text box, enter your group name. See the [limitations on group names](../../user/reserved_names.md). +1. Optional. In the **Group description (optional)** text box, enter your group description. + The description is limited to 500 characters. +1. Select **Save changes**. + +## Leave a group + +> The button to leave a group [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. + +When you leave a group: + +- You are no longer a member of the group, its subgroups, and projects, and cannot contribute. +- All the issues and merge requests that were assigned to you are unassigned. + +To leave a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. On the group overview page, in the upper-right corner, select **Actions** (**{ellipsis_v})**. +1. Select **Leave group**, then **Leave group** again. + ## Remove a group > Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. @@ -107,23 +139,19 @@ For details about groups, watch [GitLab Namespaces (users, groups and subgroups) To remove a group and its contents: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Remove group** section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. +1. On the confirmation dialog, type the group name and select **Confirm**. -A group can also be removed from the groups dashboard: +You can also remove a group from the groups dashboard: 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. 1. Select (**{ellipsis_v}**) for the group you want to delete. 1. Select **Delete**. -1. In the Remove group section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. - -This action removes the group. It also adds a background job to delete all projects in the group. +1. In the **Remove group** section, select **Remove group**. +1. On the confirmation dialog, type the group name and select **Confirm**. In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on GitLab [Premium](https://about.gitlab.com/pricing/premium/) and [Ultimate](https://about.gitlab.com/pricing/ultimate/), this action adds a background job to mark a group for deletion. By default, the job schedules the deletion seven days in the future. You can modify this retention period through the [instance settings](../../administration/settings/visibility_and_access_controls.md#deletion-protection). @@ -146,11 +174,10 @@ To immediately remove a group marked for deletion: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Advanced**. -1. In the "Permanently remove group" section, select **Remove group**. +1. In the **Permanently remove group** section, select **Remove group**. 1. Confirm the action when asked to. -Your group, its subgroups, projects, and all related resources, including issues and merge requests, -are deleted. +This action deletes the group, its subgroups, projects, and all related resources, including issues and merge requests. ## Restore a group **(PREMIUM ALL)** @@ -161,7 +188,7 @@ To restore a group that is marked for deletion: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Advanced** section. -1. In the Restore group section, select **Restore group**. +1. In the **Restore group** section, select **Restore group**. ## Request access to a group @@ -169,12 +196,12 @@ As a user, you can request to be a member of a group, if an administrator allows 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. -1. At the top right side, select **Explore groups**. -1. Search for the group by name. +1. In the upper right, select **Explore groups**. +1. In the **Search by name** text box, enter the name of the group you want to join. 1. In the search results, select the name of the group. 1. On the group page, under the group name, select **Request Access**. -As many as ten of the most-recently-active group owners receive an email with your request. +Up to ten of the most recently active group owners receive an email with your request. Any group owner can approve or decline the request. If you change your mind before your request is approved, select @@ -189,16 +216,16 @@ To view a group's members: A table displays the member's: -- **Account** name and username +- **Account** name and username. - **Source** of their [membership](../project/members/index.md#membership-types). For transparency, GitLab displays all membership sources of group members. Members who have multiple membership sources are displayed and counted as separate members. For example, if a member has been added to the group both directly and through inheritance, the member is displayed twice in the **Members** table, with different sources, and is counted as two individual members of the group. -- [**Max role**](../project/members/index.md#which-roles-you-can-assign) in the group -- **Expiration** date of their group membership -- **Activity** related to their account +- [**Max role**](../project/members/index.md#which-roles-you-can-assign) in the group. +- **Expiration** date of their group membership. +- **Activity** related to their account. NOTE: The display of group members' **Source** might be inconsistent. @@ -223,11 +250,11 @@ In lists of group members, entries can display the following badges: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. -1. Above the list of members, in the **Filter members** box, enter filter criteria. - - To view members in the group only, select **Membership = Direct**. - - To view members of the group and its subgroups, select **Membership = Inherited**. - - To view members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **Disabled**. - - To view members of the top-level group who are [enterprise users](../enterprise_user/index.md), select **Enterprise = true**. +1. Above the list of members, in the **Filter members** text box, enter your search criteria. To view: + - Direct members of the group, select **Membership = Direct**. + - Members of the group and its subgroups, select **Membership = Inherited**. + - Members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **2FA = Disabled**. + - Members of the top-level group who are [enterprise users](../enterprise_user/index.md), select **Enterprise = true**. ### Search a group @@ -255,27 +282,43 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last You can give a user access to all projects in a group. -Prerequisite: +Prerequisites: -- You must have the Owner role. +- You must have the Owner role for the group. 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Select **Invite members**. -1. Fill in the fields. - - The role applies to all projects in the group. For more information, see [permissions](../permissions.md). - - Optional. Select an **Access expiration date**. From that date onward, the - user can no longer access the project. +1. If the user: + + - Has a GitLab account, enter the user's username. + - Doesn't have a GitLab account, enter the user's email address. + +1. Select a [role](../permissions.md). +1. Optional. For **Access expiration date**, enter or select a date. + From that date onward, the user can no longer access the project. + + If you enter an access expiration date, the group member gets an email notification + seven days before their access expires. + + WARNING: + If you give a member the Maintainer role and enter an expiration date, that member + has full permissions as long as they are in the role. These permissions include the member's ability + to extend their own time in the Maintainer role. + 1. Select **Invite**. + If you invite the user by their: -If you selected an access expiration date, the group member gets an email notification -seven days before their access expires. + - GitLab username, the user is added to the member list. + - Email address, the user receives an email invitation and is prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. Members that are not automatically added are displayed on the **Invited** tab. -Users can be on this tab because they: +This tab includes users who: - Have not yet accepted the invitation. -- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). +- Are waiting for [approval from an administrator](../../administration/moderate_users.md). - [Exceed the group user cap](manage.md#user-cap-for-groups). ## Remove a member from the group @@ -293,21 +336,16 @@ To remove a member from a group: 1. Select **Manage > Members**. 1. Next to the member you want to remove, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Remove member**. -1. Optional. On the **Remove member** confirmation box: - - To remove direct user membership from subgroups and projects, select the **Also remove direct user membership from subgroups and projects** checkbox. - - To unassign the user from linked issues and merge requests, select the **Also unassign this user from linked issues and merge requests** checkbox. +1. Optional. On the **Remove member** confirmation dialog, select one or both checkboxes: + - **Also remove direct user membership from subgroups and projects** + - **Also unassign this user from linked issues and merge requests** 1. Select **Remove member**. -## Ensure removed users cannot invite themselves back - -Malicious users with the Maintainer or Owner role could exploit a race condition that allows -them to invite themselves back to a group or project that a GitLab administrator has removed them from. - -To avoid this problem, GitLab administrators can [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back). +GitLab administrators can also [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back). ## Add projects to a group -There are two different ways to add a new project to a group: +You can add a new project to a group in two ways: - Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md). - While you are creating a project, select a group from the dropdown list. @@ -316,13 +354,10 @@ There are two different ways to add a new project to a group: ### Specify who can add projects to a group -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. - -By default, users with: +By default, users with at least the: -- At least the Developer role can create projects under a group. This default can be changed. -- At least the Maintainer role can fork projects into a group. This default prevents users with the Developer role from forking projects that +- Developer role can create projects under a group. This default can be changed. +- Maintainer role can fork projects into a group. This default prevents users with the Developer role from forking projects that contain protected branches and cannot be changed. To change the role that can create projects under a group: @@ -330,7 +365,19 @@ To change the role that can create projects under a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. Select the desired option in the **Roles allowed to create projects** dropdown list. +1. From **Roles allowed to create projects**, select an option. 1. Select **Save changes**. To change this setting globally, see [Default project creation protection](../../administration/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). + +## Get the group ID + +> Group ID [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. + +You might need the group ID if you want to interact with it using the [GitLab API](../../api/index.md). + +To copy the group ID: + +1. On the left sidebar, select **Search or go to** and find your group. +1. On the group overview page, in the upper-right corner, select **Actions** (**{ellipsis_v})**. +1. Select **Copy group ID**. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 2ded1b08de2..6ca37cb9a2c 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Insights for groups **(ULTIMATE ALL)** @@ -56,6 +56,16 @@ By default, insights display all available dimensions on the chart. To exclude a dimension, from the legend below the chart, select the name of the dimension. +### Drill down on charts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372215/) in GitLab 16.7. + +You can drill down into the data of the **Bugs created per month by priority** and **Bugs created per month by severity** charts from the [default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). + +To view a drill-down report of the data for a specific priority or severity in a month: + +- On the chart, select the bar stack you want to drill down on. + ## Configure group insights GitLab reads insights from the diff --git a/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png b/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png Binary files differnew file mode 100644 index 00000000000..519e56acaa5 --- /dev/null +++ b/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png diff --git a/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png b/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png Binary files differdeleted file mode 100644 index 5e1fe4eaa8c..00000000000 --- a/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png +++ /dev/null diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 4f1c7b4be7a..28f4026b3e3 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue analytics for groups **(PREMIUM ALL)** @@ -16,7 +15,7 @@ prior. To access the chart: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Analyze > Issue analytics**. +1. Select **Analyze > Issue analytics**. You can also access the chart from the [Value Streams Dashboard](../../analytics/value_streams_dashboard.md) through the **New issues** drill-down report. @@ -50,7 +49,7 @@ available. This feature is not ready for production use. Enhanced issue analytics display the additional metric "Issues closed", which represents the total number of resolved issues in your group over a selected period. You can use this metric to improve the overall turn-around time and value delivered to your customers. - + ## Drill into the information diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 8c0838cf33c..bfbba8cc0da 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Iterations **(PREMIUM ALL)** @@ -78,7 +77,7 @@ From there you can create a new iteration or select an iteration to get a more d NOTE: If a project has issue tracking -[turned off](../../project/settings/index.md#configure-project-features-and-permissions), +[turned off](../../project/settings/project_features_permissions.md#configure-project-features-and-permissions), to view the iterations list, enter its URL. To do so, add: `/-/cadences` to your project or group URL. For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences`. This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). @@ -179,7 +178,7 @@ Prerequisites: To create an iteration: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Plan > Iterations** and select an iteration cadence. +1. Select **Plan > Iterations** and select an iteration cadence. 1. Select **New iteration**. 1. Enter the title, a description (optional), a start date, and a due date. 1. Select **Create iteration**. The iteration details page opens. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 48f86ee4f0e..877db58b716 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage groups @@ -23,7 +23,7 @@ A single top-level group provides insights in your entire organization via a com As a group owner or member, you can use a README to provide more information about your team, and invite users to contribute to your projects. The README is displayed on the group overview page, and can be changed in the group settings. All group members can edit the README. -Prerequisite: +Prerequisites: - To create the README from the group settings, you must have the Owner role for the group. @@ -53,20 +53,15 @@ member with the Owner role. ## Change a group's path -Changing a group's path (group URL) can have unintended side effects. Read -[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes) +Changing a group's path (group URL) can have unintended side effects. Read how redirects behave +[on the project-level](../project/repository/index.md#what-happens-when-a-repository-path-changes) +and [in the API](../../api/rest/index.md#redirects) before you proceed. If you are changing the path so it can be claimed by another group or user, you must rename the group too. Both names and paths must be unique. -After you change the group path, the new group path is a new namespace and you must update the existing project URL in the following resources: - -- [Include statements](../../ci/yaml/includes.md#include-a-single-configuration-file). -- Docker image references in CI files. -- Variables that specify a project or namespace. - To retain ownership of the original namespace and protect the URL redirects, create a new group and transfer projects to it instead. @@ -83,6 +78,11 @@ It is not possible to rename a namespace if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. +WARNING: +To ensure that groups with thousands of subgroups get processed correctly, you should test the path change in a test environment. +Consider increasing the [Puma worker timeout](../../administration/operations/puma.md#change-the-worker-timeout) temporarily. +For more information about our solution to mitigate this timeout risk, see [issue 432065](https://gitlab.com/gitlab-org/gitlab/-/issues/432065). + ## Change the default branch protection of a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. @@ -231,7 +231,7 @@ To disable group mentions: You can export a list of members in a group or subgroup as a CSV. 1. On the left sidebar, select **Search or go to** and find your group or subgroup. -1. On the left sidebar, **Manage > Members**. +1. Select **Manage > Members**. 1. Select **Export as CSV**. 1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -254,7 +254,7 @@ disabled for the group and its subgroups. ### Specify a user cap for a group -Prerequisite: +Prerequisites: - You must be assigned the Owner role for the group. @@ -276,7 +276,7 @@ Increasing the user cap does not approve pending members. You can remove the user cap, so there is no limit on the number of members you can add to a group. -Prerequisite: +Prerequisites: - You must be assigned the Owner role for the group. @@ -297,14 +297,14 @@ and must be approved. Pending members do not count as billable. Members count as billable only after they have been approved and are no longer in a pending state. -Prerequisite: +Prerequisites: -- You must be assigned the Owner role) for the group. +- You must be assigned the Owner role for the group. To approve members that are pending because they've exceeded the user cap: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select **Settings > Usage Quotas**. 1. On the **Seats** tab, under the alert, select **View pending approvals**. 1. For each member you want to approve, select **Approve**. @@ -322,7 +322,7 @@ User cap doesn’t consider whether users are billable or not (e.g., Free Guest Use group file templates to share a set of templates for common file types with every project in a group. It is analogous to the -[instance template repository](../admin_area/settings/instance_template_repository.md). +[instance template repository](../../administration/settings/instance_template_repository.md). The selected project should follow the same naming conventions as are documented on that page. @@ -390,7 +390,7 @@ You can configure [skipped pipelines](../../ci/pipelines/index.md#skip-a-pipelin See also [the project-level setting](../project/merge_requests/merge_when_pipeline_succeeds.md#allow-merge-after-skipped-pipelines). -Prerequisite: +Prerequisites: - You must be the owner of the group. @@ -409,7 +409,7 @@ To change this behavior: You can prevent merge requests from being merged until all threads are resolved. When this setting is enabled, for all child projects in your group, the **Unresolved threads** count in a merge request is shown in orange when at least one thread remains unresolved. -Prerequisite: +Prerequisites: - You must be the owner of the group. @@ -443,7 +443,7 @@ Approval settings should not be confused with [approval rules](../project/merge_ for the ability to set merge request approval rules for groups is tracked in [epic 4367](https://gitlab.com/groups/gitlab-org/-/epics/4367). -## Enable Code Suggestions **(FREE SAAS)** +## Enable Code Suggestions for a group **(FREE SAAS)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405126) in GitLab 15.11. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. @@ -454,12 +454,9 @@ This feature is in [Beta](../../policy/experiment-beta-support.md#beta). Beta users should read about the [known limitations](../project/repository/code_suggestions/index.md#known-limitations). We look forward to hearing your [feedback](../project/repository/code_suggestions/index.md#feedback). -You can give all users in a group and its subgroups access to [Code Suggestions](../project/repository/code_suggestions/index.md). - -- This setting - [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) in the group. -- Each user can - [enable Code Suggestions](../../user/profile/preferences.md#enable-code-suggestions). +You can give all users in a group and its subgroups access to +[Code Suggestions](../project/repository/code_suggestions/index.md). This setting +[cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) in the group. Code Suggestions are enabled by default at the group level. @@ -471,6 +468,9 @@ To update this setting: 1. Under **Code Suggestions**, select the **Projects in this group can use Code Suggestions** checkbox. 1. Select **Save changes**. +Individual users can disable Code Suggestions by disabling the feature in their +[installed IDE editor extension](../project/repository/code_suggestions/index.md#supported-editor-extensions). + ## Enable Experiment and Beta features **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118222) in GitLab 16.0. @@ -509,7 +509,7 @@ Changes to [group wikis](../project/wiki/group.md) do not appear in group activi You can view the most recent actions taken in a group, either in your browser or in an RSS feed: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Manage > Activity**. +1. Select **Manage > Activity**. To view the activity feed in Atom format, select the **RSS** (**{rss}**) icon. diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md index 6859125b323..38d83c6b5f7 100644 --- a/doc/user/group/moderate_users.md +++ b/doc/user/group/moderate_users.md @@ -1,16 +1,23 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Moderate users **(FREE ALL)** +# Moderate users **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. This is the group-level documentation. For self-managed instances, see the [administration documentation](../../administration/moderate_users.md). A group Owner can moderate user access by banning and unbanning users. +You should ban a user when you want to block them from the group. + +A banned user: + +- Cannot access the group or any of repositories. +- Cannot use [slash commands](../project/integrations/gitlab_slack_application.md#slash-commands). +- Does not occupy a [seat](../free_user_limit.md). ## Unban a user diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index 17552ceaf88..3cfcba066c7 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -1,8 +1,7 @@ --- -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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Planning hierarchies **(PREMIUM ALL)** diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index d32524b8f5f..e00602aeacd 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git abuse rate limit **(ULTIMATE ALL)** @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w FLAG: On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is available. -This is the group-level documentation. For self-managed instances, see the [administration documentation](../../admin_area/reporting/git_abuse_rate_limit.md). +This is the group-level documentation. For self-managed instances, see the [administration documentation](../../../administration/reporting/git_abuse_rate_limit.md). Git abuse rate limiting is a feature to automatically ban users who download, clone, pull, fetch, or fork more than a specified number of repositories of a group in a given time frame. Banned users cannot access the top-level group or any of its non-public subgroups via HTTP or SSH. The rate limit also applies to users who authenticate with [personal](../../../user/profile/personal_access_tokens.md) or [group access tokens](../../../user/group/settings/group_access_tokens.md), as well as [CI/CD job tokens](../../../ci/jobs/ci_job_token.md). Access to unrelated groups is unaffected. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 6f02b27a214..baeab5b0bbc 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repositories analytics for groups **(PREMIUM ALL)** diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 89d461127e7..6af2a234447 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Roadmap **(PREMIUM ALL)** diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index 86ad2ba32d1..46666abe366 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Example group SAML and SCIM configurations **(PREMIUM SAAS)** @@ -41,9 +40,6 @@ This section has screenshots for the elements of Azure Active Directory configur  -NOTE: -Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. - ### SCIM mapping Provisioning: diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 7b10da016b9..144d927f7e5 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML Group Sync **(PREMIUM ALL)** @@ -77,11 +76,26 @@ example configurations for [Azure AD](../../../user/group/saml_sso/example_saml_ ## Configure SAML Group Links -When SAML is enabled, users with the Maintainer or Owner role -see a new menu item in group **Settings > SAML Group Links**. You can configure one or more **SAML Group Links** to map -a SAML identity provider group name to a GitLab role. This can be done for a top-level group or any subgroup. +When SAML is enabled, users with the Maintainer or Owner role see a new menu +item in group **Settings > SAML Group Links**. -SAML Group Sync only manages a group if that group has one or more SAML group links. If a SAML group link is created then removed, the user remains in the group until they are removed from the group in the identity provider. +- You can configure one or more **SAML Group Links** to map a SAML identity + provider group name to a GitLab role. +- Members of the SAML identity provider group are added as members of the GitLab + group on their next SAML sign-in. +- Group membership is evaluated each time a user signs in using SAML. +- SAML Group Links can be configured for a top-level group or any subgroup. +- SAML Group Sync only manages a group if that group has one or more SAML group + links. If a SAML group link is created then removed, and there are: + - Other SAML group links configured, users that were in the removed group + link are automatically removed from the group during sync. + - No other SAML group links configured, users remain in the group during sync. + Those users must be manually removed from the group. + +Prerequisites: + +- Self-managed GitLab instances must have configured SAML Group Sync. GitLab.com + instances are already configured for SAML Group Sync, and require no extra configuration. To link the SAML groups: @@ -104,8 +118,6 @@ Users granted: - A lower or the same role with Group Sync are displayed as having [inherited membership](../../project/members/index.md#display-inherited-members) of the group. -SAML group membership is evaluated each time a user signs in. - ### Use the API > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. @@ -171,8 +183,7 @@ To configure for a GitLab.com group: To configure for self-managed: 1. Configure [SAML SSO for the instance](../../../integration/saml.md). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. 1. Enter the **Tenant ID**, **Client ID**, and **Client secret** obtained earlier when configuring Azure Active Directory in the Azure Portal. @@ -202,11 +213,10 @@ When global group memberships lock is enabled: To enable global group memberships lock: 1. [Configure SAML](../../../integration/saml.md) for your self-managed GitLab instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. -1. Ensure the **Lock memberships to SAML synchronization** checkbox is selected. +1. Ensure that **Lock memberships to SAML Group Links synchronization** is selected. ## Automatic member removal diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 70af800b180..6f1ab305782 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML SSO for GitLab.com groups **(PREMIUM SAAS)** @@ -179,6 +179,9 @@ To set up OneLogin as your identity provider: ### Configure assertions +NOTE: +The attributes are case-sensitive. + At minimum, you must configure the following assertions: 1. [NameID](#manage-user-saml-identity). @@ -192,9 +195,6 @@ Optionally, you can pass user information to GitLab as attributes in the SAML as For more information, see the [attributes available for self-managed GitLab instances](../../../integration/saml.md#configure-assertions). -NOTE: -Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. For more information on configuring required attribute names in the SAML identity provider's settings, see [example group SAML and SCIM configurations](../../../user/group/saml_sso/example_saml_config.md). - ### Use metadata To configure some identity providers, you need a GitLab metadata URL. @@ -236,6 +236,8 @@ If the **NameID** is configured with the email address, [change the **NameID** f ## Configure GitLab +> Ability to set a custom role as the default membership role [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417285) in GitLab 16.7. + After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. On the left sidebar, select **Search or go to** and find your group. @@ -244,9 +246,12 @@ After you set up your identity provider to work with GitLab, you must configure - In the **Identity provider single sign-on URL** field, enter the SSO URL from your identity provider. - In the **Certificate fingerprint** field, enter the fingerprint for the SAML token signing certificate. 1. In the **Default membership role** field, select the role to assign to new users. - The default role is **Guest**. In [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523) - and later, group owners can set a default membership role other than **Guest**. - That role becomes the starting role of all users added to the group. + The default role is **Guest**. That role becomes the starting role of all users + added to the group: + - In [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523) and + later, group Owners can set a default membership role other than **Guest**. + - In GitLab 16.7 and later, group Owners can set a [custom role](../../custom_roles.md) + as the default membership role. 1. Select the **Enable SAML authentication for this group** checkbox. 1. Optional. Select: - **Enforce SSO-only authentication for web activity for this group**. @@ -349,25 +354,22 @@ breaks the configuration and could lock users out of the GitLab group. For more information on the recommended value and format for specific identity providers, see [set up your identity provider](#set-up-your-identity-provider). -### Configure user settings from SAML response +### Configure enterprise user settings from SAML response -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/412898) to configure only enterprise user settings in GitLab 16.7. GitLab allows setting certain user attributes based on values from the SAML response. An existing user's attributes are updated from the SAML response values if that -user was originally provisioned by the group. Users are provisioned by the group -when the account was created either: - -- Through [SCIM](scim_setup.md). -- By first sign-in with SAML SSO for GitLab.com groups. +user is an [enterprise user](../../enterprise_user/index.md) of the group. #### Supported user attributes -- **can_create_group** - `true` or `false` to indicate whether the user can create +- **can_create_group** - `true` or `false` to indicate whether an enterprise user can create new top-level groups. Default is `true`. -- **projects_limit** - The total number of personal projects a user can create. +- **projects_limit** - The total number of personal projects an enterprise user can create. A value of `0` means the user cannot create new projects in their personal - namespace. Default is `10000`. + namespace. Default is `100000`. #### Example SAML response diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index e29b33469ab..3c5c53cbdf6 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure SCIM for GitLab.com groups **(PREMIUM SAAS)** @@ -19,6 +19,8 @@ When SCIM is enabled for a GitLab group, membership of that group is synchronize The [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). Identity providers can use the [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) to develop a SCIM app. +To set up SCIM on GitLab self-managed, see [Configure SCIM for self-managed GitLab instances](../../../administration/settings/scim_setup.md). + ## Configure GitLab Prerequisites: diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index 527d710058a..a2576f37ac9 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting SAML **(FREE ALL)** @@ -222,7 +221,7 @@ to [reset their password](https://gitlab.com/users/password/new) if both: Users might get an error that states "SAML Name ID and email address do not match your user account. Contact an administrator." This means: -- The NameID value sent by SAML does not match the existing SAML identity `extern_uid` value. Both the NameID and the `extern_uid` are case sensitive. For more information, see [manage user SAML identity](index.md#manage-user-saml-identity). +- The NameID value sent by SAML does not match the existing SAML identity `extern_uid` value. Both the NameID and the `extern_uid` are case sensitive. For more information, see [manage user SAML identity](index.md#manage-user-saml-identity). - Either the SAML response did not include an email address or the email address did not match the user's GitLab email address. The workaround is that a GitLab group Owner uses the [SAML API](../../../api/saml.md) to update the user's SAML `extern_uid`. @@ -290,7 +289,7 @@ If a subset of users are receiving a `404` after signing in to the IdP, first ve Example request: ```plaintext - curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }' + curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --header "Content-Type: application/scim+json" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }' ``` ### 500 error after login **(FREE SELF)** @@ -323,8 +322,7 @@ This message might indicate that you must add or remove a domain from your domai To implement this workaround: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings** > **General**. 1. Expand **Sign-up restrictions**. 1. Add or remove a domain as appropriate to **Allowed domains for sign-ups** and **Denied domains for sign-ups**. @@ -359,18 +357,21 @@ Additionally, see [troubleshooting users receiving a 404 after sign in](#users-r ## Message: The SAML response did not contain an email address. Either the SAML identity provider is not configured to send the attribute, or the identity provider directory does not have an email address value for your user -This error appears when the SAML response does not contain the user's email address in an **email** or **mail** attribute as shown in the following example: +This error appears when the SAML response does not contain the user's email address in an **email** or **mail** attribute. +Ensure the SAML identity provider is configured to send a [supported mail attribute](../../../integration/saml.md). + +Examples: ```xml <Attribute Name="email"> - <AttributeValue>user@domain.com‹/AttributeValue> + <AttributeValue>user@example.com‹/AttributeValue> </Attribute> ``` -Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` like in the following example are not supported. Remove this type of attribute name from the SAML response on the IDP side. +Attribute names starting with phrases such as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims` and `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are supported by default beginning in GitLab 16.7. ```xml -<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/email"> - <AttributeValue>user@domain.com‹/AttributeValue> +<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress"> + <AttributeValue>user@example.com‹/AttributeValue> </Attribute> ``` diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index b31c2eed9df..3dcb2d93096 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting SCIM **(FREE ALL)** @@ -18,20 +18,17 @@ When the user is added back to the SCIM app, GitLab does not create a new user b From August 11, 2023, the `skip_saml_identity_destroy_during_scim_deprovision` feature flag is enabled. For a user de-provisioned by SCIM from that date, their SAML identity is not removed. - When that user is added back to the SCIM app: - Their SCIM identity `active` attribute is set to `true`. - They can sign in using SSO. For users de-provisioned by SCIM before that date, their SAML identity is destroyed. +To solve this problem, the user must [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account). -To solve this problem: - -1. Have the user sign in directly to GitLab. -1. [Manually link](scim_setup.md#link-scim-and-saml-identities) their account. +### Self-managed GitLab -Alternatively, self-managed administrators can [add a user identity](../../../administration/admin_area.md#user-identities). +For a self-managed GitLab instance, administrators of that instance can instead [add the user identity themselves](../../../administration/admin_area.md#user-identities). This might save time if administrators need to re-add multiple identities. ## User cannot sign in @@ -130,6 +127,47 @@ For example, use these values as a definitive source on why an account was provi details. This information can help where an account was SCIM provisioned with details that do not match the SCIM app configuration. +## Member's email address is not linked error in SCIM log + +When you attempt to provision a SCIM user on GitLab.com, GitLab checks to see if +a user with that email address already exists. You might see the following error +when the: + +- User exists, but does not have a SAML identity linked. +- User exists, has a SAML identity, **and** has a SCIM identity that is set to `active: false`. + +```plaintext +The member's email address is not linked to a SAML account or has an inactive +SCIM identity. +``` + +This error message is returned with the status `412`. + +This might prevent the affected end user from accessing their account correctly. + +The first workaround is: + +1. Have the end user [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account). +1. After the user has done this, initiate a SCIM sync from your identity provider. +If the SCIM sync completes without the same error, GitLab has +successfully linked the SCIM identity to the existing user account, and the user +should now be able to sign in using SAML SSO. + +If the error persists, the user most likely already exists, has both a SAML and +SCIM identity, and a SCIM identity that is set to `active: false`. To resolve +this: + +1. Optional. If you did not save your SCIM token when you first configured SCIM, [generate a new token](scim_setup.md#configure-gitlab). If you generate a new SCIM token, you **must** update the token in your identity provider's SCIM configuration, or SCIM will stop working. +1. Locate your SCIM token. +1. Use the API to [get a single SCIM provisioned user](/ee/development/internal_api/index.md#get-a-single-scim-provisioned-user). +1. Check the returned information to make sure that: + - The user's identifier (`id`) and email match what your identity provider is sending. + - `active` is set to `false`. + If any of this information does not match, [contact GitLab Support](https://support.gitlab.com/). +1. Use the API to [update the SCIM provisioned user's `active` value to `true`](/ee/development/internal_api/index.md#update-a-single-scim-provisioned-user). +1. If the update returns a status code `204`, have the user attempt to sign in +using SAML SSO. + ## Azure Active Directory The following troubleshooting information is specifically for SCIM provisioned through Azure Active Directory. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index cd3efcc6562..5b3f962061e 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Group access tokens **(FREE)** @@ -59,6 +58,7 @@ To create a group access token: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Access Tokens**. +1. Select **Add new token**. 1. Enter a name. The token name is visible to any user with permissions to view the group. 1. Enter an expiry date for the token: - The token expires on that date at midnight UTC. @@ -121,7 +121,7 @@ To revoke a group access token: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Access Tokens**. -1. Next to the group access token to revoke, select **Revoke**. +1. Next to the group access token to revoke, select **Revoke** (**{remove}**). ## Revoke a group access token using Rails console @@ -143,17 +143,17 @@ token.revoke! The scope determines the actions you can perform when you authenticate with a group access token. -| Scope | Description | -|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `api` | Grants complete read and write access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_api` | Grants read access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_registry` | Grants read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. | -| `write_registry` | Grants write access (push) to the [Container Registry](../../packages/container_registry/index.md). | -| `read_repository` | Grants read access (pull) to all repositories within a group. | -| `write_repository` | Grants read and write access (pull and push) to all repositories within a group. | -| `create_runner` | Grants permission to create runners in a group. | -| `ai_features` | Grants permission to perform API actions for GitLab Duo. | -| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in a group. | +| Scope | Description | +|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped group and related project API, including the [container registry](../../packages/container_registry/index.md), the [dependency proxy](../../packages/dependency_proxy/index.md), and the [package registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped group and related project API, including the [package registry](../../packages/package_registry/index.md). | +| `read_registry` | Grants read access (pull) to the [container registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. | +| `write_registry` | Grants write access (push) to the [container registry](../../packages/container_registry/index.md). | +| `read_repository` | Grants read access (pull) to all repositories within a group. | +| `write_repository` | Grants read and write access (pull and push) to all repositories within a group. | +| `create_runner` | Grants permission to create runners in a group. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in a group. | ## Enable or disable group access token creation @@ -163,6 +163,7 @@ To enable or disable group access token creation for all subgroups in a top-leve 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Users can create project access tokens and group access tokens in this group**. +1. Select **Save changes**. Even when creation is disabled, you can still use and revoke existing group access tokens. diff --git a/doc/user/group/ssh_certificates.md b/doc/user/group/ssh_certificates.md new file mode 100644 index 00000000000..25c5f4b1be8 --- /dev/null +++ b/doc/user/group/ssh_certificates.md @@ -0,0 +1,83 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Manage group's SSH certificates **(PREMIUM SAAS)** + +Manage Git access to the projects by sharing public Certified Authority (`CA`) files in your organization's top-level group. + +Git access control options on GitLab SaaS (SSH, HTTPS) rely on credentials (such as access tokens and SSH keys) +setup in the user profile and are out of control of the organization. +To temporarily grant Git access to your projects, you can use SSH certificates. + +## Add a CA certificate to a top-level group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.4 [with a flag](../feature_flags.md) named `ssh_certificates_rest_endpoints`. Disabled by default. + +FLAG: +On GitLab.com, this feature is not available. +Prerequisites: + +- You must have the Owner role for the group. +- The group must be a top-level group, not a subgroup. + +To add a CA certificate to a group: + +1. Generate an SSH key pair to be used as a Certified Authority file: + + ```plaintext + ssh-keygen -f CA + ``` + +1. Add the public key to the top-level group using [Group SSH certificates API](../../api/group_ssh_certificates.md#create-ssh-certificate) + to grant access to the projects of the group and its subgroups. + +## Issue CA certificates for users + +Prerequisites: + +- You must have the Owner role for the group. +- The user certificates can only be used to access the projects within the top-level group and its subgroups. +- A user's username or primary email (`user` or `user@example.com`) must be specified to associate a + GitLab user with the user certificate. +- The user must be an [Enterprise User](../enterprise_user/index.md). + +To issue user certificates, use the private key from the pair you [created earlier](#add-a-ca-certificate-to-a-top-level-group): + +```shell +ssh-keygen -s CA -I user@example.com -V +1d user-key.pub +``` + +The (`user-key.pub`) key is the public key from an SSH key pair that is used by a user for SSH authentication. +The SSH key pair is either generated by a user or provisioned by the group owner infrastructure along with the SSH certificate. + +The expiration date (`+1d`) identifies how long the SSH certificate can be used to access the group projects. + +The user certificates can only be used to access the projects within the top-level group. + +## Enforce SSH certificates + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.7 [with a flag](../feature_flags.md) named `enforce_ssh_certificates_via_settings`. Disabled by default. + +FLAG: +On GitLab.com, this feature is not available. + +You can enforce usage of SSH certificates and forbid users from authenticating using SSH +keys and access tokens. + +When SSH certificates are enforced, only individual user accounts are affected. +It does not apply to service accounts, deploy keys, and other types of internal accounts. + +Prerequisites: + +- You must have the Owner role for the group. + +To enforce using SSH certificates: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Select the **Enforce SSH Certificates** checkbox. +1. Select **Save changes**. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index e9064ff72a6..a63d4a98fa2 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Subgroups **(FREE ALL)** @@ -49,7 +49,7 @@ graph TD ## View subgroups of a group -Prerequisite: +Prerequisites: - To view private nested subgroups, you must be a direct or inherited member of the private subgroup. @@ -58,23 +58,25 @@ To view the subgroups of a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select the **Subgroups and projects** tab. -1. To view a nested subgroup, expand a subgroup in the hierarchy list. +1. Select the subgroup you want to view. + To view nested subgroups, expand (**{chevron-down}**) a subgroup. ### Private subgroups in public parent groups -In the hierarchy list, public groups with a private subgroup have an expand option (**{chevron-down}**) -for all users that indicate there is a subgroup. When users who are not direct or inherited members of -the private subgroup select expand (**{chevron-down}**), the nested subgroup does not display. +In the hierarchy list, public groups with private subgroups have an expand option (**{chevron-down}**), +which indicates the group has nested subgroups. The expand option (**{chevron-down}**) is visible +to all users, but the private group is displayed only to users who are direct or inherited members +of the private subgroup. -If you prefer to keep information about the presence of nested subgroups private, we advise that you -add private subgroups only to private parent groups. +If you prefer to keep information about the presence of nested subgroups private, +you should add private subgroups only to private parent groups. ## Create a subgroup Prerequisites: - You must have either: - - At least the Maintainer role for a group to create subgroups for it. + - At least the Maintainer role for a group. - The [role determined by a setting](#change-who-can-create-subgroups). These users can create subgroups even if group creation is [disabled by an Administrator](../../../administration/admin_area.md#prevent-a-user-from-creating-top-level-groups) in the user's settings. @@ -84,15 +86,14 @@ You cannot host a GitLab Pages subgroup website with a top-level domain name. Fo To create a subgroup: -1. On the left sidebar, select **Search or go to** and find a parent group for the subgroup. +1. On the left sidebar, select **Search or go to** and find the group you want to create the subgroup in. 1. On the parent group's overview page, in the upper-right corner, select **New subgroup**. -1. Select **Create group**. 1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. -1. Select **Create group**. +1. Select **Create subgroup**. ### Change who can create subgroups -Prerequisite: +Prerequisites: - You must have at least the Maintainer role on the group, depending on the group's setting. @@ -102,25 +103,21 @@ To change who can create subgroups on a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. - 1. Select a role from **Roles allowed to create subgroups**. + 1. From **Roles allowed to create subgroups**, select an option. 1. Select **Save changes**. - As an administrator: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Overview > Groups**. - 1. In the group's row select **Edit**. - 1. Select a role from **Allowed to create subgroups**. + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Overview > Groups** and find your group. + 1. In the group's row, select **Edit**. + 1. From the **Allowed to create subgroups** dropdown list, select an option. 1. Select **Save changes**. For more information, view the [permissions table](../../permissions.md#group-members-permissions). ## Subgroup membership -NOTE: -There is a bug that causes some pages in the parent group to be accessible by subgroup members. For more details, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340421). - -When you add a member to a group, that member is also added to all subgroups. The user's permissions are inherited from -the group's parent. +When you add a member to a group, that member is also added to all subgroups of that group. +The member's permissions are inherited from the group's parent. Subgroup members can be: @@ -163,6 +160,7 @@ To see if a member has inherited the permissions from a parent group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. + The member's inheritance is displayed in the **Source** column. Members list for an example subgroup _Four_: @@ -189,22 +187,23 @@ Members can be [filtered by inherited or direct membership](../index.md#filter-a ### Override ancestor group membership -Users with the Owner role on a subgroup can add members to it. +Users with the Owner role in a subgroup can add members to it. -You can't give a user a role on a subgroup that's lower than the roles they have on ancestor groups. To override a user's -role on an ancestor group, add the user to the subgroup again with a higher role. For example: +You can't give a user a role in a subgroup that is lower than the roles the user has in ancestor groups. +To override a user's role in an ancestor group, add the user to the subgroup again with a higher role. +For example: -- If User 1 is added to group _Two_ with the Developer role, they inherit that role in every subgroup of group _Two_. -- To give User 1 the Maintainer role on group _Four_ (under _One / Two / Three_), add them again to group _Four_ with +- If User 1 is added to group _Two_ with the Developer role, User 1 inherits that role in every subgroup of group _Two_. +- To give User 1 the Maintainer role in group _Four_ (under _One / Two / Three_), add User 1 again to group _Four_ with the Maintainer role. -- If User 1 is removed from group _Four_, their role falls back to their role on group _Two_. They have the Developer - role on group _Four_ again. +- If User 1 is removed from group _Four_, the user's role falls back to their role in group _Two_. User 1 has the Developer + role in group _Four_ again. ## Mention subgroups Mentioning subgroups ([`@<subgroup_name>`](../../discussions/index.md#mentions)) in issues, commits, and merge requests -notifies all direct members of that group. Inherited members of a subgroup are not notified by mentions. Mentioning works the same as for projects and groups, and you can choose the group -of people to be notified. +notifies all direct members of that group. Inherited members of a subgroup are not notified by mentions. +Mentioning works the same as for projects and groups, and you can choose the group of members to be notified. <!-- ## Troubleshooting diff --git a/doc/user/group/troubleshooting.md b/doc/user/group/troubleshooting.md index 08343f604f1..d7086e9271e 100644 --- a/doc/user/group/troubleshooting.md +++ b/doc/user/group/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting groups diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 2ed01a0ec05..0fdd572ed7c 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Value stream analytics **(FREE ALL)** @@ -208,9 +207,10 @@ You can change the name of a project environment in your GitLab CI/CD configurat > - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 > - Horizontal stage path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in 13.0 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in 13.12 > - Predefined date ranges dropdown list [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408656/) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. Disabled by default. +> - Predefined date ranges dropdown list [enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/433149) in GitLab 16.7. FLAG: -On self-managed GitLab, by default the predefined date ranges dropdown list feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. On GitLab.com, this feature is not available. The feature is not ready for production use. +On self-managed GitLab, by default the predefined date ranges dropdown list feature is available. To hide the feature per user, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. On GitLab.com, this feature is available. Prerequisites: @@ -302,7 +302,7 @@ In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on ## View lifecycle and DORA metrics -Prerequisite: +Prerequisites: - To view deployment metrics, you must have a [production environment configured](#how-value-stream-analytics-identifies-the-production-environment). diff --git a/doc/user/img/enable_AI_ML_features.png b/doc/user/img/enable_AI_ML_features.png Binary files differdeleted file mode 100644 index 97d06c877e4..00000000000 --- a/doc/user/img/enable_AI_ML_features.png +++ /dev/null diff --git a/doc/user/img/objective_two_column_view_v16_2.png b/doc/user/img/objective_two_column_view_v16_2.png Binary files differdeleted file mode 100644 index d3f4f733e7e..00000000000 --- a/doc/user/img/objective_two_column_view_v16_2.png +++ /dev/null diff --git a/doc/user/img/objective_two_column_view_v16_7.png b/doc/user/img/objective_two_column_view_v16_7.png Binary files differnew file mode 100644 index 00000000000..70001108203 --- /dev/null +++ b/doc/user/img/objective_two_column_view_v16_7.png diff --git a/doc/user/img/snippet_sample_v16_6.png b/doc/user/img/snippet_sample_v16_6.png Binary files differindex 035947a2b82..d2dd08be88d 100644 --- a/doc/user/img/snippet_sample_v16_6.png +++ b/doc/user/img/snippet_sample_v16_6.png diff --git a/doc/user/img/task_two_column_view_v16_2.png b/doc/user/img/task_two_column_view_v16_2.png Binary files differdeleted file mode 100644 index 8ca87f55f8a..00000000000 --- a/doc/user/img/task_two_column_view_v16_2.png +++ /dev/null diff --git a/doc/user/img/task_two_column_view_v16_7.png b/doc/user/img/task_two_column_view_v16_7.png Binary files differnew file mode 100644 index 00000000000..b3cd205c60e --- /dev/null +++ b/doc/user/img/task_two_column_view_v16_7.png diff --git a/doc/user/index.md b/doc/user/index.md index 490a946a077..80f480d9e26 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitLab **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 961914aac9c..4a8ec3d85f7 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect a cluster to GitLab **(FREE ALL)** @@ -44,9 +44,8 @@ your cluster's level. **Instance-level clusters:** -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Kubernetes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Kubernetes**. ## Security implications for clusters connected with certificates diff --git a/doc/user/infrastructure/clusters/connect/new_aks_cluster.md b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md index 24933875d48..0c5f67069d5 100644 --- a/doc/user/infrastructure/clusters/connect/new_aks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an Azure AKS cluster @@ -63,9 +63,9 @@ Use CI/CD environment variables to configure your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Variables**. -1. Set the variable `AZURE_CLIENT_ID` to your Azure client ID. -1. Set the variable `AZURE_CLIENT_SECRET` to your Azure client secret. -1. Set the variable `AZURE_TENANT_ID` to your service principal. +1. Set the variable `ARM_CLIENT_ID` to your Azure client ID. +1. Set the variable `ARM_CLIENT_SECRET` to your Azure client secret. +1. Set the variable `ARM_TENANT_ID` to your service principal. 1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task. 1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index de35b21c8b6..37310040f28 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Civo Kubernetes cluster diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 4ec28a7c3c6..c0499339812 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an Amazon EKS cluster diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 5412ced3e6d..3b20125ff03 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Google GKE cluster @@ -64,7 +64,7 @@ To create a GitLab agent for Kubernetes: 1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. Select **Connect a cluster (agent)**. -1. From the **Select an agent** dropdown list, select `gke-agent` and select **Register an agent**. +1. From the **Select an agent or enter a name to create new** dropdown list, choose your agent's name and select **Register**. 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. 1. GitLab provides an address for the agent server (KAS), which you will also need later. diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index cd81f6a1f86..bd074d42efb 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tracking cluster resources managed by GitLab (deprecated) **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index cace9c66fcf..79f350b1084 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kubernetes clusters **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index 2408e16160b..22a77ac0b5a 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install cert-manager with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md index ee9b2f848fe..c6bad5a9cb4 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install Ingress with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index cbc23402915..cd8a261544b 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install GitLab Runner with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index ac61c0c11b4..c58db7cd9b4 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install Vault with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 1e1372bb035..530376c1923 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate to the GitLab agent for Kubernetes **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md index 2161c2ba191..e86f2c71d3b 100644 --- a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md +++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Terraform helpers **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 65ec84652ef..d76f5dd736a 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure as Code with Terraform and GitLab **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 8fe639bb453..beef4c4d2aa 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform integration in merge requests **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 876300a7794..e8b8d840453 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab-managed Terraform state **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index 404e48d61bf..3036a297b0e 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform template recipes **(FREE ALL)** @@ -177,7 +177,7 @@ To define a custom container image: ``` 1. In a new job, define a `prepare` stage that builds the image whenever the `Dockerfile` changes. - - The built image is pushed to the [GitLab Container Registry](../../packages/container_registry). A tag is applied to indicate whether the image was built from a merge request or from the default branch. + - The built image is pushed to the [GitLab container registry](../../packages/container_registry). A tag is applied to indicate whether the image was built from a merge request or from the default branch. 1. Use your image in your Terraform jobs, such as `build` and `deploy`. - You can combine your image with specialized `before_script` configurations to perform setup commands, like to generate inputs for Terraform. diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index d770c0111d0..5b0420d476e 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting the Terraform integration with GitLab diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 54f062884ee..04d6caff0ba 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure management **(FREE ALL)** diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 5787051a2c2..dfd38f7daf1 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance-level Kubernetes clusters (certificate-based) (deprecated) **(FREE SELF)** @@ -21,8 +21,7 @@ projects. To view the instance level Kubernetes clusters: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Kubernetes**. ## Cluster precedence diff --git a/doc/user/markdown.md b/doc/user/markdown.md index a06e26c3e82..01bd7ce0ba6 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Flavored Markdown (GLFM) **(FREE ALL)** @@ -78,6 +78,29 @@ Features [extended from standard Markdown](#features-extended-from-standard-mark | [line breaks](#line-breaks) | [more line break control](#newlines) | | [links](#links) | [automatically linking URLs](#url-auto-linking) | +## Markdown and accessibility + +When you use GitLab Flavored Markdown, you are creating digital content. +This content should be as accessible as possible to your audience. +The following list is not exhaustive, but it provides guidance for some of the GLFM styles to pay +particular attention to: + +### Headings + +Use heading formatting to create a logical heading structure. +The structure of headings on a page should make sense, like a good table of contents. +Ensure that there is only one `h1` element on a page, that heading levels are not skipped, and that they are nested correctly. + +### Tables + +To keep tables accessible and scannable, tables should not have any empty cells. +If there is no otherwise meaningful value for a cell, consider entering **N/A** for "not applicable" or **None**. + +### Images and videos + +Describe the image or video in the `[alt text]`. Make the description accurate, succinct, and unique. +Don't use `image of` or `video of` in the description. For more information, see [WebAim Alternative Text](https://webaim.org/techniques/alttext/). + ## Features not found in standard Markdown The following features are not found in standard Markdown. @@ -459,10 +482,21 @@ To create a task list, follow the format of an ordered or unordered list: ### Table of contents +<!-- +The following paragraphs use HTML to work around a Markdown bug. +Do not change it back to a Markdown backticks. +For more information, see https://gitlab.com/gitlab-org/gitlab/-/issues/359077. +--> +<!-- vale gitlab.Uppercase = NO --> A table of contents is an unordered list that links to subheadings in the document. You can add a table of contents to issues and merge requests, but you can't add one -to notes or comments. Add either the `[[_TOC_]]` or `[TOC]` tag on its own line +to notes or comments. Add either the `[[_TOC_]]` or <code>[TOC]</code> tag on its own line to the **Description** field of any of the supported content types: +<!-- vale gitlab.Uppercase = YES --> + +NOTE: +A table of contents renders also when you use <code>`[TOC]`</code>, regardless of being on its own line or not. +This behavior is unintended. For more information, see [issue 359077](https://gitlab.com/gitlab-org/gitlab/-/issues/359077). - Markdown files. - Wiki pages. diff --git a/doc/user/namespace/index.md b/doc/user/namespace/index.md index 00eb63da3ff..f4acde64dce 100644 --- a/doc/user/namespace/index.md +++ b/doc/user/namespace/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Namespaces diff --git a/doc/user/okrs.md b/doc/user/okrs.md index ca5882da22a..14e887fe297 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -54,14 +54,10 @@ To learn how to create better OKRs and how we use them at GitLab, see the ## Create an objective -Prerequisites: - -- You must have at least the Guest role for the project. - To create an objective: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Plan > Issues**. +1. Select **Plan > Issues**. 1. In the upper-right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. 1. Select **New objective** again. 1. Enter the objective title. @@ -71,28 +67,20 @@ To create a key result, [add it as a child](#add-a-child-key-result) to an exist ## View an objective -Prerequisites: - -- You must have at least the Guest role for the project. - To view an objective: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Plan > Issues**. +1. Select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = objective`. 1. Select the title of an objective from the list. ## View a key result -Prerequisites: - -- You must have at least the Guest role for the project. - To view a key result: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Plan > Issues**. +1. Select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = key_result`. 1. Select the title of a key result from the list. @@ -126,12 +114,12 @@ Prerequisites: - You must have at least the Reporter role for the project. -You can view all the system notes related to the task. By default they are sorted by **Oldest first**. +You can view all the [system notes](project/system_notes.md) related to the OKR. By default they are sorted by **Oldest first**. You can always change the sorting order to **Newest first**, which is remembered across sessions. ## Comments and threads -You can add [comments](discussions/index.md) and reply to threads in tasks. +You can add [comments](discussions/index.md) and reply to threads in OKRs. ## Assign users @@ -403,7 +391,7 @@ To turn off a check-in reminder, enter: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.6. -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the project. - The parent objective and child OKR must belong to the same project. @@ -431,6 +419,15 @@ leaking out. By default, OKRs are public. You can make an OKR confidential when you create or edit it. +#### In a new OKR + +When you create a new objective, a checkbox right below the text area is available to mark the +OKR as confidential. + +Select that checkbox and then select **Create objective** or **Create key result** to create the OKR. + +#### In an existing OKR + Prerequisites: - You must have at least the Reporter role for the project. @@ -443,20 +440,11 @@ Prerequisites: - To add child objectives or key results to a confidential objective, you must first make them confidential. -#### In a new OKR - -When you create a new objective, a checkbox right below the text area is available to mark the -OKR as confidential. - -Check that box and select **Create objective** or **Create key result** to create the OKR. - -#### In an existing OKR - To change the confidentiality of an existing OKR: 1. [Open the objective](#view-an-objective) or [key result](#view-a-key-result). 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). -1. Select **Turn on confidentiality**. +1. Select **Turn on confidentiality** or **Turn off confidentiality**. ### Who can see confidential OKRs @@ -504,16 +492,16 @@ When enabled, OKRs use a two-column layout, similar to issues. The description and threads are on the left, and attributes, such as labels or assignees, on the right. - + ## Linked items in OKRs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Enabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `linked_work_items`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `linked_work_items`. +On GitLab.com, this feature is available. Linked items are a bi-directional relationship and appear in a block below the Child objectives and key results. You can link an objective, key result, or a task in the same project with each other. @@ -522,18 +510,18 @@ The relationship only shows up in the UI if the user can see both items. ### Add a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. To link an item to an objective or key result: 1. In the **Linked items** section of an objective or key result, - select the **Add** button. + select **Add**. 1. Select the relationship between the two items. Either: - - **relates to** - - **blocks** - - **is blocked by** + - **Relates to** + - **Blocks** + - **Is blocked by** 1. Enter the search text of the item. 1. When you have added all the items to be linked, select **Add** below the search box. @@ -544,7 +532,7 @@ them categorized so their relationships can be better understood visually. ### Remove a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 3364d927a9b..3b53195ff2b 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operations Dashboard **(PREMIUM ALL)** diff --git a/doc/user/organization/index.md b/doc/user/organization/index.md index 5a08307cc11..c4fff4178f1 100644 --- a/doc/user/organization/index.md +++ b/doc/user/organization/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Organization @@ -30,20 +30,9 @@ everything you do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. - Aggregating data from all your groups, subgroups, and projects. -Our goal is to reach feature parity between SaaS and self-managed installations, with all -[Admin Area settings](../../administration/settings/index.md) moving to either: - -- Groups. Available in the Organization, and subgroups. -- Hardware Controls. For functionality that does not apply to groups, Hardware Controls are only - applicable to self-managed installations. There is one Hardware Controls section per installation. - For more information about the state of organization development, see [epic 9265](https://gitlab.com/groups/gitlab-org/-/epics/9265). -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video introduction to the new hierarchy concept for groups and projects for epics, see -[Consolidating groups and projects update (August 2021)](https://www.youtube.com/watch?v=fE74lsG_8yM). - ## View organizations To view the organizations you have access to: @@ -53,17 +42,25 @@ To view the organizations you have access to: ## Create an organization 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New organization**. -1. In the **Organization name** field, enter a name for the organization. -1. In the **Organization URL** field, enter a path for the organization. +1. In the **Organization name** text box, enter a name for the organization. +1. In the **Organization URL** text box, enter a path for the organization. 1. Select **Create organization**. ## Edit an organization's name 1. On the left sidebar, select **Organizations** (**{organization}**) and find the organization you want to edit. 1. Select **Settings > General**. -1. Update the **Organization name** field. +1. In the **Organization name** text box, edit the name. 1. Select **Save changes**. +## Change an organization's URL + +1. On the left sidebar, select **Organizations** (**{organization}**) and find organization whose URL you want to change. +1. Select **Settings > General**. +1. Expand the **Advanced** section. +1. In the **Organization URL** text box, edit the URL. +1. Select **Change organization URL**. + ## Manage groups and projects 1. On the left sidebar, select **Organizations** (**{organization}**) and find the organization you want to manage. @@ -78,3 +75,4 @@ To view the organizations you have access to: ## Related topics - [Organization developer documentation](../../development/organization/index.md) +- [Organization blueprint](../../architecture/blueprints/organization/index.md) diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 6eac299e71f..db3d31d3c18 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Composer packages in the Package Registry **(FREE ALL BETA)** +# Composer packages in the package registry **(FREE ALL BETA)** > - [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. @@ -16,7 +16,7 @@ The Composer package registry for GitLab is under development and isn't ready fo limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6817) details the remaining work and timelines to make it production ready. -Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry. +Publish [Composer](https://getcomposer.org/) packages in your project's package registry. Then, install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that the Composer @@ -29,7 +29,7 @@ Learn how to [build a Composer package](../workflows/build_packages.md#composer) ## Publish a Composer package by using the API -Publish a Composer package to the Package Registry, +Publish a Composer package to the package registry, so that anyone who can access the project can use the package as a dependency. Prerequisites: @@ -81,7 +81,7 @@ selecting the **Composer** tab. ## Publish a Composer package by using CI/CD -You can publish a Composer package to the Package Registry as part of your CI/CD process. +You can publish a Composer package to the package registry as part of your CI/CD process. 1. Specify a `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file: @@ -123,11 +123,11 @@ When you publish: > Authorization to [download a package archive](../../../api/packages/composer.md#download-a-package-archive) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331601) in GitLab 14.10. -Install a package from the Package Registry so you can use it as a dependency. +Install a package from the package registry so you can use it as a dependency. Prerequisites: -- A package in the Package Registry. +- A package in the package registry. - The group ID, which is on the group's home page. - One of the following token types: - A [personal access token](../../../user/profile/personal_access_tokens.md) @@ -138,9 +138,9 @@ Prerequisites: To install a package: -1. Add the Package Registry URL to your project's `composer.json` file, along with the package name and version you want to install: +1. Add the package registry URL to your project's `composer.json` file, along with the package name and version you want to install: - - Connect to the Package Registry for your group: + - Connect to the package registry for your group: ```shell composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 74152515198..56ea4fe74b4 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Conan packages in the Package Registry **(FREE ALL EXPERIMENT)** +# Conan packages in the package registry **(FREE ALL EXPERIMENT)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab 12.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -17,25 +17,25 @@ work and timelines to make it production ready. NOTE: The Conan registry is not FIPS compliant and is disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. -Publish Conan packages in your project's Package Registry. Then install the +Publish Conan packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. -To publish Conan packages to the Package Registry, add the Package Registry as a +To publish Conan packages to the package registry, add the package registry as a remote and authenticate with it. Then you can run `conan` commands and publish your package to the -Package Registry. +package registry. For documentation of the specific API endpoints that the Conan package manager client uses, see the [Conan API documentation](../../../api/packages/conan.md). Learn how to [build a Conan package](../workflows/build_packages.md#conan). -## Add the Package Registry as a Conan remote +## Add the package registry as a Conan remote -To run `conan` commands, you must add the Package Registry as a Conan remote for +To run `conan` commands, you must add the package registry as a Conan remote for your project or instance. Then you can publish packages to -and install packages from the Package Registry. +and install packages from the package registry. ### Add a remote for your project @@ -105,13 +105,13 @@ Example recipe names: [Project remotes](#add-a-remote-for-your-project) have a more flexible naming convention. -## Authenticate to the Package Registry +## Authenticate to the package registry GitLab requires authentication to upload packages, and to install packages from private and internal projects. (You can, however, install packages from public projects without authentication.) -To authenticate to the Package Registry, you need one of the following: +To authenticate to the package registry, you need one of the following: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. @@ -151,8 +151,8 @@ occasionally need to re-enter your personal access token. ### Set a default remote for your project (optional) -If you want to interact with the GitLab Package Registry without having to -specify a remote, you can tell Conan to always use the Package Registry for your +If you want to interact with the GitLab package registry without having to +specify a remote, you can tell Conan to always use the package registry for your packages. In a terminal, run this command: @@ -174,14 +174,14 @@ remote in your commands: ## Publish a Conan package -Publish a Conan package to the Package Registry, so that anyone who can access +Publish a Conan package to the package registry, so that anyone who can access the project can use the package as a dependency. Prerequisites: - The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). - [Authentication](#authenticate-to-the-package-registry) with the - Package Registry must be configured. + package registry must be configured. - A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html) must exist. - For an instance remote, the package must meet the [naming convention](#package-recipe-naming-convention-for-instance-remotes). @@ -229,7 +229,7 @@ only the most recently-published package is returned. ## Install a Conan package -Install a Conan package from the Package Registry so you can use it as a +Install a Conan package from the package registry so you can use it as a dependency. You can install a package from the scope of your instance or your project. If multiple packages have the same recipe, when you install a package, the most recently-published package is retrieved. @@ -242,7 +242,7 @@ Prerequisites: - The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). - For private and internal projects, you must configure [Authentication](#authenticate-to-the-package-registry) - with the Package Registry. + with the package registry. 1. In the project where you want to install the package as a dependency, open `conanfile.txt`. Or, in the root of your project, create a file called @@ -278,7 +278,7 @@ Delete `~/.conan/data` to clean up the packages stored in the cache. ## Remove a Conan package -There are two ways to remove a Conan package from the GitLab Package Registry. +There are two ways to remove a Conan package from the GitLab package registry. - From the command line, using the Conan client: @@ -291,14 +291,14 @@ There are two ways to remove a Conan package from the GitLab Package Registry. NOTE: This command removes all recipe and binary package files from the - Package Registry. + package registry. - From the GitLab user interface: Go to your project's **Deploy > Package Registry**. Remove the package by selecting **Remove repository** (**{remove}**). -## Search for Conan packages in the Package Registry +## Search for Conan packages in the package registry To search by full or partial package name, or by exact recipe, run the `conan search` command. @@ -327,7 +327,7 @@ packages in the target project, as long as you have permission to access it. NOTE: The limit of the search results is 500 packages, and the results are sorted by the most recently published packages. -## Fetch Conan package information from the Package Registry +## Fetch Conan package information from the package registry The `conan info` command returns information about a package: @@ -339,13 +339,13 @@ conan info Hello/0.1@mycompany/beta The GitLab Conan repository supports the following Conan CLI commands: -- `conan upload`: Upload your recipe and package files to the Package Registry. -- `conan install`: Install a Conan package from the Package Registry, which +- `conan upload`: Upload your recipe and package files to the package registry. +- `conan install`: Install a Conan package from the package registry, which includes using the `conanfile.txt` file. -- `conan search`: Search the Package Registry for public packages, and private +- `conan search`: Search the package registry for public packages, and private packages you have permission to view. -- `conan info`: View the information on a given package from the Package Registry. -- `conan remove`: Delete the package from the Package Registry. +- `conan info`: View the information on a given package from the package registry. +- `conan remove`: Delete the package from the package registry. ## Troubleshooting diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index 2aab69877ff..ae19a891fc9 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -1,17 +1,12 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Authenticate with the Container Registry **(FREE ALL)** +# Authenticate with the container registry **(FREE ALL)** -<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> -WARNING: -In GitLab 16.0 and later, [external authorization](../../admin_area/settings/external_authorization.md) prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. -<!--- end_remove --> - -To authenticate with the Container Registry, you can use a: +To authenticate with the container registry, you can use a: - [Personal access token](../../profile/personal_access_tokens.md). - [Deploy token](../../project/deploy_tokens/index.md). @@ -31,11 +26,11 @@ To authenticate, run the `docker login` command. For example: ## Use GitLab CI/CD to authenticate -To use CI/CD to authenticate with the Container Registry, you can use: +To use CI/CD to authenticate with the container registry, you can use: - The `CI_REGISTRY_USER` CI/CD variable. - This variable has read-write access to the Container Registry and is valid for + This variable has read-write access to the container registry and is valid for one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. ```shell diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index 93140e34493..680aab42544 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -1,18 +1,18 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Build and push container images to the Container Registry **(FREE ALL)** +# Build and push container images to the container registry **(FREE ALL)** -Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the Container Registry. +Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the container registry. ## Use Docker commands -You can use Docker commands to build and push container images to your Container Registry: +You can use Docker commands to build and push container images to your container registry: -1. [Authenticate](authenticate_with_container_registry.md) with the Container Registry. +1. [Authenticate](authenticate_with_container_registry.md) with the container registry. 1. Run the Docker command to build or push. For example: - To build: @@ -29,7 +29,7 @@ You can use Docker commands to build and push container images to your Container ## Configure your `.gitlab-ci.yml` file -You can configure your `.gitlab-ci.yml` file to build and push container images to the Container Registry. +You can configure your `.gitlab-ci.yml` file to build and push container images to the container registry. - If multiple jobs require authentication, put the authentication command in the `before_script`. - Before building, use `docker build --pull` to fetch changes to base images. It takes slightly @@ -50,7 +50,7 @@ You can use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push containe Container Registry. You can use CI/CD to test, build, and deploy your project from the container image you created. -### Use a Docker-in-Docker container image from your Container Registry +### Use a Docker-in-Docker container image from your container registry You can use your own container images for Docker-in-Docker. @@ -108,7 +108,7 @@ and an error like the following is shown: error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host ``` -## Container Registry examples with GitLab CI/CD +## Container registry examples with GitLab CI/CD If you're using Docker-in-Docker on your runners, your `.gitlab-ci.yml` file should look similar to this: diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md index 0b91a9453a7..852c20a80f5 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -1,12 +1,12 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Delete container images from the Container Registry **(FREE ALL)** +# Delete container images from the container registry **(FREE ALL)** -You can delete container images from your Container Registry. +You can delete container images from your container registry. WARNING: Deleting container images is a destructive action and can't be undone. To restore @@ -18,9 +18,9 @@ Deleting a container image on self-managed instances doesn't free up storage spa as eligible for deletion. To actually delete unreferenced container images and recover storage space, 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 +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/). -In this new version of the Container Registry, the following are automatically scheduled +In this new version of the container registry, the following are automatically scheduled for deletion in 24 hours if left unreferenced: - Layers that aren't referenced by any image manifest. @@ -117,4 +117,4 @@ the code example by changing the `REG_SHA256` and `REG_VERSION` variables define ## Use a cleanup policy You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and -images are regularly removed from the Container Registry. +images are regularly removed from the container registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 786fd0ca658..13bdd9ad4e5 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -1,25 +1,25 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Container Registry **(FREE ALL)** +# GitLab container registry **(FREE ALL)** > Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. -You can use the integrated Container Registry to store container images for each GitLab project +You can use the integrated container registry to store container images for each GitLab project -To enable the Container Registry for your GitLab instance, see the [administrator documentation](../../../administration/packages/container_registry.md). +To enable the container registry for your GitLab instance, see the [administrator documentation](../../../administration/packages/container_registry.md). NOTE: If you pull Docker container images from Docker Hub, you can use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid rate limits and speed up your pipelines. For more information about the Docker Registry, see <https://docs.docker.com/registry/introduction/>. -## View the Container Registry +## View the container registry -You can view the Container Registry for a project or group. +You can view the container registry for a project or group. 1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: @@ -29,14 +29,14 @@ You can view the Container Registry for a project or group. You can search, sort, filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) your container images. You can share a filtered view by copying the URL from your browser. -Only members of the project or group can access the Container Registry for a private project. +Only members of the project or group can access the container registry for a private project. Container images downloaded from a private registry may be [available to other users in a shared runner](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). -If a project is public, the Container Registry is also public. +If a project is public, the container registry is also public. -### View the tags of a specific container image in the Container Registry +### View the tags of a specific container image in the container registry -You can use the Container Registry **Tag Details** page to view a list of tags associated with a given container image: +You can use the container registry **Tag Details** page to view a list of tags associated with a given container image: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: @@ -50,9 +50,9 @@ and the manifest and configuration digests. You can search, sort (by tag name), filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) tags on this page. You can share a filtered view by copying the URL from your browser. -## Use container images from the Container Registry +## Use container images from the container registry -To download and run a container image hosted in the Container Registry: +To download and run a container image hosted in the container registry: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: @@ -101,19 +101,19 @@ registry.example.com/mynamespace/myproject/image:latest registry.example.com/mynamespace/myproject/my/image:rc1 ``` -## Move or rename Container Registry repositories +## Move or rename container registry repositories -Moving or renaming existing Container Registry repositories is not supported after you have pushed +Moving or renaming existing container registry repositories is not supported after you have pushed container images. The container images are stored in a path that matches the repository path. To move -or rename a repository with a Container Registry, you must delete all existing container images. +or rename a repository with a container registry, you must delete all existing container images. Community suggestions to work around this known issue are shared in [issue 18383](https://gitlab.com/gitlab-org/gitlab/-/issues/18383#possible-workaround). -## Disable the Container Registry for a project +## Disable the container registry for a project -The Container Registry is enabled by default. +The container registry is enabled by default. -You can, however, remove the Container Registry for a project: +You can, however, remove the container registry for a project: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. @@ -123,51 +123,55 @@ You can, however, remove the Container Registry for a project: The **Deploy > Container Registry** entry is removed from the project's sidebar. -## Change visibility of the Container Registry +## Change visibility of the container registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18792) in GitLab 14.2. -By default, the Container Registry is visible to everyone with access to the project. -You can, however, change the visibility of the Container Registry for a project. +By default, the container registry is visible to everyone with access to the project. +You can, however, change the visibility of the container registry for a project. For more information about the permissions that this setting grants to users, -see [Container Registry visibility permissions](#container-registry-visibility-permissions). +see [Container registry visibility permissions](#container-registry-visibility-permissions). 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand the section **Visibility, project features, permissions**. 1. Under **Container Registry**, select an option from the dropdown list: - - **Everyone With Access** (Default): The Container Registry is visible to everyone with access - to the project. If the project is public, the Container Registry is also public. If the project - is internal or private, the Container Registry is also internal or private. + - **Everyone With Access** (Default): The container registry is visible to everyone with access + to the project. If the project is public, the container registry is also public. If the project + is internal or private, the container registry is also internal or private. - - **Only Project Members**: The Container Registry is visible only to project members with + - **Only Project Members**: The container registry is visible only to project members with at least the Reporter role. This visibility is similar to the behavior of a private project with Container Registry visibility set to **Everyone With Access**. 1. Select **Save changes**. -## Container Registry visibility permissions +## Container registry visibility permissions -The ability to view the Container Registry and pull container images is controlled by the Container Registry's +The ability to view the container registry and pull container images is controlled by the container registry's visibility permissions. You can change the visibility through the [visibility setting on the UI](#change-visibility-of-the-container-registry) or the [API](../../../api/container_registry.md#change-the-visibility-of-the-container-registry). -[Other permissions](../../permissions.md) such as updating the Container Registry and pushing or deleting container images are not affected by -this setting. However, disabling the Container Registry disables all Container Registry operations. +[Other permissions](../../permissions.md) such as updating the container registry and pushing or deleting container images are not affected by +this setting. However, disabling the container registry disables all Container Registry operations. | | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | |-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|--------------------------------------|-------|----------------------------------------| -| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes | -| Public project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes | -| Internal project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | +| Public project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | Yes | Yes | Yes | +| Public project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes | +| Internal project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | No | Yes | Yes | +| Internal project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes | +| Private project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | No | No | Yes | +| Private project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes | +| Any project with container registry `disabled` | All operations on container registry | No | No | No | ## Supported image types -The Container Registry supports [Docker V2](https://docs.docker.com/registry/spec/manifest-v2-2/) and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md) image formats. +> OCI conformance [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10345) in GitLab 16.6. + +The container registry supports the [Docker V2](https://docs.docker.com/registry/spec/manifest-v2-2/) +and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md) +image formats. Additionally, the container registry [conforms to the OCI distribution specification](https://conformance.opencontainers.org/#gitlab-container-registry). OCI support means that you can host OCI-based image formats in the registry, such as [Helm 3+ chart packages](https://helm.sh/docs/topics/registries/). There is no distinction between image formats in the GitLab [API](../../../api/container_registry.md) and the UI. [Issue 38047](https://gitlab.com/gitlab-org/gitlab/-/issues/38047) addresses this distinction, starting with Helm. diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md index 9ac00445b95..c2a48d1e91a 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md +++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md @@ -1,14 +1,14 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Reduce Container Registry data transfers **(FREE ALL)** +# Reduce container registry data transfers **(FREE ALL)** -Depending on the frequency with which images or tags are downloaded from the Container Registry, +Depending on the frequency with which images or tags are downloaded from the container registry, data transfers can exceed the GitLab.com limit. This page offers several recommendations and tips for -reducing the amount of data you transfer with the Container Registry. +reducing the amount of data you transfer with the container registry. ## Check data transfer use diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index 8c4f25af2e1..614639c705f 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -1,10 +1,10 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Reduce Container Registry storage **(FREE ALL)** +# Reduce container registry storage **(FREE ALL)** Container registries can grow in size over time if you don't manage your registry usage. For example, if you add a large number of images or tags: @@ -15,16 +15,21 @@ if you add a large number of images or tags: You should delete unnecessary images and tags and set up a [cleanup policy](#cleanup-policy) to automatically manage your container registry usage. -## Check Container Registry storage use **(FREE SAAS)** +## View container registry usage **(FREE SAAS)** -The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. -Measuring usage is only possible on the new version of the GitLab Container Registry backed by a -metadata database, which is [available on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/5523) since GitLab 15.7. -For information on the planned availability for self-managed instances, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5523) in GitLab 15.7 + +To view the storage usage for the container registry: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > Usage Quotas**. + +You cannot view container registry usage for self-managed instances, but this is +proposed in [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). ## How container registry usage is calculated -Image layers stored in the Container Registry are deduplicated at the root namespace level. +Image layers stored in the container registry are deduplicated at the root namespace level. An image is only counted once if: @@ -75,7 +80,7 @@ the size value only changes when: > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. > - [Required permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) changed from developer to maintainer in GitLab 15.0. -The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. +The cleanup policy is a scheduled job you can use to remove tags from the container registry. For the project where it's defined, tags matching the regex pattern are removed. The underlying layers and images remain. @@ -106,7 +111,7 @@ GitLab.com that don't have a container image. ### How the cleanup policy works -The cleanup policy collects all tags in the Container Registry and excludes tags until the only +The cleanup policy collects all tags in the container registry and excludes tags until the only tags you want to delete remain. The cleanup policy searches for images based on the tag name. Support for full path matching is tracked in issue [281071](https://gitlab.com/gitlab-org/gitlab/-/issues/281071). @@ -121,11 +126,11 @@ The cleanup policy: 1. Orders the remaining tags by `created_date`. 1. Excludes the N tags based on the `keep_n` value (Number of tags to retain). 1. Excludes the tags more recent than the `older_than` value (Expiration interval). -1. Deletes the remaining tags in the list from the Container Registry. +1. Deletes the remaining tags in the list from the container registry. WARNING: On GitLab.com, the execution time for the cleanup policy is limited. Some tags may remain in -the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included. +the container registry after the policy runs. The next time the policy runs, the remaining tags are included. It may take multiple runs to delete all tags. WARNING: @@ -274,11 +279,10 @@ For self-managed instances, those settings can be updated in the [Rails console] ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) ``` -They are also available in the [administrator area](../../admin_area/index.md): +They are also available in the [administrator area](../../../administration/admin_area.md): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD** +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD** 1. Expand **Container Registry**. ### Use the cleanup policy API @@ -331,9 +335,9 @@ the GitLab background jobs may get backed up or fail completely. For projects created before GitLab 12.8, you should enable container cleanup policies only if the number of tags being cleaned up is minimal. -## More Container Registry storage reduction options +## More container registry storage reduction options -Here are some other options you can use to reduce the Container Registry storage used by your project: +Here are some other options you can use to reduce the container registry storage used by your project: - Use the [GitLab UI](delete_container_registry_images.md#use-the-gitlab-ui) to delete individual image tags or the entire repository containing all the tags. @@ -371,7 +375,7 @@ There can be different reasons behind this: - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). This limits the cleanup execution in time, and avoids the expired token error. - - Extend the expiration delay of the Container Registry authentication tokens. This defaults to 5 + - Extend the expiration delay of the container registry authentication tokens. This defaults to 5 minutes. You can set a custom value by running `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)` in the Rails console, where `<integer>` is the desired number of minutes. For reference, the expiration delay diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md index 3fb2754eb9c..b923be94bfe 100644 --- a/doc/user/packages/container_registry/troubleshoot_container_registry.md +++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md @@ -1,20 +1,20 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Troubleshooting the GitLab Container Registry +# Troubleshooting the GitLab container registry -You must sign in to GitLab with administrator rights to troubleshoot most issues with the GitLab Container Registry. +You must sign in to GitLab with administrator rights to troubleshoot most issues with the GitLab container registry. -You can find [additional troubleshooting information](../../../administration/packages/container_registry.md#troubleshooting) in the GitLab Container Registry administration documentation. +You can find [additional troubleshooting information](../../../administration/packages/container_registry.md#troubleshooting) in the GitLab container registry administration documentation. -## Migrating OCI container images to GitLab Container Registry +## Migrating OCI container images to GitLab container registry Migrating container images to the GitLab registry is not supported, but [epic](https://gitlab.com/groups/gitlab-org/-/epics/5210) proposes to change this behavior. -You can use third-party tools to migrate container images. For example, [skopeo](https://github.com/containers/skopeo), can [copy container images](https://github.com/containers/skopeo#copying-images) between various storage mechanisms. You can use skopeo to copy from container registries, container storage backends, local directories, and local OCI-layout directories to the GitLab Container Registry. +You can use third-party tools to migrate container images. For example, [skopeo](https://github.com/containers/skopeo), can [copy container images](https://github.com/containers/skopeo#copying-images) between various storage mechanisms. You can use skopeo to copy from container registries, container storage backends, local directories, and local OCI-layout directories to the GitLab container registry. ## Docker connection error @@ -25,19 +25,19 @@ project, or branch name. Special characters include: - A trailing hyphen or dash. To resolve this error, you can change the [group path](../../group/manage.md#change-a-groups-path), -the [project path](../../project/settings/index.md#rename-a-repository) or the branch name. +the [project path](../../project/working_with_projects.md#rename-a-repository) or the branch name. You may get a `404 Not Found` or `Unknown Manifest` error message if you use Docker Engine 17.11 or earlier. Current versions of Docker Engine use the [v2 API](https://docs.docker.com/registry/spec/manifest-v2-2/). -The images in your GitLab Container Registry must use the Docker v2 API. +The images in your GitLab container registry must use the Docker v2 API. For information on how to update version 1 images to version 2, see the [Docker documentation](https://docs.docker.com/registry/spec/deprecated-schema-v1). ## `Blob unknown to registry` error when pushing a manifest list When [pushing a Docker manifest list](https://docs.docker.com/engine/reference/commandline/manifest/#create-and-push-a-manifest-list) -to the GitLab Container Registry, you may receive the error +to the GitLab container registry, you may receive the error `manifest blob unknown: blob unknown to registry`. This error is likely caused by having multiple images with different architectures spread out over several repositories instead of the same repository. @@ -61,7 +61,7 @@ you may receive one of the following errors: - Project cannot be transferred because tags are present in its container registry. - Namespace cannot be moved because at least one project has tags in the container registry. -This error occurs when the project has images in the Container Registry. +This error occurs when the project has images in the container registry. You must delete or move these images before you change the path or transfer the project. @@ -122,7 +122,7 @@ unauthorized: authentication required ``` This error happens when your authentication token expires before the image push is complete. By default, tokens for -the Container Registry on self-managed GitLab instances expire every five minutes. On GitLab.com, the token expiration +the container registry on self-managed GitLab instances expire every five minutes. On GitLab.com, the token expiration time is set to 15 minutes. If you are using self-managed GitLab, an administrator can diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 45ebfb2ef73..86d85b5e0ca 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Debian packages in the Package Registry **(FREE SELF EXPERIMENT)** +# Debian packages in the package registry **(FREE SELF EXPERIMENT)** > - Debian API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42670) in GitLab 13.5. > - Debian group API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66188) in GitLab 14.2. @@ -14,7 +14,7 @@ WARNING: The Debian package registry for GitLab is under development and isn't ready for production use. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining work and timelines to make it production ready. Support for [Debian packages is an experiment](../package_registry/supported_package_managers.md), and has known security vulnerabilities. -Publish Debian packages in your project's Package Registry. Then install the +Publish Debian packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. Project and Group packages are supported. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 02810bcb922..9037abde1cf 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Proxy **(FREE ALL)** @@ -86,9 +86,9 @@ docker login gitlab.example.com --username my_username --password my_password You can authenticate using: - Your GitLab username and password. -- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. +- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`, or to `api`. - A [group deploy token](../../../user/project/deploy_tokens/index.md) with the scope set to `read_registry` and `write_registry`. -- A [group access token](../../../user/group/settings/group_access_tokens.md) for the group, with the scope set to `read_registry` and `write_registry`. +- A [group access token](../../../user/group/settings/group_access_tokens.md) for the group, with the scope set to `read_registry` and `write_registry`, or to `api`. Users accessing the Dependency Proxy with a personal access token or username and password must have at least the Guest role for the group they pull images from. @@ -170,7 +170,7 @@ build: before_script: - docker login -u $CI_DEPENDENCY_PROXY_USER -p $CI_DEPENDENCY_PROXY_PASSWORD $CI_DEPENDENCY_PROXY_SERVER script: - - docker build -t test . + - docker build -t test . ``` You can also use [custom CI/CD variables](../../../ci/variables/index.md#for-a-project) to store and access your personal access token or deploy token. diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md index e24a3d3fa84..3b565f3a3ad 100644 --- a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md +++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce Dependency Proxy Storage **(FREE ALL)** diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 1416dcde14f..188b634af0a 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Generic Packages Repository **(FREE ALL)** @@ -9,11 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `generic_packages`. Enabled by default. > - [Feature flag `generic_packages`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80886) removed in GitLab 14.8. -Publish generic files, like release binaries, in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. +Publish generic files, like release binaries, in your project's package registry. Then, install the packages whenever you need to use them as a dependency. -## Authenticate to the Package Registry +## Authenticate to the package registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), +To authenticate to the package registry, you need either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), [CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package @@ -142,8 +142,8 @@ If multiple packages have the same name, version, and filename, then the most re Prerequisites: -- You need to [authenticate with the API](../../../api/rest/index.md#authentication). - - If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). + - If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. - Project access tokens require the `read_api` scope and at least the `Reporter` role. ```plaintext diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 6dffd7371b6..590a3d1e949 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Go proxy for GitLab **(FREE ALL EXPERIMENT)** @@ -53,7 +53,7 @@ Feature.disable(:go_proxy, Project.find(2)) ``` NOTE: -Even if it's enabled, GitLab doesn't display Go modules in the **Package Registry**. +Even if it's enabled, GitLab doesn't display Go modules in the **package registry**. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details. diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index d45b6ea7026..85e1f1b5fd1 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Harbor Registry **(FREE ALL)** diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index b7888fe2d18..891dc59bb80 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Helm charts in the Package Registry **(FREE ALL BETA)** +# Helm charts in the package registry **(FREE ALL BETA)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. @@ -13,7 +13,7 @@ The Helm chart registry for GitLab is under development and isn't ready for prod limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6366) details the remaining work and timelines to make it production ready. -Publish Helm packages in your project's Package Registry. Then install the +Publish Helm packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that Helm package manager @@ -127,7 +127,7 @@ See [Using Helm](https://helm.sh/docs/intro/using_helm/) for more information. ## Troubleshooting -### The chart is not visible in the Package Registry after uploading +### The chart is not visible in the package registry after uploading Check the [Sidekiq log](../../../administration/logs/index.md#sidekiqlog) for any related errors. If you see `Validation failed: Version is invalid`, it means that the diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 8173a0407f0..3abdbfd83b3 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -1,16 +1,16 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Packages and Registries **(FREE ALL)** -The GitLab [Package Registry](package_registry/index.md) acts as a private or public registry +The GitLab [package registry](package_registry/index.md) acts as a private or public registry for a variety of common package managers. You can publish and share packages, which can be easily consumed as a dependency in downstream projects. -## Container Registry +## Container registry The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index c8730c42022..8f702183adc 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -1,12 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Maven packages in the Package Registry **(FREE ALL)** +# Maven packages in the package registry **(FREE ALL)** -Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. +Publish [Maven](https://maven.apache.org) artifacts in your project's package registry. Then, install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that the Maven package manager @@ -20,9 +20,9 @@ Supported clients: - `sbt` can only be used to [pull dependencies](#install-a-package). See this [issue 408479](https://gitlab.com/gitlab-org/gitlab/-/issues/408479) for more details. -## Publish to the GitLab Package Registry +## Publish to the GitLab package registry -### Authenticate to the Package Registry +### Authenticate to the package registry You need a token to publish a package. There are different tokens available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../package_registry/index.md#authenticate-with-the-registry). @@ -135,7 +135,7 @@ file: ##### Basic HTTP Authentication -You can also use basic HTTP authentication to authenticate to the Maven Package Registry. +You can also use basic HTTP authentication to authenticate to the Maven package registry. ::Tabs @@ -237,7 +237,7 @@ You must to provide a name and a password. NOTE: The name field must be named to match the token you chose. -To install a package from the Maven GitLab Package Registry by using `sbt`, you must configure +To install a package from the Maven GitLab package registry by using `sbt`, you must configure a [Maven resolver](https://www.scala-sbt.org/1.x/docs/Resolvers.html#Maven+resolvers). If you're accessing a private or an internal project or group, you need to set up [credentials](https://www.scala-sbt.org/1.x/docs/Publishing.html#Credentials). @@ -458,7 +458,7 @@ Go to your project's **Packages and registries** page and view the published pac ## Install a package -To install a package from the GitLab Package Registry, you must configure +To install a package from the GitLab package registry, you must configure the [remote and authenticate](#authenticate-to-the-package-registry). When this is completed, you can install a package from a project, group, or namespace. @@ -466,6 +466,9 @@ group, or namespace. If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. +In case there are not enough permissions to read the most recently-published +package than `403 Forbidden` is returning. + ::Tabs :::TabTitle `mvn` @@ -489,7 +492,7 @@ To install a package by using `mvn install`: mvn install ``` -The message should show that the package is downloading from the Package Registry: +The message should show that the package is downloading from the package registry: ```shell Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom @@ -509,7 +512,7 @@ You can also install packages by using the Maven [`dependency:get` command](http NOTE: The repository IDs in the command(`gitlab-maven`) and the `settings.xml` file must match. -The message should show that the package is downloading from the Package Registry: +The message should show that the package is downloading from the package registry: ```shell Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom @@ -592,11 +595,11 @@ FLAG: By default this feature is not available for self-managed. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. This feature is not available for SaaS users. -When a Maven package is not found in the Package Registry, the request is forwarded +When a Maven package is not found in the package registry, the request is forwarded to [Maven Central](https://search.maven.org/). When the feature flag is enabled, administrators can disable this behavior in the -[Continuous Integration settings](../../admin_area/settings/continuous_integration.md). +[Continuous Integration settings](../../../administration/settings/continuous_integration.md). Maven forwarding is restricted to only the project level and group level [endpoints](#naming-convention). The instance level endpoint @@ -789,13 +792,13 @@ The GitLab Maven repository supports the following CLI commands: :::TabTitle `mvn` -- `mvn deploy`: Publish your package to the Package Registry. +- `mvn deploy`: Publish your package to the package registry. - `mvn install`: Install packages specified in your Maven project. - `mvn dependency:get`: Install a specific package. :::TabTitle `gradle` -- `gradle publish`: Publish your package to the Package Registry. +- `gradle publish`: Publish your package to the package registry. - `gradle install`: Install packages specified in your Gradle project. ::EndTabs diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 43defb29fd5..7a94db939cc 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -1,20 +1,20 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# npm packages in the Package Registry **(FREE ALL)** +# npm packages in the package registry **(FREE ALL)** For documentation of the specific API endpoints that the npm package manager client uses, see the [npm API documentation](../../../api/packages/npm.md). Learn how to build an [npm](../workflows/build_packages.md#npm) or [yarn](../workflows/build_packages.md#yarn) package. -Watch a [video demo](https://youtu.be/yvLxtkvsFDA) of how to publish npm packages to the GitLab Package Registry. +Watch a [video demo](https://youtu.be/yvLxtkvsFDA) of how to publish npm packages to the GitLab package registry. -## Publish to GitLab Package Registry +## Publish to GitLab package registry -### Authentication to the Package Registry +### Authentication to the package registry You need an token to publish a package. There are different tokens available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry). @@ -43,7 +43,7 @@ If you plan to install a package through the [instance level](#install-from-the- of the project with the source code of the package itself. The scope should be lowercase. - The package name can be anything you want -| Project URL | Package Registry in | Scope | Full package name | +| Project URL | Package registry in | Scope | Full package name | | ------------------------------------------------------- | ------------------- | --------- | ---------------------- | | `https://gitlab.com/my-org/engineering-group/analytics` | Analytics | `@my-org` | `@my-org/package-name` | @@ -81,11 +81,11 @@ Associate your [token](#authentication-to-the-package-registry) with the `"${NPM NPM_TOKEN=your_token npm publish ``` -Your package should now publish to the Package Registry. +Your package should now publish to the package registry. ## Publishing a package by using a CI/CD pipeline -When publishing by using a CI/CD pipeline, you can use the [predefined variables](../../../ci/variables/predefined_variables.md) `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` to authenticate with your project's Package Registry. We use these variables to create a `.npmrc` file [for authentication](#authenticating-via-the-npmrc) during execution of your CI/CD job. +When publishing by using a CI/CD pipeline, you can use the [predefined variables](../../../ci/variables/predefined_variables.md) `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` to authenticate with your project's package registry. We use these variables to create a `.npmrc` file [for authentication](#authenticating-via-the-npmrc) during execution of your CI/CD job. WARNING: When generating the `.npmrc` file, do not specify the port after `${CI_SERVER_HOST}` if it is a default port, @@ -109,7 +109,7 @@ publish-npm: - Replace `@scope` with the [scope](https://docs.npmjs.com/cli/v10/using-npm/scope) of the package that is being published. -Your package is published to the Package Registry when the `publish-npm` job in your pipeline runs. +Your package is published to the package registry when the `publish-npm` job in your pipeline runs. ## Install a package @@ -121,9 +121,9 @@ You can install a package from a GitLab project, group, or instance: - **Group-level**: Use when you have many npm packages in different projects in the same GitLab group. - **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -### Authenticate to the Package Registry +### Authenticate to the package registry -You must authenticate to the Package Registry to install a package from a private project or a private group. +You must authenticate to the package registry to install a package from a private project or a private group. No authentication is needed if the project or the group is public. To authenticate with `npm`: @@ -171,7 +171,7 @@ are not supported. WARNING: To install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). -1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). +1. [Authenticate to the package registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -194,7 +194,7 @@ To install a package from the instance level, the package must have been publish > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `npm_group_level_endpoints`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121837) in GitLab 16.1. Feature flag `npm_group_level_endpoints` removed. -1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). +1. [Authenticate to the package registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -214,7 +214,7 @@ To install a package from the instance level, the package must have been publish ### Install from the project level -1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). +1. [Authenticate to the package registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -232,6 +232,18 @@ To install a package from the instance level, the package must have been publish npm install @scope/my-package ``` +### Package forwarding to npmjs.com + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in GitLab 12.9. + +When an npm package is not found in the package registry, GitLab responds with an HTTP redirect so the requesting client can resend the request to [npmjs.com](https://www.npmjs.com/). + +Administrators can disable this behavior in the [Continuous Integration settings](../../../administration/settings/continuous_integration.md). + +Group owners can disable this behavior in the group **Packages and registries** settings. + +Improvements are tracked in [epic 3608](https://gitlab.com/groups/gitlab-org/-/epics/3608). + ## Deprecate a package > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396763) in GitLab 16.0. @@ -267,14 +279,6 @@ npm deprecate @scope/package "" ## Helpful hints -### Package forwarding to npmjs.com - -When an npm package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). The forward is performed by sending an HTTP redirect back to the requesting client. - -Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). - -Group owners can disable this behavior in the group Packages and Registries settings. - ### Install npm packages from other organizations You can route package requests to organizations and users outside of GitLab. @@ -289,7 +293,7 @@ and use your organization's URL. The name is case-sensitive and must match the n ### npm metadata -The GitLab Package Registry exposes the following attributes to the npm client. +The GitLab package registry exposes the following attributes to the npm client. These are similar to the [abbreviated metadata format](https://github.com/npm/registry/blob/9e368cf6aaca608da5b2c378c0d53f475298b916/docs/responses/package-metadata.md#abbreviated-metadata-format): - `name` @@ -407,7 +411,7 @@ And the `.npmrc` file should look like: If you get this error, ensure that: -- The Package Registry is enabled in your project settings. Although the Package Registry is enabled by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry). +- The package registry is enabled in your project settings. Although the package registry is enabled by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry). - Your token is not expired and has appropriate permissions. - A package with the same name or version doesn't already exist within the given scope. - The scoped packages URL includes a trailing slash: diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 8db79dc6c5f..76a97834a73 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -1,19 +1,19 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# NuGet packages in the Package Registry **(FREE ALL)** +# NuGet packages in the package registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. > - Symbol package support [added](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) in GitLab 14.1. -Publish NuGet packages in your project's Package Registry. Then, install the +Publish NuGet packages in your project's package registry. Then, install the packages whenever you need to use them as a dependency. -The Package Registry works with: +The package registry works with: - [NuGet CLI](https://learn.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference) - [.NET Core CLI](https://learn.microsoft.com/en-us/dotnet/core/tools/) @@ -37,18 +37,18 @@ To use the GitLab endpoint for NuGet Packages, choose an option: Some features such as [publishing](#publish-a-nuget-package) a package are only available on the project-level endpoint. -When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 most recent versions. +When asking for versions of a given NuGet package name, the GitLab package registry returns a maximum of 300 most recent versions. Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. WARNING: -Because of how NuGet handles credentials, the Package Registry rejects anonymous requests on the group-level endpoint. +Because of how NuGet handles credentials, the package registry rejects anonymous requests on the group-level endpoint. To work around this limitation, set up [authentication](#add-the-package-registry-as-a-source-for-nuget-packages). -## Add the Package Registry as a source for NuGet packages +## Add the package registry as a source for NuGet packages -To publish and install packages to the Package Registry, you must add the -Package Registry as a source for your packages. +To publish and install packages to the package registry, you must add the +package registry as a source for your packages. Prerequisites: @@ -76,10 +76,10 @@ You can now add a new source to NuGet with: #### Project-level endpoint -A project-level endpoint is required to publish NuGet packages to the Package Registry. +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`: +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with `nuget`: ```shell nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> @@ -97,7 +97,7 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/proje 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`: +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with `nuget`: ```shell nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> @@ -115,10 +115,10 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/group #### Project-level endpoint -A project-level endpoint is required to publish NuGet packages to the Package Registry. +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 Visual Studio: +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). 1. In Windows, select **Tools > Options**. On macOS, select **Visual Studio > Preferences**. @@ -146,7 +146,7 @@ If you get a warning, ensure that the **Source**, **Username**, and To install a 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 Visual Studio: +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). 1. In Windows, select **Tools > Options**. On macOS, select **Visual Studio > Preferences**. @@ -174,11 +174,11 @@ If you get a warning, ensure that the **Source**, **Username**, and #### Project-level endpoint -A project-level endpoint is required to publish NuGet packages to the Package Registry. +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`: +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> @@ -198,7 +198,7 @@ dotnet nuget add source "https://gitlab.example.com/api/v4/projects/10/packages/ 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`: +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> @@ -219,10 +219,10 @@ dotnet nuget add source "https://gitlab.example.com/api/v4/groups/23/-/packages/ A project-level endpoint is required to: -- Publish NuGet packages to the Package Registry. +- 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: +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`. 1. Add this content: @@ -254,7 +254,7 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package To install a package from a group, use a group-level endpoint. -To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: +To use the [group-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`. 1. Add this content: @@ -288,11 +288,11 @@ You can add a source feed with the Chocolatey CLI. If you use Chocolatey CLI v1. #### Configure a project-level endpoint -You need a project-level endpoint to publish NuGet packages to the Package Registry. +You need a project-level endpoint to publish NuGet packages to the package registry. -To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for Chocolatey: +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) package registry as a source for Chocolatey: -- Add the Package Registry as a source with `choco`: +- Add the package registry as a source with `choco`: ```shell choco source add -n=gitlab -s "'https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/v2'" -u=<gitlab_username or deploy_token_username> -p=<gitlab_personal_access_token or deploy_token> @@ -300,13 +300,13 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package ## Publish a NuGet package -Prerequisite: +Prerequisites: - Set up the [source](#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). When publishing packages: -- The Package Registry on GitLab.com can store up to 5 GB of content. +- The package registry on GitLab.com can store up to 5 GB of content. This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). - If you publish the same package with the same version multiple times, each consecutive upload is saved as a separate file. When installing a package, @@ -362,7 +362,7 @@ dotnet nuget push <package_file> --source <source_url> --api-key <gitlab_persona ``` - `<package_file>` is your package filename, ending in `.nupkg`. -- `<source_url>` is the URL of the NuGet Package Registry. +- `<source_url>` is the URL of the NuGet package registry. For example: @@ -406,9 +406,9 @@ updated: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2. -Prerequisite: +Prerequisites: -- The project-level Package Registry is a source for Chocolatey. +- The project-level package registry is a source for Chocolatey. To publish a package with the Chocolatey CLI: @@ -419,7 +419,7 @@ choco push <package_file> --source <source_url> --api-key <gitlab_personal_acces In this command: - `<package_file>` is your package filename and ends with `.nupkg`. -- `<source_url>` is the URL of the NuGet v2 feed Package Registry. +- `<source_url>` is the URL of the NuGet v2 feed package registry. For example: @@ -457,14 +457,14 @@ not be recognized as a duplicate. If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. -To install a NuGet package from the Package Registry, you must first +To install a NuGet package from the package registry, you must first [add a project-level or group-level endpoint](#add-the-package-registry-as-a-source-for-nuget-packages). ### Install a package with the NuGet CLI WARNING: By default, `nuget` checks the official source at `nuget.org` first. If you have -a NuGet package in the Package Registry with the same name as a package at +a NuGet package in the package registry with the same name as a package at `nuget.org`, you must specify the source name to install the correct package. Install the latest version of a package by running this command: @@ -483,7 +483,7 @@ nuget install <package_id> -OutputDirectory <output_directory> \ ### Install a package with the .NET CLI WARNING: -If you have a package in the Package Registry with the same name as a package at +If you have a package in the package registry with the same name as a package at a different source, verify the order in which `dotnet` checks sources during install. This is defined in the `nuget.config` file. @@ -503,7 +503,7 @@ dotnet add package <package_id> \ Prerequisites: -- The project-level Package Registry is a [v2 feed source](#add-a-source-with-chocolatey-cli) for Chocolatey. +- The project-level package registry is a [v2 feed source](#add-a-source-with-chocolatey-cli) for Chocolatey. - A version must be provided when installing or upgrading a package using NuGet v2 feed. To install a package with the Chocolatey CLI: @@ -515,7 +515,7 @@ choco install <package_id> -Source <source_url> -Version <package_version> In this command: - `<package_id>` is the package ID. -- `<source_url>` is the URL or name of the NuGet v2 feed Package Registry. +- `<source_url>` is the URL or name of the NuGet v2 feed package registry. - `<package_version>` is the package version. For example: @@ -537,7 +537,7 @@ choco upgrade <package_id> -Source <source_url> -Version <package_version> In this command: - `<package_id>` is the package ID. -- `<source_url>` is the URL or name of the NuGet v2 feed Package Registry. +- `<source_url>` is the URL or name of the NuGet v2 feed package registry. - `<package_version>` is the package version. For example: @@ -587,12 +587,51 @@ can also push them manually: nuget push My.Package.snupkg -Source <source_name> ``` -Consuming symbol packages is not yet guaranteed using clients such as Visual Studio or -dotnet-symbol. The `.snupkg` files are available for download through the UI or the -[API](../../../api/packages/nuget.md#download-a-package-file). +### Use the package registry as a symbol server + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7. + +GitLab can consume symbol files from the NuGet package registry, +so you can use the package registry as a symbol server. + +To use the symbol server: + +1. Enable the `nuget_symbol_server_enabled` namespace setting with the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings). +1. Configure your debugger to use the symbol server. + For example, to configure Visual Studio: + + 1. Open **Tools > Preferences**. + 1. Select **Debugger > Symbol sources**. + 1. Select **Add**. + 1. Fill in the required fields. The URL for the symbol server is: + + ```shell + https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/symbolfiles + -- or -- + https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/symbolfiles + ``` + + 1. Select **Add Source**. + +After you configure the debugger, you can debug your application as usual. +The debugger automatically downloads the symbol PDB files from the package registry as long as they're available. + +#### Consuming symbol packages + +When the debugger is configured to consume symbol packages, the debugger sends the following +in a request: + +- `Symbolchecksum` header: The SHA-256 checksum of the symbol file. +- `file_name` request parameter: The name of the symbol file. For example, `mypackage.pdb`. +- `signature` request parameter: The GUID and age of the PDB file. + +The GitLab server matches this information to a symbol file and returns it. + +Note that: -Follow the [NuGet symbol package issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) -for further updates. +- Only portable PDB files are supported. +- Because debuggers can't provide authentication tokens, the symbol server endpoint doesn't support the usual authentication methods. + The GitLab server requires the `signature` and `Symbolchecksum` to return the correct symbol file. ## Supported CLI commands diff --git a/doc/user/packages/package_registry/dependency_proxy/index.md b/doc/user/packages/package_registry/dependency_proxy/index.md new file mode 100644 index 00000000000..7b5e7a4c624 --- /dev/null +++ b/doc/user/packages/package_registry/dependency_proxy/index.md @@ -0,0 +1,293 @@ +--- +stage: Package +group: Package Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Dependency proxy for packages **(PREMIUM ALL BETA)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3610) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. Disabled by default. +> - This feature is in [Beta](../../../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +The GitLab dependency proxy for packages is a local proxy for frequently pulled packages. +It is implemented as a pull-through cache that works at the project level. + +Packages are pulled from the upstream package registry and automatically published to the +project's package registry. Subsequent identical requests are fulfilled with the project's +package registry. You can use the dependency proxy for packages to reduce unnecessary traffic +to the upstream registry. + +## Enable the dependency proxy + +To use the dependency proxy for packages, ensure your project is configured properly, +and that users who pull from the cache have the necessary authentication: + +1. In the global configuration, if the following features are disabled, enable them: + - The [`package` feature](../../../../administration/packages/index.md#enable-or-disable-the-package-registry). Enabled by default. + - The [`dependency_proxy` feature](../../../../administration/packages/dependency_proxy.md#turn-on-the-dependency-proxy). Enabled by default. +1. In the project settings, if the [`package` feature](../../package_registry/index.md#disable-the-package-registry) + is disabled, enable it. It is enabled by default. +1. [Add an authentication method](#configure-a-client). The dependency proxy supports the same [authentication methods](../index.md#authenticate-with-the-registry) as the package registry: + - [Personal access token](../../../profile/personal_access_tokens.md) + - [Project deploy token](../../../project/deploy_tokens/index.md) + - [Group deploy token](../../../project/deploy_tokens/index.md) + - [Job token](../../../../ci/jobs/ci_job_token.md) + +## Advanced caching + +When possible, the dependency proxy for packages uses advanced caching to store packages in the project's package registry. + +Advanced caching verifies the coherence between the project's package registry +and the upstream package registry. If the upstream registry has updated files, +the dependency proxy uses them to update the cached files. + +When advanced caching is not supported, the dependency proxy falls back to the default behavior: + +- If the requested file is found in the project's package registry, it is returned. +- If the file is not found, it is fetched from the upstream package registry. + +Advanced caching support depends on how the upstream package registry +responds to dependency proxy requests, and on +which package format you use. + +::Tabs + +:::TabTitle Maven + +| Package registry | Advanced caching supported? | +|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| [GitLab](../../maven_repository/index.md) | **{check-circle}** Yes | +| [Maven Central](https://mvnrepository.com/repos/central) | **{check-circle}** Yes | +| [Artifactory](https://jfrog.com/integration/maven-repository/) | **{check-circle}** Yes | +| [Sonatype Nexus](https://help.sonatype.com/repomanager3/nexus-repository-administration/formats/maven-repositories) | **{check-circle}** Yes | +| [GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) | **{dotted-circle}** No | + +::EndTabs + +### Permissions + +When the dependency proxy pulls a file, the following occurs: + +1. The dependency proxy searches for a file in the project's package registry. + This is a read operation. +1. The dependency proxy might publish a package file to the project's package registry. + This is a write operation. + +Whether both steps are executed depends on user permissions. +The dependency proxy uses the [same permissions as the package registry](../index.md#package-registry-visibility-permissions). + +| Project visibility | Minimum [role](../../../../user/permissions.md#roles) | Can read package files? | Can write package files? | Behavior | +|--------------------|-------------------------------------------------------|-------------------------|--------------------------|----------| +| Public | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected. | +| Public | Guest | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. | +| Public | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. | +| Internal | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected | +| Internal | Guest | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. | +| Internal | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. | +| Private | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected | +| Private | Reporter | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. | +| Internal | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. | + +At a minimum, any user who can use the dependency proxy can also use the project's package registry. + +To ensure the cache is properly filled over time, you should make sure a user with at least the Developer role pulls packages with the dependency proxy. + +## Configure a client + +Configuring a client for the dependency proxy is similar to configuring a client for the [package registry](../supported_functionality.md#pulling-packages). + +### For Maven packages + +For Maven packages, [all clients supported by the package registry](../../maven_repository/index.md) are supported by the dependency proxy: + +- `mvn` +- `gradle` +- `sbt` + +For authentication, the Maven dependency proxy access all authentication methods accepted by the [Maven package registry](../../maven_repository/index.md#edit-the-client-configuration). +You should use the [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication) method as it is less complex. + +To configure the client: + +1. Follow the instructions in [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication). + + Make sure you use the endpoint URL `https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven`. + +1. Complete the configuration for your client: + +::Tabs + +:::TabTitle mvn + +In the `pom.xml` file add a `repository` element: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven</url> + </repository> +</repositories> +``` + +Where: + +- `<project_id>` is the ID of the project to be used as a dependency proxy. +- `<id>` contains the name of the `<server>` used in the [authentication configuration](../../maven_repository/index.md#basic-http-authentication). + +By default, Maven Central is checked first through the [Super POM](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Super_POM). +However, you might want to force `mvn` to check the GitLab endpoint first. To do this, follow the instructions from the [request forward](../../maven_repository/index.md#additional-configuration-for-mvn). + +:::TabTitle gradle + +Add a `repositories` section to your [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) file. + +- In Groovy DSL: + + ```groovy + repositories { + maven { + url "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven" + name "GitLab" + credentials(PasswordCredentials) { + username = 'REPLACE_WITH_NAME' + password = gitLabPrivateToken + } + authentication { + basic(BasicAuthentication) + } + } + } + ``` + +- In Kotlin DSL: + + ```kotlin + repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven") + name = "GitLab" + credentials(BasicAuthentication::class) { + username = "REPLACE_WITH_NAME" + password = findProperty("gitLabPrivateToken") as String? + } + authentication { + create("basic", BasicAuthentication::class) + } + } + } + ``` + +In this example: + +- `<project_id>` is the ID of the project to be used as a dependency proxy. +- `REPLACE_WITH_NAME` is explained in the [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication) section. + +:::TabTitle sbt + +In your [`build.sbt`](https://www.scala-sbt.org/1.x/docs/Directories.html#sbt+build+definition+files), add the following lines: + +```scala +resolvers += ("gitlab" at "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven") + +credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>") +``` + +In this example: + +- `<project_id>` is the ID of the project to be used as a dependency proxy. +- `<host>` is the host present in the `<endpoint url>` without the protocol scheme or the port. Example: `gitlab.example.com`. +- `<name>` and `<token>` are explained in the [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication) section. + +::EndTabs + +## Configure the remote registry + +The dependency proxy must be configured with: + +- The URL of the remote package registry. +- Optional. The required credentials. + +To set those parameters: + +1. Use the related [GraphQL mutation](../../../../api/graphql/reference/index.md#mutationupdatedependencyproxypackagessettings). + + A frontend to display and manage these settings is proposed by [issue 410726](https://gitlab.com/gitlab-org/gitlab/-/issues/410726). + +1. Complete the configuration for your package format: + +::Tabs + +:::TabTitle Maven + +Any Maven package registry can be connected to the dependency proxy. You can +authorize the connection with the Maven package registry username and password. + +To set or update the remote Maven package registry, update the following fields on the settings object: + +- `mavenExternalRegistryUrl` - The URL of the remote registry. +- `mavenExternalRegistryUsername` - Optional. The username to use with the remote registry. +- `mavenExternalRegistryPassword` - Optional. The password to use with the remote registry. + +Example of the GraphQL mutation: + +```graphql +mutation { + updateDependencyProxyPackagesSettings(input: { projectPath : <project full path>, enabled: true, mavenExternalRegistryUrl: <remote registry url>, mavenExternalRegistryUsername: <username>, mavenExternalRegistryPassword: <password> }) { + dependencyProxyPackagesSetting { + enabled + mavenExternalRegistryUrl + mavenExternalRegistryUsername + } + errors + } +} +``` + +::EndTabs + +## Troubleshooting + +### Manual file pull errors + +You can pull files manually with cURL. +However, you might encounter one of the following responses: + +- `404 Not Found` - The dependency proxy setting object was not found because it doesn't exist, or because the [requirements](#enable-the-dependency-proxy) were not fulfilled. +- `401 Unauthorized` - The user was properly authenticated but did not have the proper permissions to access the dependency proxy object. +- `403 Forbidden` - There was an issue with the [GitLab license level](#enable-the-dependency-proxy). +- `502 Bad Gateway` - The remote package registry could not fulfill the file request. Verify the [dependency proxy settings](#configure-the-remote-registry). +- `504 Gateway Timeout` - The remote package registry timed out. Verify the [dependency proxy settings](#configure-the-remote-registry). + +::Tabs + +:::TabTitle Maven + +```shell +curl --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/<group id and artifact id>/<version>/<file_name>" +``` + +- `<username>` and `<personal access token>` are the credentials to access the dependency proxy of the GitLab instance. +- `<project_id>` is the project ID. +- `<group id and artifact id>` are the [Maven package group ID and artifact ID](https://maven.apache.org/pom.html#Maven_Coordinates) joined with a forward slash. +- `<version>` is the package version. +- `file_name` is the exact name of the file. + +For example, given a package with: + +- group ID: `com.my_company`. +- artifact ID: `my_package`. +- version: `1.2.3`. + +The request to manually pull a package is: + +```shell +curl --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/com/my_company/my_package/1.2.3/my_package-1.2.3.pom" +``` + +::EndTabs diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index e9c019deefa..6a4e7c0d6a5 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -1,20 +1,20 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Package Registry **(FREE ALL)** +# Package registry **(FREE ALL)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. -With the GitLab Package Registry, you can use GitLab as a private or public registry for a variety +With the GitLab package registry, you can use GitLab as a private or public registry for a variety of [supported package managers](supported_package_managers.md). You can publish and share packages, which can be consumed as a dependency in downstream projects. ## Package workflows -Learn how to use the GitLab Package Registry to build your own custom package workflow: +Learn how to use the GitLab package registry to build your own custom package workflow: - [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. @@ -43,11 +43,6 @@ For information on how to create and upload a package, view the GitLab documenta ## Authenticate with the registry -<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> -WARNING: -In GitLab 16.0 and later, [external authorization](../../admin_area/settings/external_authorization.md) prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. -<!--- end_remove --> - Authentication depends on the package manager being used. For more information, see the docs on the specific package format you want to use. @@ -83,7 +78,7 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -For more information about using the GitLab Package Registry with CI/CD, see: +For more information about using the GitLab package registry with CI/CD, see: - [Composer](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) - [Conan](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) @@ -110,18 +105,18 @@ For a list of supported packages, see [Importing packages from other repositorie ## Reduce storage usage -For information on reducing your storage use for the Package Registry, see -[Reduce Package Registry storage use](reduce_package_registry_storage.md). +For information on reducing your storage use for the package registry, see +[Reduce package registry storage use](reduce_package_registry_storage.md). -## Disable the Package Registry +## Disable the package registry -The Package Registry is automatically enabled. +The package registry is automatically enabled. If you are using a self-managed instance of GitLab, your administrator can remove the menu item, **Packages and registries**, from the GitLab sidebar. For more information, see the [administration documentation](../../../administration/packages/index.md). -You can also remove the Package Registry for your project specifically: +You can also remove the package registry for your project specifically: 1. In your project, go to **Settings > General**. 1. Expand the **Visibility, project features, permissions** section and disable the @@ -130,45 +125,45 @@ You can also remove the Package Registry for your project specifically: The **Deploy > Package Registry** entry is removed from the sidebar. -## Package Registry visibility permissions +## Package registry visibility permissions [Project-level permissions](../../permissions.md) determine actions such as downloading, pushing, or deleting packages. -The visibility of the Package Registry is independent of the repository and can be controlled from +The visibility of the package registry is independent of the repository and can be controlled from your project's settings. For example, if you have a public project and set the repository visibility -to **Only Project Members**, the Package Registry is then public. Disabling the Package -Registry disables all Package Registry operations. +to **Only Project Members**, the package registry is then public. Disabling the Package +Registry disables all package registry operations. | Project visibility | Action | Minimum [role](../../permissions.md#roles) required | |--------------------|-----------------------|---------------------------------------------------------| -| Public | View Package Registry | `n/a`, everyone on the internet can perform this action | +| Public | View package registry | `n/a`, everyone on the internet can perform this action | | Public | Publish a package | Developer | | Public | Pull a package | `n/a`, everyone on the internet can perform this action | -| Internal | View Package Registry | Guest | +| Internal | View package registry | Guest | | Internal | Publish a package | Developer | | Internal | Pull a package | Guest (1) | -| Private | View Package Registry | Reporter | +| Private | View package registry | Reporter | | Private | Publish a package | Developer | | Private | Pull a package | Reporter (1) | -### Allow anyone to pull from Package Registry +### Allow anyone to pull from package registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385994) in GitLab 15.7. -To allow anyone to pull from the Package Registry, regardless of project visibility: +To allow anyone to pull from the package registry, regardless of project visibility: 1. On the left sidebar, select **Search or go to** and find your private or internal project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Turn on the **Allow anyone to pull from Package Registry** toggle. 1. Select **Save changes**. -Anyone on the internet can access the Package Registry for the project. +Anyone on the internet can access the package registry for the project. #### Disable allowing anyone to pull -Prerequisite: +Prerequisites: - You must be an administrator. @@ -178,7 +173,7 @@ To hide the **Allow anyone to pull from Package Registry** toggle globally: Anonymous downloads are disabled, even for projects that turned on the **Allow anyone to pull from Package Registry** toggle. -Several known issues exist when you allow anyone to pull from the Package Registry: +Several known issues exist when you allow anyone to pull from the package registry: - Project-level endpoints are supported. Group-level and instance-level endpoints are not supported. Support for group-level endpoints is proposed in [issue 383537](https://gitlab.com/gitlab-org/gitlab/-/issues/383537). - It does not work with the [Composer](../composer_repository/index.md#install-a-composer-package), because Composer only has a group endpoint. diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index e6251034cb2..c1d3d7d0937 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Reduce Package Registry Storage **(FREE ALL)** +# Reduce package registry storage **(FREE ALL)** Without cleanup, package registries become large over time. When a large number of packages and their assets are added: @@ -14,13 +14,13 @@ their assets are added: We recommend deleting unnecessary packages and assets. This page offers examples of how to do so. -## Check Package Registry Storage Use +## Check package registry storage use The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. ## Delete a package -You cannot edit a package after you publish it in the Package Registry. Instead, you +You cannot edit a package after you publish it in the package registry. Instead, you must delete and recreate it. To delete a package, you must have suitable [permissions](../../permissions.md). diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index eb6b415ee06..4b10e703127 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -1,12 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported package functionality -The GitLab Package Registry supports different functionalities for each package type. This support includes publishing +The GitLab package registry supports different functionalities for each package type. This support includes publishing and pulling packages, request forwarding, managing duplicates, and authentication. ## Publishing packages **(FREE ALL)** @@ -133,7 +133,7 @@ By default, the GitLab package registry either allows or prevents duplicates bas ## Authentication tokens **(FREE ALL)** -GitLab tokens are used to authenticate with the GitLab Package Registry. +GitLab tokens are used to authenticate with the GitLab package registry. The following tokens are supported: @@ -181,7 +181,7 @@ The following authentication protocols are supported: Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). -The Package Registry supports the following hash types: +The package registry supports the following hash types: | Package type | Supported hashes | |-------------------------------------------------------|----------------------------------| diff --git a/doc/user/packages/package_registry/supported_package_managers.md b/doc/user/packages/package_registry/supported_package_managers.md index 8d31399a36b..aa56bed78aa 100644 --- a/doc/user/packages/package_registry/supported_package_managers.md +++ b/doc/user/packages/package_registry/supported_package_managers.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported package managers **(FREE ALL)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Not all package manager formats are ready for production use. -The Package Registry supports the following package manager types: +The package registry supports the following package manager types: | Package type | GitLab version | Status | | ------------------------------------------------ | -------------- | --------------------------------------------------------------- | @@ -27,4 +27,4 @@ The Package Registry supports the following package manager types: [View what each status means](../../../policy/experiment-beta-support.md). -You can also use the [API](../../../api/packages.md) to administer the Package Registry. +You can also use the [API](../../../api/packages.md) to administer the package registry. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index c196e414461..ccd47527855 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -1,18 +1,18 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# PyPI packages in the Package Registry **(FREE ALL)** +# PyPI packages in the package registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. -Publish PyPI packages in your project's Package Registry. Then install the +Publish PyPI packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. -The Package Registry works with: +The package registry works with: - [pip](https://pypi.org/project/pip/) - [twine](https://pypi.org/project/twine/) @@ -22,9 +22,9 @@ clients use, see the [PyPI API documentation](../../../api/packages/pypi.md). Learn how to [build a PyPI package](../workflows/build_packages.md#pypi). -## Authenticate with the Package Registry +## Authenticate with the package registry -Before you can publish to the Package Registry, you must authenticate. +Before you can publish to the package registry, you must authenticate. To do this, you can use: @@ -119,9 +119,10 @@ https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi Prerequisites: -- You must [authenticate with the Package Registry](#authenticate-with-the-package-registry). +- You must [authenticate with the package registry](#authenticate-with-the-package-registry). - Your [version string must be valid](#ensure-your-version-string-is-valid). - The maximum allowed package size is 5 GB. +- The maximum length of the `description` field is 4000 characters. Longer `description` strings are truncated. - You can't upload the same version of a package multiple times. If you try, you receive the error `400 Bad Request`. - PyPI packages are published using your projectID. @@ -202,9 +203,9 @@ more than once, a `400 Bad Request` error occurs. ## Install a PyPI package In [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/233413), -when a PyPI package is not found in the Package Registry, the request is forwarded to [pypi.org](https://pypi.org/). +when a PyPI package is not found in the package registry, the request is forwarded to [pypi.org](https://pypi.org/). -Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). +Administrators can disable this behavior in the [Continuous Integration settings](../../../administration/settings/continuous_integration.md). WARNING: When you use the `--index-url` option, do not specify the port if it is a default diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 361114e6f9e..f9017d9b5a7 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Ruby gems in the Package Registry **(FREE ALL EXPERIMENT)** +# Ruby gems in the package registry **(FREE ALL EXPERIMENT)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in GitLab 13.10. @@ -13,9 +13,9 @@ The Ruby gems package registry for GitLab is under development and isn't ready f limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/3200) details the remaining work and timelines to make it production ready. -You can publish Ruby gems in your project's Package Registry, then install the packages when you +You can publish Ruby gems in your project's package registry, then install the packages when you need to use them as a dependency. Although you can push gems to the registry, you cannot install -them from the registry. However, you can download `gem` files directly from the Package Registry's +them from the registry. However, you can download `gem` files directly from the package registry's UI, or by using the [API](../../../api/packages/rubygems.md#download-a-gem-file). For documentation of the specific API endpoints that the Ruby gems and Bundler package manager @@ -49,9 +49,9 @@ Feature.disable(:rubygem_packages, Project.find(2)) If you need help creating a Ruby gem, see the [RubyGems documentation](https://guides.rubygems.org/make-your-own-gem/). -## Authenticate to the Package Registry +## Authenticate to the package registry -Before you can push to the Package Registry, you must authenticate. +Before you can push to the package registry, you must authenticate. To do this, you can use: @@ -108,7 +108,7 @@ https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/rubygem Prerequisites: -- You must [authenticate to the Package Registry](#authenticate-to-the-package-registry). +- You must [authenticate to the package registry](#authenticate-to-the-package-registry). - The maximum allowed gem size is 3 GB. To push your gem, run a command like this one: diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 5c4105f8e00..2c9576bf9f7 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform Module Registry **(FREE ALL)** @@ -34,6 +34,7 @@ To authenticate to the Terraform Module Registry, you need either: - A [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). +- A [deploy token](../../project/deploy_tokens/index.md) with the `read_package_registry` or `write_package_registry` scope, or both. Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md index a0757e968bc..59508b3e9e2 100644 --- a/doc/user/packages/workflows/build_packages.md +++ b/doc/user/packages/workflows/build_packages.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Build packages @@ -51,7 +51,7 @@ Learn how to install and build packages different package formats. ### Install Conan -Prerequisite: +Prerequisites: - You must install Conan version 1.x. Support for Conan version 2 is proposed in [epic 8258](https://gitlab.com/groups/gitlab-org/-/epics/8258). @@ -92,7 +92,7 @@ The CMake version is printed in the output. ### Create a project -To test the Package Registry, you need a C++ project. If you don't already have +To test the package registry, you need a C++ project. If you don't already have one, you can clone the Conan [hello world starter project](https://github.com/conan-io/hello). ### Build a Conan package @@ -505,4 +505,4 @@ The output should appear similar to the following: mypypipackage-0.0.1-py3-none-any.whl mypypipackage-0.0.1.tar.gz ``` -The package is now ready to be published to the Package Registry. +The package is now ready to be published to the package registry. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 4db77348bd4..d85988a0bd7 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -1,12 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Store all of your packages in one GitLab project **(FREE ALL)** -You can store all of your packages in one project's Package Registry. Rather than using +You can store all of your packages in one project's package registry. Rather than using a GitLab repository to store code, you can use the repository to store all your packages. Then you can configure your remote repositories to point to the project in GitLab. @@ -36,7 +36,7 @@ Let's take a look at how you might create one project to host all of your packag 1. Create a new project in GitLab. The project doesn't require any code or content. 1. On the left sidebar, select **Project overview**, and note the project ID. -1. Create an access token for authentication. All package types in the Package Registry can be published by using: +1. Create an access token for authentication. All package types in the package registry can be published by using: - A [personal access token](../../profile/personal_access_tokens.md). - A [CI/CD job token](../../../ci/jobs/ci_job_token.md) (`CI_JOB_TOKEN`) in a CI/CD job. @@ -56,7 +56,7 @@ If you're using npm, create an `.npmrc` file. Add the appropriate URL for publis packages to your project. Finally, add a section to your `package.json` file. Follow the instructions in the -[GitLab Package Registry npm documentation](../npm_registry/index.md#authentication-to-the-package-registry). After +[GitLab package registry npm documentation](../npm_registry/index.md#authentication-to-the-package-registry). After you do this, you can publish your npm package to your project using `npm publish`, as described in the [publishing packages](../npm_registry/index.md#publish-to-gitlab-package-registry) section. diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md index 1383cd6df27..11c8eab2513 100644 --- a/doc/user/packages/workflows/working_with_monorepos.md +++ b/doc/user/packages/workflows/working_with_monorepos.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monorepo package management workflows **(FREE ALL)** diff --git a/doc/user/packages/yarn_repository/index.md b/doc/user/packages/yarn_repository/index.md index 942e62ae3e7..99f456bc1cb 100644 --- a/doc/user/packages/yarn_repository/index.md +++ b/doc/user/packages/yarn_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Publish packages with Yarn @@ -17,11 +17,11 @@ You can use the Yarn documentation to get started with [Yarn Classic](https://classic.yarnpkg.com/en/docs/getting-started) and [Yarn 2+](https://yarnpkg.com/getting-started/). -## Publish to GitLab Package Registry +## Publish to GitLab package registry -You can use Yarn to publish to the GitLab Package Registry. +You can use Yarn to publish to the GitLab package registry. -### Authentication to the Package Registry +### Authentication to the package registry You need a token to publish a package. Different tokens are available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry). @@ -54,7 +54,7 @@ In this configuration: Scoped registry does not work in Yarn Classic in `package.json` file, based on this [issue](https://github.com/yarnpkg/yarn/pull/7829). Therefore, under `publishConfig` there should be `registry` and not `@scope:registry` for Yarn Classic. -You can publish using your command line or a CI/CD pipeline to the GitLab Package Registry. +You can publish using your command line or a CI/CD pipeline to the GitLab package registry. ### Publishing via the command line - Manual Publish @@ -66,7 +66,7 @@ yarn publish yarn npm publish ``` -Your package should now publish to the Package Registry. +Your package should now publish to the package registry. ### Publishing via a CI/CD pipeline - Automated Publish @@ -163,7 +163,7 @@ deploy: - yarn npm publish ``` -Your package should now publish to the Package Registry when the pipeline runs. +Your package should now publish to the package registry when the pipeline runs. ## Install a package @@ -191,7 +191,7 @@ You can use one of two API endpoints to install packages: If you plan to install a package through the [project level](#install-from-the-project-level), you do not have to adhere to the naming convention. -| Project URL | Package Registry | Organization Scope | Full package name | +| Project URL | Package registry | Organization Scope | Full package name | |-------------------------------------------------------------------|----------------------|--------------------|-----------------------------| | `https://gitlab.com/<my-org>/<group-name>/<package-name-example>` | Package Name Example | `@my-org` | `@my-org/package-name` | | `https://gitlab.com/<example-org>/<group-name>/<project-name>` | Project Name | `@example-org` | `@example-org/project-name` | @@ -301,7 +301,7 @@ Then you can use `yarn add` to install your packages. ## Troubleshooting -### Error running Yarn with the Package Registry for the npm registry +### Error running Yarn with the package registry for the npm registry If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get an error message like: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index ab26e490f51..8c15d696760 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Permissions and roles **(FREE ALL)** @@ -74,9 +74,9 @@ The following table lists project permissions available for each role: | [GitLab Agent for Kubernetes](clusters/agent/index.md):<br>View agents | | | ✓ | ✓ | ✓ | | [GitLab Agent for Kubernetes](clusters/agent/index.md):<br>Manage agents | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/delete_container_registry_images.md#use-a-cleanup-policy) | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (19) | ✓ (19) | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| [Container registry](packages/container_registry/index.md):<br>Push an image to the container registry | | | ✓ | ✓ | ✓ | +| [Container registry](packages/container_registry/index.md):<br>Pull an image from the container registry | ✓ (19) | ✓ (19) | ✓ | ✓ | ✓ | +| [Container registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/pages_access_control.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | @@ -121,8 +121,9 @@ The following table lists project permissions available for each role: | [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | | [License approval policies](../user/compliance/license_approval_policies.md):<br>Manage license policy | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>View a merge request | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>View list | (25) | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Approve (8) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | @@ -133,6 +134,12 @@ The following table lists project permissions available for each role: | [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](project/merge_requests/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Objectives and key results](okrs.md):<br>Add a child OKR | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Add a linked item | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>View | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Change confidentiality | | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Edit | | ✓ | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Pull a package | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | @@ -208,6 +215,7 @@ The following table lists project permissions available for each role: | [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | +| [Tasks](tasks.md):<br>Add a linked item | ✓ | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Create (17) | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Edit | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Remove from issue | | ✓ | ✓ | ✓ | ✓ | @@ -244,12 +252,13 @@ The following table lists project permissions available for each role: 16. In projects that accept contributions from external members, users can create, edit, and close their own merge requests. 17. Authors and assignees can modify the title and description even if they don't have the Reporter role. 18. Authors and assignees can close and reopen issues even if they don't have the Reporter role. -19. The ability to view the Container Registry and pull images is controlled by the [Container Registry's visibility permissions](packages/container_registry/index.md#container-registry-visibility-permissions). +19. The ability to view the container registry and pull images is controlled by the [container registry's visibility permissions](packages/container_registry/index.md#container-registry-visibility-permissions). 20. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. 21. Authors of tasks can delete them even if they don't have the Owner role, but they have to have at least the Guest role for the project. 22. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic). -23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a [custom role](custom_roles.md) through the API and assign that role to the users. +23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed or GitLab Dedicated) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a [custom role](custom_roles.md) through the API or UI and assign that role to the users. 24. In GitLab 16.4 the ability for `Developers` to change the status of a vulnerability (`admin_vulnerability`) was [deprecated](../update/deprecations.md#deprecate-change-vulnerability-status-from-the-developer-role). The `admin_vulnerability` permission will be removed, by default, from all `Developer` roles in GitLab 17.0. +25. Members with the Guest role can view the list of MRs in public projects. Private projects restrict Guests from viewing MR lists. <!-- markdownlint-enable MD029 --> @@ -268,26 +277,27 @@ More details about the permissions for some project-level features follow. | Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | |---------------------------------------------------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| -| See that artifacts exist | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | -| View a list of jobs | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View and download artifacts | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View [environments](../ci/environments/index.md) | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | -| View job logs and job details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View pipelines and pipeline details pages | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View pipelines tab in MR | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | -| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| See that artifacts exist | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View a list of jobs | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View and download artifacts | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View [environments](../ci/environments/index.md) | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View job logs and job details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines and pipeline details pages | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines tab in MR | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (2) | ✓ | ✓ | ✓ | ✓ | | View and download project-level [Secure Files](../api/secure_files.md) | | | | ✓ | ✓ | ✓ | -| Cancel and retry jobs | | | | ✓ | ✓ | ✓ | +| Retry jobs | | | | ✓ | ✓ | ✓ | +| Cancel jobs | | | | ✓ (7) | ✓ (7) | ✓ (7) | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| Delete job logs or job artifacts | | | | ✓ (4) | ✓ | ✓ | +| Delete job logs or job artifacts | | | | ✓ (4) | ✓ | ✓ | | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | -| Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | +| Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| Run deployment job for a protected environment | | | ✓ (5) | ✓ (6) | ✓ (6) | ✓ | +| Run deployment job for a protected environment | | | ✓ (5) | ✓ (6) | ✓ (6) | ✓ | | View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | -| Add project runners to project | | | | | ✓ | ✓ | +| Add project runners to project | | | | | ✓ | ✓ | | Clear runner caches manually | | | | | ✓ | ✓ | | Enable shared runners in project | | | | | ✓ | ✓ | | Manage CI/CD settings | | | | | ✓ | ✓ | @@ -308,6 +318,7 @@ More details about the permissions for some project-level features follow. run for a non-protected branch. 5. If the user is [allowed to merge or push to the protected branch](../ci/pipelines/index.md#pipeline-security-on-protected-branches). 6. If the user if [part of a group with at least the Reporter role](../ci/environments/protected_environments.md#deployment-only-access-to-protected-environments) +7. Cancellation permissions can be [customized via the pipeline settings](../ci/pipelines/settings.md#restrict-roles-that-can-cancel-pipelines-or-jobs) <!-- markdownlint-enable MD029 --> @@ -363,8 +374,8 @@ The following table lists group permissions available for each role: | Delete [packages](packages/index.md) | | | | ✓ | ✓ | | Create/edit/delete [Maven and generic package duplicate settings](packages/generic_packages/index.md#do-not-allow-duplicate-generic-packages) | | | | ✓ | ✓ | | Enable/disable package request forwarding | | | | ✓ | ✓ | -| Pull a Container Registry image | ✓ (6) | ✓ | ✓ | ✓ | ✓ | -| Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| Pull a container registry image | ✓ (6) | ✓ | ✓ | ✓ | ✓ | +| Remove a container registry image | | | ✓ | ✓ | ✓ | | View [Group DevOps Adoption](group/devops_adoption/index.md) | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | View [Productivity analytics](analytics/productivity_analytics.md) | | ✓ | ✓ | ✓ | ✓ | @@ -404,6 +415,7 @@ The following table lists group permissions available for each role: | Manage group runners | | | | | ✓ | | [Migrate groups](group/import/index.md) | | | | | ✓ | | Manage [subscriptions, and purchase storage and compute minutes](../subscriptions/gitlab_com/index.md) | | | | | ✓ | +| Manage group-level custom roles | | | | | ✓ | <!-- markdownlint-disable MD029 --> @@ -436,8 +448,8 @@ For more information, see Users with the Minimal Access role do not: -- Count as licensed seats on self-managed Ultimate subscriptions or any GitLab.com subscriptions. - Automatically have access to projects and subgroups in that root group. +- Count as licensed seats on self-managed Ultimate subscriptions or any GitLab.com subscriptions, provided the user has no other role anywhere in the instance or in the GitLab SaaS namespace. Owners must explicitly add these users to the specific subgroups and projects. @@ -465,6 +477,6 @@ To work around the issue, give these users the Guest role or higher to any proje - [Project aliases](../user/project/import/index.md#project-aliases) - [Auditor users](../administration/auditor_users.md) - [Confidential issues](project/issues/confidential_issues.md) -- [Container Registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) +- [Container registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) - [Release permissions](project/releases/index.md#release-permissions) - [Read-only namespaces](../user/read_only_namespaces.md) diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 94217f985cf..75e44471f92 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Product analytics **(ULTIMATE ALL EXPERIMENT)** @@ -19,12 +19,11 @@ On GitLab.com, this feature is not available. This feature is not ready for production use. This page is a work in progress, and we're updating the information as we add more features. -For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). +For more information, see the [group direction page](https://about.gitlab.com/direction/monitor/product-analytics/). To leave feedback about Product Analytics bugs or functionality: - Comment on [issue 391970](https://gitlab.com/gitlab-org/gitlab/-/issues/391970). - Create an issue with the `group::product analytics` label. -- [Schedule a call](https://calendly.com/jheimbuck/30-minute-call) with the team. ## How product analytics works @@ -32,7 +31,7 @@ Product analytics uses several tools: - [**Snowplow**](https://docs.snowplow.io/docs) - A developer-first engine for collecting behavioral data, and passing it through to ClickHouse. - [**ClickHouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. -- [**Cube**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in ClickHouse. +- [**Cube**](https://cube.dev/docs/) - A universal semantic layer that provides an API to run queries against the data stored in ClickHouse. The following diagram illustrates the product analytics flow: @@ -74,12 +73,11 @@ This feature is not ready for production use. To track events in your project applications on a self-managed instance, you must enable and configure product analytics. -Prerequisite: +Prerequisites: - You must be an administrator of a self-managed GitLab instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Analytics** tab and find the **Product analytics** section. 1. Select **Enable product analytics** and enter the configuration values. @@ -224,7 +222,7 @@ You can [query the funnel data with the REST API](../../api/product_analytics.md To do this, you can use the example query body below, where you need to replace `FUNNEL_NAME` with your funnel's name. NOTE: -The `afterDate` filter is not supported. Please use `beforeDate` or `inDateRange`. +The `afterDate` filter is not supported. Use `beforeDate` or `inDateRange`. ```json { @@ -299,12 +297,8 @@ If the request is successful, the returned JSON includes an array of rows of res ## View product analytics usage quota -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424153) in GitLab 16.6 with a [flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424153) in GitLab 16.6 with a [flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427838) in GitLab 16.7. Feature flag `product_analytics_usage_quota` removed. Product analytics usage quota is calculated from the number of events received from instrumented applications. The tab displays the monthly totals for the group, and a breakdown of usage per project. Current month shows events counted to date. diff --git a/doc/user/product_analytics/instrumentation/browser_sdk.md b/doc/user/product_analytics/instrumentation/browser_sdk.md index f2beafab8e0..6bc9a9ef234 100644 --- a/doc/user/product_analytics/instrumentation/browser_sdk.md +++ b/doc/user/product_analytics/instrumentation/browser_sdk.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Browser SDK @@ -83,7 +83,7 @@ interface GitLabClientSDKOptions { | :---------------------------- | :---------- | | `appId` | The ID provided by the GitLab Project Analytics setup guide. This ID ensures your data is sent to your analytics instance. | | `host` | The GitLab Project Analytics instance provided by the setup guide. | -| `hasCookieConsent` | Whether to use cookies to identify unique users and record their full IP address. Set to `false` by default. When `false`, users are considered anonymous users. No cookies or other storage mechanisms are used to identify users. | +| `hasCookieConsent` | Whether to use cookies to identify unique users. Set to `false` by default. When `false`, users are considered anonymous users. No cookies or other storage mechanisms are used to identify users. | | `respectGlobalPrivacyControl` | Whether to respect the user's [GPC](https://globalprivacycontrol.org/) configuration to permit or refuse tracking. Set to `true` by default. When `false`, events are emitted regardless of user configuration. | | `trackerId` | Used to differentiate between multiple trackers running on the same page or application, because each tracker instance can be configured differently to capture different sets of data. This identifier helps ensure that the data sent to the collector is correctly associated with the correct tracker configuration. Default value is `gitlab`. | | `pagePingTracking` | Option to track user engagement on your website or application by sending periodic events while a user is actively browsing a page. Page pings provide valuable insight into how users interact with your content, such as how long they spend on a page, which sections they are viewing, and whether they are scrolling. `pagePingTracking` can be boolean or an object. As a boolean, set to `true` it enables page ping with default options, and set to `false` it disables page ping tracking. As an object, it has two options: `minimumVisitLength` (the minimum time that must have elapsed before the first heartbeat) and `heartbeatDelay` (the interval at which the callback is fired). | diff --git a/doc/user/product_analytics/instrumentation/index.md b/doc/user/product_analytics/instrumentation/index.md index f909a01ff59..da30563eede 100644 --- a/doc/user/product_analytics/instrumentation/index.md +++ b/doc/user/product_analytics/instrumentation/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instrumentation diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 2166b40b575..6c78152fa70 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Creating users **(FREE SELF)** @@ -16,9 +15,9 @@ You can create users: ## Create users on sign-in page -Prerequisite: +Prerequisites: -- [Sign-up must be enabled](../../admin_area/settings/sign_up_restrictions.md). +- [Sign-up must be enabled](../../../administration/settings/sign_up_restrictions.md). Users can create their own accounts by either: @@ -27,14 +26,13 @@ Users can create their own accounts by either: ## Create users in Admin Area -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To create a user manually: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select **New user**. 1. Complete the required fields, such as name, username, and email. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 70c12cbcf00..a3df0aa5460 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,8 +1,7 @@ --- -type: howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deleting a user account **(FREE ALL)** @@ -36,8 +35,7 @@ On GitLab.com, there is a seven day delay between a user deleting their own acco As an administrator, to delete a user account: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index d26f2193124..376fde66cf0 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Two-factor authentication **(FREE ALL)** @@ -521,7 +521,7 @@ Instead you can authenticate: - Using a [personal access token](../personal_access_tokens.md) (PAT): - For Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. - - For [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT + - For [GitLab container registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT with `read_registry` or `write_registry` scope is required. - For [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with `read_registry` and `write_registry` scopes is required. diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md index c208bd554bf..0f03868de95 100644 --- a/doc/user/profile/achievements.md +++ b/doc/user/profile/achievements.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Achievements **(FREE ALL EXPERIMENT)** diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 5e8eb80a1aa..658134be9ad 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Active sessions **(FREE ALL)** diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md index 98fabdb0a35..126f0e1dc8c 100644 --- a/doc/user/profile/comment_templates.md +++ b/doc/user/profile/comment_templates.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Comment templates **(FREE ALL)** diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index 37b2c1a26e6..ec1bb3f7771 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Contributions calendar **(FREE ALL)** diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 64fa5d7b448..81e2f3d7a55 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,8 +1,7 @@ --- -type: index, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User account **(FREE ALL)** @@ -127,14 +126,15 @@ GitLab displays the contents of your README below your contribution graph. ### From an existing project To add the README from an existing project to your profile, -[update the path](../project/settings/index.md#rename-a-repository) of the project +[update the path](../project/working_with_projects.md#rename-a-repository) of the project to match your username. ## Add external accounts to your user profile page -> Mastodon user account [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132892) in 16.6 [with a flag](../feature_flags.md) named `mastodon_social_ui`. Disabled by default. This feature is in [Beta](../../policy/experiment-beta-support.md#beta). +> - Mastodon user account [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132892) in GitLab 16.6 [with a flag](../feature_flags.md) named `mastodon_social_ui`. Disabled by default. +> - Mastodon user account [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/428163) in GitLab 16.7. Feature flag `mastodon_social_ui` removed. -You can add links to certain other external accounts you might have, like Skype and Twitter. +You can add links to certain other external accounts you might have, like Skype and X (formerly Twitter). They can help other users connect with you on other platforms. To add links to other accounts: @@ -146,7 +146,7 @@ To add links to other accounts: - LinkedIn profile name. - Mastodon username. - Skype username. - - Twitter @username. + - X (formerly Twitter) @username. Your user ID or username must be 500 characters or less. 1. Select **Update profile settings**. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 8d34055d42c..c7b2de3ce7f 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Notification emails **(FREE ALL)** @@ -101,7 +101,7 @@ To select a notification level for a group, use either of these methods: 1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. +1. Locate the group in the **Groups** section. 1. Select the desired [notification level](#notification-levels). Or: @@ -120,7 +120,7 @@ You can use group notifications, for example, if you work freelance, and want to 1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. +1. Locate the group in the **Groups** section. 1. Select the desired email address. ### Change level of project notifications diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index a953a878cc9..9d54381ef87 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -1,8 +1,7 @@ --- -type: concepts, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Personal access tokens **(FREE ALL)** @@ -69,7 +68,7 @@ list of scopes. To do this, you can append a `name` parameter and a list of comm to the URL. For example: ```plaintext -https://gitlab.example.com/-/profile/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry +https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry ``` WARNING: @@ -83,7 +82,8 @@ At any time, you can revoke a personal access token. 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. -1. In the **Active personal access tokens** area, next to the key, select **Revoke**. +1. In the **Active personal access tokens** area, select **Revoke** for the relevant token. +1. On the confirmation dialog, select **Revoke**. ## View the last time a token was used @@ -100,7 +100,8 @@ To view the last time a token was used: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. -1. In the **Active personal access tokens** area, next to the key, view the **Last Used** date. +1. In the **Active personal access tokens** area, view the **Last Used** date for + the relevant token. ## Personal access token scopes @@ -110,23 +111,23 @@ To view the last time a token was used: A personal access token can perform actions based on the assigned scopes. -| Scope | Access | -|--------------------|--------| -| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | -| `read_user` | Grants read-only access to the authenticated user's profile through the `/user` API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under [`/users`](../../api/users.md). | -| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) in GitLab 12.10.) | -| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | -| `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | -| `read_registry` | Grants read-only (pull) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. | -| `write_registry` | Grants read-write (push) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | -| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. | -| `admin_mode` | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 15.8.) | -| `create_runner` | Grants permission to create runners. | -| `ai_features` | Grants permission to perform API actions for GitLab Duo. | -| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. | +| Scope | Access | +|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry. | +| `read_user` | Grants read-only access to the authenticated user's profile through the `/user` API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under [`/users`](../../api/users.md). | +| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) in GitLab 12.10.) | +| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | +| `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | +| `read_registry` | Grants read-only (pull) access to [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the container registry is enabled. | +| `write_registry` | Grants read-write (push) access to [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the container registry is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | +| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. | +| `admin_mode` | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 15.8.) | +| `create_runner` | Grants permission to create runners. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. | WARNING: -If you enabled [external authorization](../admin_area/settings/external_authorization.md), personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries. +If you enabled [external authorization](../../administration/settings/external_authorization.md), personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries. ## When personal access tokens expire @@ -141,33 +142,32 @@ Personal access tokens expire on the date you define, at midnight, 00:00 AM UTC. [maximum allowed lifetime for the token](../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens). If the maximum allowed lifetime is not set, the default expiry date is 365 days from the date of creation. -### Service Accounts +### Create a service account personal access token with no expiry date -You can [create a personal access token for a service account](../../api/groups.md#create-personal-access-token-for-service-account-user) with no expiry date. +You can [create a personal access token for a service account](../../api/groups.md#create-personal-access-token-for-service-account-user) with no expiry date. These personal access tokens never expire, unlike non-service account personal access tokens. NOTE: Allowing personal access tokens for service accounts to be created with no expiry date only affects tokens created after you change this setting. It does not affect existing tokens. #### GitLab.com -Prerequisite: +Prerequisites: - You must have the Owner role in the top-level group. 1. On the left sidebar, select **Search or go to** and find your group. -1. Select **Settings > Permissions and group features**. +1. Select **Settings > General > Permissions and group features**. 1. Clear the **Service account token expiration** checkbox. You can now create personal access tokens for a service account user with no expiry date. #### Self-managed GitLab -Prerequisite: +Prerequisites: - You must be an administrator for your self-managed instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Clear the **Service account token expiration** checkbox. @@ -179,7 +179,7 @@ You can now create personal access tokens for a service account user with no exp You can create a predetermined personal access token as part of your tests or automation. -Prerequisite: +Prerequisites: - You need sufficient access to run a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) @@ -219,7 +219,7 @@ sudo gitlab-rails runner "token = User.find_by_username('automation-bot').person You can programmatically revoke a personal access token as part of your tests or automation. -Prerequisite: +Prerequisites: - You need sufficient access to run a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) for your GitLab instance. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 34f083e0b48..6cc5f7c5039 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Profile preferences **(FREE ALL)** @@ -272,16 +271,20 @@ To use exact times on the GitLab UI: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15206) in GitLab 16.6. -You can customize the format used to display times of activities on your group and project overview pages and user profiles. You can display times as: +You can customize the format used to display times of activities on your group and project overview pages and user +profiles. You can display times as: - 12 hour format. For example: `2:34 PM`. - 24 hour format. For example: `14:34`. +You can also follow your system's setting. + To customize the time format: 1. On the left sidebar, select your avatar. -1. Select **Preferences** > **Time preferences**. -1. In **Time format**, select either the **12-hour** or **24-hour** option. +1. Select **Preferences**. +1. Go to the **Time preferences** section. +1. Under **Time format**, select either the **System**, **12-hour**, or **24-hour** option. 1. Select **Save changes**. ## User identities in CI job JSON web tokens @@ -315,13 +318,15 @@ To access your **Followers** and **Following** tabs: - On the left sidebar, select your avatar > select your name or username. - Select **Followers** or **Following**. -## Enable Code Suggestions +## Enable Code Suggestions **(FREE SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../policy/experiment-beta-support.md#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../policy/experiment-beta-support.md#beta). +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. -Code Suggestions are disabled by default at the user account level. +A percentage of users can use Code Suggestions without any additional configuration. -To update this setting: +If the following options are available to you, it means you are **not** part of the percentage of users +and you must manually enable Code Suggestions for your account: 1. On the left sidebar, select your avatar. 1. Select **Preferences**. @@ -329,7 +334,7 @@ To update this setting: 1. Select **Save changes**. NOTE: -If Code Suggestions are disabled [for any groups that you belong to](../../user/group/manage.md#enable-code-suggestions), then you cannot enable them for yourself. (Your setting has no effect.) +If Code Suggestions are disabled [for any groups that you belong to](../../user/group/manage.md#enable-code-suggestions-for-a-group), then you cannot enable them for yourself. (Your setting has no effect.) ## Integrate your GitLab instance with third-party services diff --git a/doc/user/profile/service_accounts.md b/doc/user/profile/service_accounts.md index 8fa0067f150..3833d844d46 100644 --- a/doc/user/profile/service_accounts.md +++ b/doc/user/profile/service_accounts.md @@ -1,8 +1,7 @@ --- -type: index, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service accounts **(PREMIUM ALL)** @@ -40,7 +39,7 @@ How you create an account differs depending on whether you are on GitLab.com or ### GitLab.com -Prerequisite: +Prerequisites: - You must have the Owner role in a top-level group. @@ -62,7 +61,7 @@ Prerequisite: ### Self-managed GitLab -Prerequisite: +Prerequisites: - You must be an administrator for your self-managed instance. diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index 1b4fbd5fa53..97fd1081e05 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User passwords **(FREE ALL)** diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 0bec72d64e8..c341d2cef3e 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: "Autocomplete characters in Markdown fields." --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 39c1d228d63..4848217c468 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Badges **(FREE ALL)** @@ -126,26 +126,6 @@ If you set an out of range value, GitLab automatically adjusts it to the default Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges). -### Add a badge to a project - -To add a new badge to a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Badges**. -1. Select **Add badge**. -1. Under **Link**, enter the URL that the badges should point to. -1. Under **Badge image URL**, enter the URL of the image that should be displayed. -1. Select **Add badge**. - -After adding a badge to a project, you can see the badge in the list below the form. - -### Edit or delete a project badge - -To edit a badge, select **Edit** (**{pencil}**). - -To delete a badge, select **Delete** (**{remove}**). - ### Example project badge: Pipeline Status A common project badge presents the GitLab CI pipeline status. @@ -177,26 +157,26 @@ If you need individual badges for each project, either: - Add the badge at the [project level](#project-badges). - Use [placeholders](#placeholders). -### Add a badge to a group +## View badges -To add a new badge to a group: +To view badges available in a project or group: -1. On the left sidebar, select **Search or go to** and find your group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > General**. 1. Expand **Badges**. -1. Under "Link", enter the URL that the badges should point to and under - "Badge image URL" the URL of the image that should be displayed. -1. Select **Add badge**. - -After adding a badge to a group, you can see it in the list below the form. -### Edit or delete a group badge +## Add a badge -To edit a badge, select **Edit** (**{pencil}**). +To add a new badge to a project or group: -To delete a badge, select **Delete** (**{remove}**). - -Badges associated with a group can be edited or deleted only at the [group level](#group-badges). +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Settings > General**. +1. Expand **Badges**. +1. Select **Add badge**. +1. In the **Name** text box, enter the name of your badge. +1. In the **Link** text box, enter the URL that the badges should point to. +1. In the **Badge image URL** text box, enter the URL of the image you want to display for the badge. +1. Select **Add badge**. ## View the URL of pipeline badges @@ -283,6 +263,31 @@ To add a new badge with a custom image to a group or project: To learn how to use custom images generated through a pipeline, see the documentation on [accessing the latest job artifacts by URL](../../ci/jobs/job_artifacts.md#from-a-url). +## Edit a badge + +To edit a badge in a project or group: + +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Settings > General**. +1. Expand **Badges**. +1. Next to the badge you want to edit, select **Edit** (**{pencil}**). +1. Edit the **Name**, **Link**, or **Badge image URL**. +1. Select **Save changes**. + +## Delete a badge + +To delete a badge in a project or group: + +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Settings > General**. +1. Expand **Badges**. +1. Next to the badge you want to delete, select **Delete** (**{remove}**). +1. On the confirmation dialog, select **Delete badge**. +1. Select **Save changes**. + +NOTE: +Badges associated with a group can be edited or deleted only at the [group level](#group-badges). + ## Placeholders Both the URL a badge points to and the image URL can contain placeholders, @@ -302,9 +307,3 @@ Placeholders allow badges to expose otherwise-private information, such as the default branch or commit SHA when the project is configured to have a private repository. This behavior is intentional, as badges are intended to be used publicly. Avoid using these placeholders if the information is sensitive. - -## Configure badges through the API - -You can also configure badges via the GitLab API. As in the settings, there is -a distinction between endpoints for badges at the -[project level](../../api/project_badges.md) and [group level](../../api/group_badges.md). diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index efa1fad92b8..fe425d7420e 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Canary deployments **(FREE ALL)** diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index 1f251565d3f..a15bd39f1b7 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Changelogs **(FREE ALL)** @@ -72,7 +71,7 @@ in the API documentation. Prerequisites: -- You have installed and configured the [GitLab CLI](../../integration/glab/index.md), +- You have installed and configured the [GitLab CLI](../../editor_extensions/gitlab_cli/index.md), version 1.30.0 or later. - Your repository's tag naming schema matches [the expected tag naming format](#customize-the-tag-format-when-extracting-versions). diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index d8b1b6fd413..831e37dcf3c 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect EKS clusters through cluster certificates (deprecated) **(FREE ALL)** @@ -248,8 +248,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Amazon EKS**. 1. Check **Enable Amazon EKS integration**. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 7e2c429c6bb..161a698a48c 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect existing clusters through cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index a087460d89e..96eff58c638 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect GKE clusters through cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index a3263109bb1..940561d70d0 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Add a cluster using cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 2b57fa964c0..74f3cb689ff 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 70c96280e48..e287a3b94bb 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 1126e5a7241..cb053c8ede8 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab-managed clusters (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 1a69b45b651..1b6fab8fa34 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 7763cb13cd7..4fb6ecb1336 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple clusters per project with cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 7f0fd954d97..7af3068c691 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runbooks **(FREE ALL)** diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 0df0ef977c0..a7f1aff9b02 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Code Intelligence **(FREE ALL)** @@ -41,7 +40,7 @@ code_navigation: lsif: dump.lsif ``` -The generated LSIF file size may be limited by +The generated LSIF file size might be limited by the [artifact application limits (`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact), default to 100 MB (configurable by an instance administrator). diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index 0fa9983e93b..292be3848c1 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Owners **(PREMIUM ALL)** @@ -420,6 +420,8 @@ A Code Owner approval rule is optional if any of these conditions are true: Code Owners [cannot inherit members from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). - [Code Owner approval on a protected branch](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. - The section is [marked as optional](#make-a-code-owners-section-optional). +- No eligible code owners are available to approve the merge request due to conflicts + with other [merge request approval settings](../merge_requests/approvals/settings.md#approval-settings). ### Approvals do not show diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md index c2fbbe88b6f..558ee8c3a7e 100644 --- a/doc/user/project/codeowners/reference.md +++ b/doc/user/project/codeowners/reference.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Owners syntax and error handling **(PREMIUM ALL)** diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 91a3d71642d..e1f6bcbf5cc 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy boards (deprecated) **(FREE ALL)** diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 73d3d97be4a..6c2d4763526 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy keys **(FREE ALL)** @@ -17,7 +17,7 @@ Depending on your needs, you might want to use a [deploy token](../deploy_tokens | Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | | Accessible resources | Git repository over SSH | Git repository over HTTP, package registry, and container registry. | -Deploy keys can't be used for Git operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. +Deploy keys can't be used for Git operations if [external authorization](../../../administration/settings/external_authorization.md) is enabled. ## Scope @@ -65,7 +65,7 @@ As with all sensitive information, you should ensure only those who need access For human interactions, use credentials tied to users such as Personal Access Tokens. To help detect a potential secret leak, you can use the -[Audit Event](../../../administration/audit_event_streaming/examples.md#example-payloads-for-ssh-events-with-deploy-key) feature. +[Audit Event](../../../administration/audit_event_streaming/examples.md#example-payloads-for-git-over-ssh-events-with-deploy-key) feature. ## View deploy keys @@ -111,8 +111,7 @@ Prerequisites: To create a public deploy key: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Deploy Keys**. 1. Select **New deploy key**. 1. Complete the fields. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 351762228fb..c53b557a9e0 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy tokens **(FREE ALL)** @@ -25,7 +25,7 @@ A deploy token is a pair of values: You can use a deploy token for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) to the following endpoints: -- GitLab Package Registry public API. +- GitLab package registry public API. - [Git commands](https://git-scm.com/docs/gitcredentials#_description). You can create deploy tokens at either the project or group level: @@ -37,8 +37,8 @@ By default, a deploy token does not expire. You can optionally set an expiry dat it. Expiry occurs at midnight UTC on that date. WARNING: -You cannot use new or existing deploy tokens for Git operations and Package Registry operations if -[external authorization](../../admin_area/settings/external_authorization.md) is enabled. +You cannot use new or existing deploy tokens for Git operations and package registry operations if +[external authorization](../../../administration/settings/external_authorization.md) is enabled. ## Scope @@ -79,7 +79,7 @@ name and token of the group deploy token. ### GitLab public API Deploy tokens can't be used with the GitLab public API. However, you can use deploy tokens with some -endpoints, such as those from the Package Registry. For more information, see +endpoints, such as those from the package registry. For more information, see [Authenticate with the registry](../../packages/package_registry/index.md#authenticate-with-the-registry). ## Create a deploy token diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 97b350c8692..db98688497a 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Description templates **(FREE ALL)** @@ -107,10 +107,10 @@ your merge request template with their values: ### Set instance-level description templates **(PREMIUM SELF)** You can set a description template at the **instance level** for issues -and merge requests by using an [instance template repository](../admin_area/settings/instance_template_repository.md). +and merge requests by using an [instance template repository](../../administration/settings/instance_template_repository.md). You can also use the instance template repository for file templates. -You might also be interested in [project templates](../admin_area/custom_project_templates.md) +You might also be interested in [project templates](../../administration/custom_project_templates.md) that you can use when creating a new project in the instance. ### Set group-level description templates **(PREMIUM ALL)** diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 783f5f3ee7c..48a09d99c21 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File Locking **(FREE ALL)** diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 5e67706708d..61e73fcce81 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Git attributes **(FREE ALL)** @@ -52,3 +51,72 @@ For more information, see [working-tree-encoding](https://git-scm.com/docs/gitat The `.gitattributes` file can be used to define which language to use when syntax highlighting files and diffs. For more information, see [Syntax highlighting](highlighting.md). + +## Custom merge drivers **(FREE SELF)** + +> Ability to configure custom merge drivers through GitLab introduced in GitLab 15.10. + +GitLab self-managed instance administrators can define [custom merge drivers](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver) +in a GitLab configuration file, then use the custom merge drivers in a Git `.gitattributes` file. Custom merge drivers are not supported on GitLab.com. + +You might configure a custom merge driver, for example, if there are certain +files that should be ignored during a merge such as build files and configuration files. + +### Configure a custom merge driver + +The following example illustrates how to define and use a custom merge driver in +GitLab. + +How to configure a custom merge driver depends on the type of installation. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`. +1. Add configuration similar to the following: + + ```ruby + gitaly['configuration'] = { + # ... + git: { + # ... + config: [ + # ... + { key: "merge.foo.driver", value: "true" }, + ], + }, + } + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `gitaly.toml`. +1. Add configuration similar to the following: + + ```toml + [[git.config]] + key = "merge.foo.driver" + value = "true" + ``` + +::EndTabs + +In this example, during a merge, Git uses the `driver` value as the command to execute. In +this case, because we are using [`true`](https://man7.org/linux/man-pages/man1/true.1.html) +with no arguments, it always returns a non-zero return code. This means that for +the files specified in `.gitattributes`, merges do nothing. + +To use your own merge driver, replace the value in `driver` to point to an +executable. For more details on how this command is invoked, see the Git +documentation on [custom merge drivers](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver). + +### Use `.gitattributes` to set files custom merge driver applies to + +In a `.gitattributes` file, you can set the paths of files you want to use with the custom merge driver. For example: + +```plaintext +config/* merge=foo +``` + +In this case, every file under the `config/` folder uses the custom merge driver called `foo` defined in the GitLab configuration. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index ba7d7d39e84..54f529302ae 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Syntax Highlighting **(FREE ALL)** diff --git a/doc/user/project/img/global_time_report_v16_5.png b/doc/user/project/img/global_time_report_v16_5.png Binary files differnew file mode 100644 index 00000000000..36feb9591ae --- /dev/null +++ b/doc/user/project/img/global_time_report_v16_5.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index bafcbbb9cbd..92c14347a15 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -1,17 +1,16 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import your project from Bitbucket Cloud to GitLab **(FREE ALL)** +# Import your project from Bitbucket Cloud **(FREE ALL)** -NOTE: -The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket -Server (aka Stash). If you are trying to import projects from Bitbucket Server, use -[the Bitbucket Server importer](bitbucket_server.md). +> - Parallel imports from Bitbucket Cloud [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412614) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `bitbucket_parallel_importer`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.6. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.7. Feature flag `bitbucket_parallel_importer` removed. -Import your projects from Bitbucket Cloud to GitLab with minimal effort. +Import your projects from Bitbucket Cloud to GitLab. The Bitbucket importer can import: @@ -23,6 +22,9 @@ The Bitbucket importer can import: - Pull request comments - Milestones - Wiki +- Labels +- Milestones +- LFS objects When importing: @@ -30,29 +32,46 @@ When importing: - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Prerequisites - -> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. - -- [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator - to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. -- [Bitbucket Cloud import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your - GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. -- At least the Maintainer role on the destination group to import to. - -## How it works +NOTE: +The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket +Server (aka Stash). If you are trying to import projects from Bitbucket Server, use +[the Bitbucket Server importer](bitbucket_server.md). -When issues/pull requests are being imported, the Bitbucket importer uses the Bitbucket nickname of +When issues, pull requests, and comments are imported, the Bitbucket importer uses the Bitbucket nickname of the author/assignee and tries to find the same Bitbucket identity in GitLab. If they don't match or the user is not found in the GitLab database, the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. +For pull requests: + +- If the source SHA does not exist in the repository, the importer attempts to set the source commit to the merge commit SHA. +- The merge request assignee is set to the author. Reviewers are set with usernames matching Bitbucket identities in GitLab. +- Approvals are not imported. +- Merge requests in GitLab can be either can be either `opened`, `closed` or `merged`. + +For issues: + +- A label is added corresponding to the type of issue on Bitbucket. Either `bug`, `enhancement`, `proposal` or `task`. +- If the issue on Bitbucket was one of `resolved`, `invalid`, `duplicate`, `wontfix`, or `closed`, the issue is closed on GitLab. + The importer creates any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository is imported under the user's namespace that started the import process. -## Requirements for user-mapped contributions +## Prerequisites + +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + +- [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator + to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. +- [Bitbucket Cloud import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your + GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. +- Pull requests in Bitbucket must have the same source and destination project and not be from a fork of a project. + Otherwise, the pull requests are imported as empty merge requests. + +### Requirements for user-mapped contributions For user contributions to be mapped, each user must complete the following before the project import: @@ -117,5 +136,5 @@ current Bitbucket public name, and reconnect if there's a mismatch: 1. Following reconnection, the user should use the API again to verify that their `extern_uid` in the GitLab database now matches their current Bitbucket public name. -The importer must then [delete the imported project](../../project/settings/index.md#delete-a-project) +The importer must then [delete the imported project](../../project/working_with_projects.md#delete-a-project) and import again. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 4afe23a29fa..41076bfbc67 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -1,34 +1,21 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from Bitbucket Server **(FREE ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. - -NOTE: -This process is different than [importing from Bitbucket Cloud](bitbucket.md). - -From Bitbucket Server, you can import: - -- Repository description -- Git repository data -- Pull requests -- Pull request comments - -When importing, repository public access is retained. If a repository is private in Bitbucket, it's -created as private in GitLab as well. - -## Import your Bitbucket repositories - > - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. > - Ability to import reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416611) in GitLab 16.3. +> - Support for pull request approval imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135256) in GitLab 16.7. + +Import your projects from Bitbucket Server to GitLab. -You can import Bitbucket repositories to GitLab. +NOTE: +This process is different than [importing from Bitbucket Cloud](bitbucket.md). -### Prerequisites +## Prerequisites > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. @@ -36,8 +23,9 @@ You can import Bitbucket repositories to GitLab. must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. +- Bitbucket Server authentication token with administrator access. -### Import repositories +## Import repositories To import your Bitbucket repositories: @@ -52,16 +40,34 @@ To import your Bitbucket repositories: - For the first time: Select **Import**. - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. -### Items that are not imported +## Items that are imported + +- Repository description +- Git repository data +- Pull requests +- Pull request comments, reviewers, approvals, and merge events +- LFS objects + +When importing, repository public access is retained. If a repository is private in Bitbucket, it's +created as private in GitLab as well. + +When closed or merged pull requests are imported, commit SHAs that do not exist in the repository are fetched from the Bitbucket server +to make sure pull requests have commits tied to them: + +- Source commit SHAs are saved with references in the format `refs/merge-requests/<iid>/head`. +- Target commit SHAs are saved with references in the format `refs/keep-around/<SHA>`. + +If the source commit does not exist in the repository, a commit containing the SHA in the commit message is used instead. + +## Items that are not imported The following items aren't imported: -- Pull request approvals - Attachments in Markdown - Task lists - Emoji reactions -### Items that are imported but changed +## Items that are imported but changed The following items are changed when they are imported: @@ -69,15 +75,12 @@ The following items are changed when they are imported: inserted as comments in the merge request. - Multiple threading levels are collapsed into one thread and quotes are added as part of the original comment. -- Declined pull requests have unreachable commits. These pull requests show up as empty changes. - Project filtering doesn't support fuzzy search. Only **starts with** or **full match** strings are supported. ## User assignment -Prerequisite: - -- Authentication token with administrator access. +> Importing approvals by email address or username [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23586) in GitLab 16.7. When issues and pull requests are importing, the importer tries to find the author's email address with a confirmed email address in the GitLab user database. If no such user is available, the @@ -87,8 +90,10 @@ original creator. The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the repository imports under the namespace of the user who started the import process. -The importer attempts to find reviewers by their email address in the GitLab user database. If they don't exist in GitLab, they cannot be added as reviewers to a -merge request. +The importer attempts to find: + +- Reviewers by their email address in the GitLab user database. If they don't exist in GitLab, they are not added as reviewers to a merge request. +- Approvers by username or email. If they don't exist in GitLab, the approval is not added to a merge request. ### User assignment by username @@ -129,16 +134,6 @@ If the project import completes but LFS objects can't be downloaded or cloned, y password or personal access token containing special characters. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769). -### Pull requests are missing - -Importing large projects spawns a process that can consume a lot of memory. Sometimes you can see messages such as `Sidekiq worker RSS out of range` in the -[Sidekiq logs](../../../administration/logs/index.md#sidekiq-logs). This can mean that MemoryKiller is interrupting the `RepositoryImportWorker` because it's using -too much memory. - -To resolve this problem, temporarily increase the `SIDEKIQ_MEMORY_KILLER_MAX_RSS` environment variable using -[custom environment variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html) from the default `2000000` value to a larger value like `3000000`. -Consider memory constraints on the system before deciding to increase `SIDEKIQ_MEMORY_KILLER_MAX_RSS`. - ## Related topics - [Automate group and project import](index.md#automate-group-and-project-import) diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 30a85a108c9..13d068a8262 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from ClearCase **(FREE ALL)** diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 90ed6cfdb2c..b7f2c0229dc 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from CVS **(FREE ALL)** diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 2bce6708556..1e1b86224d5 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from FogBugz to GitLab **(FREE ALL)** diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 9629ec03443..b67f2c1bdc0 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from Gitea to GitLab **(FREE ALL)** diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index f9b94774809..87467cbc56c 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from GitHub to GitLab **(FREE ALL)** @@ -14,8 +14,7 @@ You can import your GitHub projects from either GitHub.com or GitHub Enterprise. migrate or import any types of groups or organizations from GitHub to GitLab. The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or -`gitlab.com/customer-success`. You can use bulk actions in the rails console to move projects to -different namespaces. +`gitlab.com/customer-success`. If you are importing from GitHub Enterprise to GitLab.com, use the [GitLab Import API](../../../api/import.md#import-repository-from-github) GitHub endpoint instead. The API allows you to @@ -79,61 +78,46 @@ If you are importing from GitHub.com to a self-managed GitLab instance: - GitHub pull request comments (known as diff notes in GitLab) created before 2017 are imported in separate threads. This occurs because of a limitation of the GitHub API that doesn't include `in_reply_to_id` for comments before 2017. -- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383047), if you are using GitHub as an - OmniAuth provider, ensure that the URL perimeter is specified in the - [OmniAuth configuration](../../../integration/github.md#enable-github-oauth-in-gitlab). - Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/424400), Markdown attachments from repositories on GitHub Enterprise Server instances aren't imported. +- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/418800), when importing projects that used + [GitHub auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request), the imported project in GitLab can have merge commits labeled "unverified" if the commit was signed with GitHub's internal GPG key. ## Import your GitHub repository into GitLab -### Use the GitHub integration - -Before you begin, ensure that any GitHub user you want to map to a GitLab user has a GitLab email address that matches their -[publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) on GitHub. - -If you are importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). +Before you begin, ensure that any GitHub user you want to map to a GitLab user +has a GitLab email address that matches their +[publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) +on GitHub. -If a GitHub user's public email address doesn't match any GitLab user email address, the user's activity is associated with the user account that is +If a GitHub user's public email address doesn't match any GitLab user email +address, the user's activity is associated with the user account that is performing the import. -NOTE: -If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured -[GitHub integration](../../../integration/github.md). +### Use the GitHub integration 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Import project** and then **GitHub**. 1. Now you can either: - - Add a personal access token and select **Authenticate**. - - If GitHub is [configured](../../../integration/github.md) for the instance, select **Authorize with GitHub**. -1. Select **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. + - If GitHub OAuth is [configured](../../../integration/github.md) for the instance, select **Authorize with GitHub**. + - Use a GitHub personal access token: + 1. Go to <https://github.com/settings/tokens/new>. + 1. In the **Note** field, enter a token description. + 1. Select the `repo` scope. + 1. Optional. To [import collaborators](#select-additional-items-to-import), select the `read:org` scope. + 1. Select **Generate token**. + 1. On the GitLab import page, in the **Personal Access Token** field, paste the GitHub personal access token. + 1. Select **Authenticate**. 1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import). -### Use a GitHub token - -Prerequisite: +To use a different token to perform an imports after previously performing +these steps, sign out of your GitLab account and sign in again, or revoke the +older token in GitHub. -- Authentication token with administrator access. +### Use the REST API -If you are a GitLab.com user, you can use a personal access token to import your project from GitHub. -If you are an administrator of a self-managed GitLab instance or if you are importing from -GitHub Enterprise, you cannot use a personal access token. -The [GitHub integration method (above)](#use-the-github-integration) is recommended for all users. - -If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories: - -1. Go to `https://github.com/settings/tokens/new`. -1. Enter a token description. -1. Select the `repo` scope. -1. Optional. To [import collaborators](#select-additional-items-to-import), select the `read:org` scope. -1. Select **Generate token**. -1. Copy the token hash. -1. Go back to GitLab and provide the token to the GitHub importer. -1. Select **List Your GitHub Repositories** and wait while GitLab reads your repositories' information. - When done, you are taken to the importer page to select the repositories to import. - -To use a newer personal access token in imports after previously performing these steps, sign out of -your GitLab account and sign in again, or revoke the older personal access token in GitHub. +You can also import a repository from GitHub using the +[GitLab REST API](../../../api/import.md#import-repository-from-github). ### Filter repositories list @@ -165,7 +149,7 @@ To make imports as fast as possible, the following items aren't imported from Gi You can choose to import these items, but this could significantly increase import time. To import these items, select the appropriate fields in the UI: - **Import issue and pull request events**. -- **Use alternative comments import method**. If importing GitHub projects with more than approximately 30,000 comments, you should enable this method because of a +- **Use alternative comments import method**. If importing GitHub projects with more than approximately 30,000 comments across all issues and pull requests, you should enable this method because of a [limitation of the GitHub API](#missing-comments). - **Import Markdown attachments**. - **Import collaborators** (selected by default). Leaving it selected might result in new users using a seat in the group or namespace, @@ -226,7 +210,9 @@ Mirroring does not sync any new or updated pull requests from your GitHub projec ## Improve the speed of imports on self-managed instances -Administrator access on the GitLab server is required for this process. +Administrator access on the GitLab server is required for these steps. + +### Increase the number of Sidekiq workers For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: @@ -242,6 +228,33 @@ Reducing the time spent in cloning a repository can be done by increasing networ performance (by using high performance SSDs, for example) of the disks that store the Git repositories (for your GitLab instance). Increasing the number of Sidekiq workers does *not* reduce the time spent cloning repositories. +### Enable GitHub OAuth using a GitHub Enterprise Cloud OAuth App + +You can use a personal access token to make API requests. Additionally, you can +authorize a GitHub App or OAuth app, which can then make API requests on your +behalf. + +API requests to GitHub are [subject to rate limits](https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-authenticated-users). + +For GitHub repositories with tens of thousands of issues, pull requests, and +comments on those issues and pull requests, a higher rate limit results in a +faster overall import time because the GitLab importer must pause when a +GitHub rate limit is reached. To enable a higher rate limit for your +self-managed or dedicated GitLab instance: + +- Ensure that you have access to a + [GitHub Enterprise Cloud organization](https://docs.github.com/en/enterprise-cloud@latest/get-started/onboarding/getting-started-with-github-enterprise-cloud) +- [Create an OAuth app in GitHub](../../../integration/github.md#create-an-oauth-app-in-github). +- Ensure that the OAuth app is owned by the Enterprise Cloud Organization, not + your personal GitHub account. +- [Configure GitHub OAuth in GitLab](../../../integration/github.md#enable-github-oauth-in-gitlab). +- Perform the project import using the [GitHub integration](#use-the-github-integration) and select **Authorize with GitHub** to use the OAuth authorization method. +- Optional. By default, sign-in is enabled for all configured OAuth providers. + If you want to enable GitHub OAuth for imports but you want to + prevent the ability for users to sign in to your GitLab instance with GitHub, + you can + [disable sign-in with GitHub](../../../integration/omniauth.md#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). + ## Imported data The following items of a project are imported: diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 26054317441..e604d9d871b 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import a project from GitLab.com to your self-managed GitLab instance (removed) **(FREE ALL)** diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index e47e9715980..681174400a2 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import and migrate projects **(FREE ALL)** @@ -41,8 +41,7 @@ with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate gro GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 921669e4b70..17ba5e5fb91 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your Jira project issues to GitLab **(FREE ALL)** diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index aaf19439c24..07328c7a672 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import multiple repositories by uploading a manifest file **(FREE ALL)** diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 10e61139d50..1646c2c5578 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from Perforce Helix **(FREE ALL)** diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 375cb718538..5d67d10582d 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import project from repository by URL **(FREE ALL)** @@ -19,10 +19,8 @@ You can import your existing repositories by providing the Git URL. ## Import project by URL -1. On the left sidebar, select **Search or go to**. -1. Select **View all my projects**. -1. On the right of the page, select **New project**. -1. Select the **Import project** tab. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Import project**. 1. Select **Repository by URL**. 1. Enter a **Git repository URL**. 1. Complete the remaining fields. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index b66e8431f9b..7617dfae525 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate from TFVC to Git **(FREE ALL)** diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 9ee1e33ecdd..7a70d5dde63 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Create a project **(FREE ALL)** @@ -15,7 +15,7 @@ To create a blank project: 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. + - In the **Project name** field, enter the name of your project. See the [limitations on project names](../../user/reserved_names.md). - 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. @@ -52,7 +52,7 @@ To create a project from a built-in template: - 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. + - In the **Project description (optional)** field, enter the description of your project's dashboard. The description is limited to 500 characters. - To modify the project's [viewing and access rights](../public_access.md) for users, change the **Visibility Level**. 1. Select **Create project**. @@ -82,7 +82,7 @@ Custom project templates are available at: - 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. + - The description of your project's dashboard in the **Project description (optional)** field. The description is limited to 500 characters. - To modify the project's [viewing and access rights](../public_access.md) for users, change the **Visibility Level**. 1. Select **Create project**. @@ -107,7 +107,7 @@ To create a project from the HIPAA Audit Protocol template: - 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. + - In the **Project description (optional)** field, enter the description of your project's dashboard. The description is limited to 500 characters. - To modify the project's [viewing and access rights](../public_access.md) for users, change the **Visibility Level**. 1. Select **Create project**. @@ -122,7 +122,7 @@ GitLab creates your project in your chosen namespace. You cannot use `git push` to create projects with project paths that: - Have previously been used. -- Have been [renamed](settings/index.md#rename-a-repository). +- Have been [renamed](working_with_projects.md#rename-a-repository). 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 diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index d8ad7f9a29c..8a91a0c4621 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Insights for projects **(ULTIMATE ALL)** diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 763f478eb99..3031ae42e4d 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -1,10 +1,10 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Apple App Store **(FREE ALL)** +# Apple App Store Connect **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed. @@ -16,9 +16,9 @@ The feature is still in development, but you can: - [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). - [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). -With the Apple App Store integration, you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. +With the Apple App Store Connect integration, you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. -The Apple App Store integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. +The Apple App Store Connect integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. ## Prerequisites @@ -26,7 +26,7 @@ An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.co ## Configure GitLab -GitLab supports enabling the Apple App Store integration at the project level. Complete these steps in GitLab: +GitLab supports enabling the Apple App Store Connect integration at the project level. Complete these steps in GitLab: 1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). 1. On the left sidebar, select **Search or go to** and find your project. @@ -36,15 +36,15 @@ GitLab supports enabling the Apple App Store integration at the project level. C 1. Provide the Apple App Store Connect configuration information: - **Issuer ID**: The Apple App Store Connect issuer ID. - **Key ID**: The key ID of the generated private key. - - **Private Key**: The generated private key. You can download this key only once. - - **Protected branches and tags only**: Enable to only set variables on protected branches and tags. + - **Private key**: The generated private key. You can download this key only once. + - **Protected branches and tags only**: Enable to set variables on protected branches and tags only. 1. Select **Save changes**. -After the Apple App Store integration is activated: +After you enable the integration: - The global variables `$APP_STORE_CONNECT_API_KEY_ISSUER_ID`, `$APP_STORE_CONNECT_API_KEY_KEY_ID`, `$APP_STORE_CONNECT_API_KEY_KEY`, and `$APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64` are created for CI/CD use. -- `$APP_STORE_CONNECT_API_KEY_KEY` contains the Base64 encoded Private Key. +- `$APP_STORE_CONNECT_API_KEY_KEY` contains the Base64-encoded private key. - `$APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64` is always `true`. ## Security considerations @@ -52,7 +52,7 @@ After the Apple App Store integration is activated: ### CI/CD variable security Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including -`$APP_STORE_CONNECT_API_KEY_KEY`, and send them to a third-party server. For more details, see +`$APP_STORE_CONNECT_API_KEY_KEY`, and send them to a third-party server. For more information, see [CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). ## Enable the integration in fastlane diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 442b8695136..1ce01973b2f 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Asana **(FREE ALL)** diff --git a/doc/user/project/integrations/aws_codepipeline.md b/doc/user/project/integrations/aws_codepipeline.md index 5404101b4f6..ec398918fde 100644 --- a/doc/user/project/integrations/aws_codepipeline.md +++ b/doc/user/project/integrations/aws_codepipeline.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # AWS CodePipeline **(FREE SAAS)** diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 85cab40626d..f2b8c9efc1c 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Atlassian Bamboo **(FREE ALL)** diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 8b04d6aad8e..d9971f9a5fa 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Bugzilla **(FREE ALL)** @@ -39,7 +39,7 @@ project pages. This link takes you to the appropriate Bugzilla project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference Bugzilla issues in GitLab diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md index dc93ff8ed06..53db9f22c54 100644 --- a/doc/user/project/integrations/clickup.md +++ b/doc/user/project/integrations/clickup.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ClickUp **(FREE ALL)** @@ -34,7 +34,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference ClickUp issues in GitLab diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 0a31e66fe96..4eb71f815a2 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom issue tracker **(FREE ALL)** diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 29d92b16e32..e8e33eade1a 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Discord Notifications **(FREE ALL)** diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 5c1130c7893..029803f3cc4 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Emails on push **(FREE ALL)** diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 831078e4e4b..8ec62d22a73 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Engineering Workflow Management (EWM) **(FREE ALL)** diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index c368a9da2f6..9249ee68c04 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub **(PREMIUM ALL)** diff --git a/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md new file mode 100644 index 00000000000..363e7c2c364 --- /dev/null +++ b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md @@ -0,0 +1,48 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting GitLab for Slack app **(FREE ALL)** + +When configuring the GitLab for Slack app on GitLab.com, you might encounter the following issues. + +For self-managed GitLab, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md#troubleshooting). + +## The app does not appear in the list of integrations + +The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../../administration/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. + +The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). + +## Project or alias not found + +Some Slack commands must have a project full path or alias and fail with the following error +if the project cannot be found: + +```plaintext +GitLab error: project or alias not found +``` + +To resolve this issue, ensure: + +- The project full path is correct. +- If using a [project alias](gitlab_slack_application.md#create-a-project-alias-for-slash-commands), the alias is correct. +- The GitLab for Slack app is [enabled for the project](gitlab_slack_application.md#from-project-integration-settings). + +## Slash commands return an error in Slack + +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. +To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../../administration/settings/slack_app.md) on your self-managed instance. + +## Notifications are not received to a channel + +If you're not receiving notifications to a Slack channel, ensure: + +- The channel name you configured is correct. +- If the channel is private, you've [added the GitLab for Slack app to the channel](gitlab_slack_application.md#receive-notifications-to-a-private-channel). + +## The App Home does not display properly + +If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](gitlab_slack_application.md#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index abfd4243e07..0a42b363eb6 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Slack app **(FREE ALL)** @@ -20,7 +20,7 @@ you run in Slack is run by your linked GitLab user. Prerequisites: - You must have the [appropriate permissions to add apps to your Slack workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). -- On self-managed GitLab, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). +- On self-managed GitLab, an administrator must [enable the integration](../../../administration/settings/slack_app.md). In GitLab 15.0 and later, the GitLab for Slack app uses [granular permissions](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). @@ -170,46 +170,3 @@ The following events are available for Slack notifications: | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | - -## Troubleshooting - -When configuring the GitLab for Slack app on GitLab.com, you might encounter the following issues. - -For self-managed GitLab, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md#troubleshooting). - -### The app does not appear in the list of integrations - -The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../../administration/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. - -The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). - -### Project or alias not found - -Some Slack commands must have a project full path or alias and fail with the following error -if the project cannot be found: - -```plaintext -GitLab error: project or alias not found -``` - -As a workaround, ensure: - -- The project full path is correct. -- If using a [project alias](#create-a-project-alias-for-slash-commands), the alias is correct. -- The GitLab for Slack app is [enabled for the project](#from-project-integration-settings). - -### Slash commands return an error in Slack - -Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. -To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../../administration/settings/slack_app.md) on your self-managed instance. - -### Notifications are not received to a channel - -If you're not receiving notifications to a Slack channel, ensure: - -- The channel name you configured is correct. -- If the channel is private, you've [added the GitLab for Slack app to the channel](#receive-notifications-to-a-private-channel). - -### The App Home does not display properly - -If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 1affa7abfb4..70a1fe5b054 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Play **(FREE ALL)** diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index e0d30f63ad9..da7fbabd84e 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Chat **(FREE ALL)** diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 9d6be5da810..af81dda6ac1 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Harbor **(FREE ALL)** diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 01dbdd0b3f2..bf1d0826e11 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project integrations **(FREE ALL)** @@ -23,7 +23,7 @@ You can use: ## Manage group-level default settings for a project integration -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the group. @@ -64,7 +64,7 @@ is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ### Remove a group-level default setting -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the group. @@ -79,7 +79,7 @@ Resetting a group-level default setting removes integrations that use default se ## Use instance-level or group-level default settings for a project integration -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. @@ -95,7 +95,7 @@ To use instance-level or group-level default settings for a project integration: ## Use custom settings for a project or group integration -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project or group. @@ -131,7 +131,7 @@ To use custom settings for a project or group integration: | [GitHub](github.md) | Receive statuses for commits and pull requests. | **{dotted-circle}** No | | [GitLab for Slack app](gitlab_slack_application.md) | Use the native Slack app to receive notifications and run commands. | **{dotted-circle}** No | | [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat. | **{dotted-circle}** No | -| [Harbor](harbor.md) | Use Harbor as the Container Registry for GitLab. | **{dotted-circle}** No | +| [Harbor](harbor.md) | Use Harbor as the container registry for GitLab. | **{dotted-circle}** No | | [irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | | [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | | JetBrains TeamCity | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 146123f97cd..4b55dda5388 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # irker (IRC gateway) **(FREE ALL)** diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 9588fbff922..0a82a94d998 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mattermost notifications **(FREE ALL)** diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 715e744988c..f78f637a4df 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mattermost slash commands **(FREE ALL)** @@ -67,8 +67,7 @@ To get configuration values from GitLab: 1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. 1. Copy the **Request URL** value. All other values are suggestions. @@ -109,7 +108,7 @@ Your slash command can now communicate with your GitLab project. ## Connect your GitLab account to Mattermost -Prerequisite: +Prerequisites: - To run [slash commands](gitlab_slack_application.md#slash-commands), you must have [permission](../../permissions.md#project-members-permissions) to diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index dea34709dff..889849f2182 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Microsoft Teams notifications **(FREE ALL)** diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md deleted file mode 100644 index ce092d10d20..00000000000 --- a/doc/user/project/integrations/mlflow_client.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../ml/experiment_tracking/mlflow_client.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../ml/experiment_tracking/mlflow_client.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index ddd000f4c0e..745e70d7d1e 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mock CI **(FREE ALL)** diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md index bf485d73691..cc9f2f468a0 100644 --- a/doc/user/project/integrations/pipeline_status_emails.md +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline status emails **(FREE ALL)** diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index cd0a1819afd..a94391b9362 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pivotal Tracker **(FREE ALL)** diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index 3f1907d04cb..d5adee65456 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pumble **(FREE ALL)** @@ -26,8 +26,7 @@ notifications: 1. To enable the integration for your group or project: 1. In your group or project, on the left sidebar, select **Settings > Integrations**. 1. To enable the integration for your instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index a66aa9cd00a..adc362fa07b 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redmine **(FREE ALL)** @@ -38,7 +38,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index 156ff4a54aa..67613c35657 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ServiceNow **(FREE ALL)** diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index 6ea0cfa6fff..9ed1b471101 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -1,38 +1,12 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2024-02-13' +redirect_to: 'index.md' --- -# Shimo (deprecated) **(FREE ALL)** +# Shimo (removed) **(FREE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 [with a flag](../../../administration/feature_flags.md) named `shimo_integration`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. Feature flag `shimo_integration` removed. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7. -This change is a breaking change. - -[Shimo](https://shimo.im/) is a productivity suite that includes documents, spreadsheets, and slideshows in one interface. -With this integration, you can use the Shimo wiki directly in GitLab instead of the [GitLab group or project wiki](../wiki/index.md). - -## Configure settings in GitLab - -To enable the Shimo integration for your project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > Integrations**. -1. Select **Shimo**. -1. Under **Enable integration**, ensure the **Active** checkbox is selected. -1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). -1. Select **Save changes**. - -On the left sidebar, **Shimo** now appears instead of **Wiki**. - -## View the Shimo Workspace - -To view the Shimo Workspace from your group or project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Shimo**. -1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136143) in 16.7. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index d48fd929d54..9b92fa35e24 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> @@ -11,8 +11,6 @@ WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) in GitLab 15.9 and is planned for removal in 17.0. Use the [GitLab for Slack app](gitlab_slack_application.md) instead. This change is a breaking change. -For the planned support of the GitLab for Slack app for self-managed instances, -see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). The Slack notifications integration enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 67894e158c8..49fbd0eb694 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Slack slash commands **(FREE SELF)** diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md index 75849d61551..6a1ca89f4b7 100644 --- a/doc/user/project/integrations/squash_tm.md +++ b/doc/user/project/integrations/squash_tm.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Squash TM **(FREE SELF)** diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md index 94d0f887730..a7a0a58b922 100644 --- a/doc/user/project/integrations/telegram.md +++ b/doc/user/project/integrations/telegram.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Telegram **(FREE ALL)** @@ -43,8 +43,7 @@ After you invite the bot to a Telegram channel, you can configure GitLab to send 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - **For your instance:** - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Telegram**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 34f8cf262cd..e0dbf3e59aa 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unify Circuit **(FREE ALL)** diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index b675ffa7a36..2a7ad52d9d3 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webex Teams **(FREE ALL)** @@ -29,8 +29,7 @@ notifications: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - At the instance level: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 73450971434..11d164d68e9 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhook events **(FREE ALL)** @@ -1492,7 +1492,7 @@ Payload example: "docker" ] }, - "environment": null + "environment": null, "source_pipeline":{ "project":{ "id": 41, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 1ecc14edcd3..33da78191c0 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhooks **(FREE ALL)** diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index c05083a1d83..bf0c3ff215f 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # YouTrack **(FREE ALL)** @@ -30,7 +30,7 @@ project pages. This link takes you to the appropriate YouTrack project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference YouTrack issues in GitLab diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 64967e94f68..d6f4816b7bb 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ZenTao (deprecated) **(PREMIUM ALL)** diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 8e3310d3234..e6fd302e4f0 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue boards **(FREE ALL)** @@ -133,10 +133,10 @@ With [multiple issue boards](#multiple-issue-boards), each team can have their own board to organize their workflow individually. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=2IaMXteKSD4">Portfolio Planning - Portfolio Management</a>. + See the video: <a href="https://www.youtube.com/watch?v=d9scVJUIF4c">Portfolio Planning - Portfolio Management</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/2IaMXteKSD4" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/d9scVJUIF4c" frameborder="0" allowfullscreen> </iframe> </figure> #### Scrum team diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index e112c5ebd0d..87611a9cda6 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Associate a Zoom meeting with an issue **(FREE ALL)** diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 60b50251555..21cdd88d701 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Confidential issues **(FREE ALL)** diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index cd4ef43d333..a86a94fdea0 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an issue **(FREE ALL)** diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 882e4d97938..de321cedebd 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Crosslinking issues **(FREE ALL)** diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 34a9b69038b..d87fb9e1775 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export issues to CSV **(FREE ALL)** diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 9770c333cdd..f2f56f5566e 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Importing issues from CSV **(FREE ALL)** @@ -13,6 +13,7 @@ You can import issues to a project by uploading a CSV file with the following co | `title` | **{check-circle}** Yes | Issue title. | | `description` | **{check-circle}** Yes | Issue description. | | `due_date` | **{dotted-circle}** No | Issue due date in `YYYY-MM-DD` format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91317) in GitLab 15.2. | +| `milestone` | **{dotted-circle}** No | Title of the issue milestone. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112204) in GitLab 16.7. | Data in other columns is not imported. @@ -29,6 +30,7 @@ You must have at least the Developer role for a project to import issues. - Consider importing a test file containing only a few issues. There is no way to undo a large import without using the GitLab API. - Ensure your CSV file meets the [file format](#csv-file-format) requirements. +- If your CSV includes the milestone header, ensure all unique milestones titles in the file already exist in the project or its parent groups. ## Import the file @@ -41,7 +43,7 @@ To import issues: 1. Select the file you want to import, and then select **Import issues**. The file is processed in the background, and a notification email is sent -to you after the import is complete. +to you if any errors are detected or after the import is complete. ## CSV file format @@ -50,7 +52,7 @@ To import issues, GitLab requires CSV files have a specific format: | Element | Format | |------------------------|--------| | header row | CSV files must include the following headers: `title` and `description`. The case of the headers does not matter. | -| columns | Data from columns outside of `title`, `description`, and `due_date` are not imported. | +| columns | Data from columns outside of `title`, `description`, `due_date`, and `milestone` are not imported. | | separators | The column separator is detected from the header row. Supported separator characters are commas (`,`), semicolons (`;`), and tabs (`\t`). The row separator can be either `CRLF` or `LF`. | | double-quote character | The double-quote (`"`) character is used to quote fields, enabling the use of the column separator in a field (see the third line in the sample CSV data below). To insert a double-quote (`"`) in a quoted field use two double-quote characters in succession (`""`). | | data rows | After the header row, following rows must use the same column order. The issue title is required, but the description is optional. | @@ -67,7 +69,7 @@ Also when using [quick actions](../quick_actions.md): Sample CSV data: ```plaintext -title,description,due_date +title,description,due_date,milestone My Issue Title,My Issue Description,2022-06-28 Another Title,"A description, with a comma", "One More Title","One More Description", @@ -75,6 +77,7 @@ An Issue with Quick Actions,"Hey can we change the frontend? /assign @sjones /label ~frontend ~documentation", +An issue with milestone,"My milestone is created",,v1.0 ``` ### File size diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 9850dcc22fc..01bd840ed0e 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Design management **(FREE ALL)** @@ -23,7 +23,7 @@ For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube. - On self-managed instances, a GitLab administrator must [enable LFS globally](../../../administration/lfs/index.md). - On both GitLab.com and self-managed instances, LFS must be - [enabled for the project itself](../settings/index.md#configure-project-features-and-permissions). + [enabled for the project itself](../settings/project_features_permissions.md#configure-project-features-and-permissions). If enabled globally, LFS is enabled by default for all projects. If you have disabled it for your project, you must enable it again. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 322d603aced..8b58866c256 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Due dates **(FREE ALL)** diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 0b64328fe03..cdbf6d5b5b3 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues **(FREE ALL)** @@ -23,10 +23,10 @@ Issues are always associated with a specific project. If you have multiple projects in a group, you can view all of the projects' issues at once. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=tTE6omrBBZI">Issues - Setting up your Organization with GitLab</a>. + See the video: <a href="https://www.youtube.com/watch?v=Mt1EzlKToig">Issues - Setting up your Organization with GitLab</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/tTE6omrBBZI" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/Mt1EzlKToig" frameborder="0" allowfullscreen> </iframe> </figure> <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index ddd08ee1de0..234ebf4913f 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue weight **(PREMIUM ALL)** diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a162c2d1709..6f2d0083ae8 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage issues **(FREE ALL)** @@ -132,7 +132,7 @@ To move an issue: You can move multiple issues at the same time when you're in a project. You can't move tasks or test cases. -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the project. diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 3ec3b72b173..ea0149db8f7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple assignees for issues **(PREMIUM ALL)** diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 10c7899ac30..517d289b282 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked issues **(FREE ALL)** @@ -75,7 +75,7 @@ Access our [permissions](../../permissions.md) page for more information. When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or **is blocked by** another issue. -Issues that block other issues have an icon (**{issue-block}**) next to their title, shown in the +Issues blocked by other issues have an icon (**{issue-block}**) next to their title, shown in the issue lists and [boards](../issue_board.md). The icon disappears when the blocking issue is closed or their relationship is changed or [removed](#remove-a-linked-issue). diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index f2ecfc1f24b..74b106335fc 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sorting and ordering issue lists **(FREE ALL)** diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index eb872a24767..2cc38e6a31c 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Labels **(FREE ALL)** @@ -322,8 +322,12 @@ An issue, merge request, or epic cannot have two scoped labels, of the form `key with the same `key`. If you add a new label with the same `key` but a different `value`, the previous `key` label is replaced with the new label. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video overview, see [Scoped Labels Speed Run](https://www.youtube.com/watch?v=ebyCiKMFODg). +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=7l7tnEva6I8">Scoped Labels - Setting up your Organization with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/7l7tnEva6I8" frameborder="0" allowfullscreen> </iframe> +</figure> ### Filter by scoped labels diff --git a/doc/user/project/members/img/project_members_filter_direct_v14_4.png b/doc/user/project/members/img/project_members_filter_direct_v14_4.png Binary files differdeleted file mode 100644 index 79cee06bc30..00000000000 --- a/doc/user/project/members/img/project_members_filter_direct_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_filter_inherited_v14_4.png b/doc/user/project/members/img/project_members_filter_inherited_v14_4.png Binary files differdeleted file mode 100644 index ce2a0ebf088..00000000000 --- a/doc/user/project/members/img/project_members_filter_inherited_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_search_v14_4.png b/doc/user/project/members/img/project_members_search_v14_4.png Binary files differdeleted file mode 100644 index 8c52c5788d4..00000000000 --- a/doc/user/project/members/img/project_members_search_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_sort_v14_4.png b/doc/user/project/members/img/project_members_sort_v14_4.png Binary files differdeleted file mode 100644 index 20834b9307e..00000000000 --- a/doc/user/project/members/img/project_members_sort_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 6df33a4fb06..92aaee1ae54 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Members of a project **(FREE ALL)** @@ -17,9 +17,9 @@ Users can become members of a group or project in different ways, which define t | Membership type | Membership process | | --------------------------------------------- | ------------------ | | [Direct](#add-users-to-a-project) | The user is added directly to the current group or project. | -| [Inherited](#inherited-membership) | The user is a member of an ancestor group or project that is added to the current group or project. | +| [Inherited](#inherited-membership) | The user is a member of a parent group that contains the current group or project. | | [Direct shared](share_project_with_groups.md) | The user is a member of a group or project that is shared into the current group or project. | -| [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of an ancestor of a group or project that is shared into the current group or project. | +| [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of a parent of a group or project that is shared into the current group or project. | ```mermaid flowchart RL @@ -45,64 +45,6 @@ flowchart RL G-->|Group C shared with Project A|E ``` -### Inherited membership - -When your project belongs to a group, project members inherit their role -from the group. - - - -In this example: - -- Three members have access to the project. -- **User 0** is a Reporter and has inherited their role in the project from the **demo** group, - which contains the project. -- **User 1** belongs directly to the project. In the **Source** column, they are listed - as a **Direct member**. -- **Administrator** is the [Owner](../../permissions.md) and member of all groups. - They have inherited their role in the project from the **demo** group. - -If a user is: - -- A direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. -- An inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. - -### Membership and visibility rights - -Depending on their membership type, members of groups or projects are granted different [visibility levels](../../../user/public_access.md) -and rights into the group or project. - -| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | -| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | -| Generate boards | ✓ | ✓ | ✓ | ✓ | -| View issues of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | -| View labels of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | -| View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | -| Be shared into other groups | ✓ | | | | -| Be shared into other projects | ✓ | ✓ | ✓ | ✓ | -| Share the group with other members | ✓ | ✓ | ✓ | ✓ | - -In the following example, `User` is a: - -- Direct member of `subgroup`. -- Inherited member of `subsubgroup`. -- Indirect member of `subgroup-2` and `subgroup-3`. -- Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`. - -```mermaid -graph TD - classDef user stroke:green,color:green; - - root --> subgroup --> subsubgroup - root-2 --> subgroup-2 --> subsubgroup-2 - root-3 --> subgroup-3 --> subsubgroup-3 - subgroup -. shared .-> subgroup-2 -. shared .-> subgroup-3 - - User-. member .- subgroup - - class User user -``` - ## Add users to a project > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. @@ -113,9 +55,10 @@ graph TD Add users to a project so they become direct members and have permission to perform actions. -Prerequisite: +Prerequisites: - You must have the Owner or Maintainer role. +- [Group membership lock](../../group/access_and_permissions.md#prevent-members-from-being-added-to-projects-in-a-group) must be disabled. To add a user to a project: @@ -158,6 +101,28 @@ role for the group. For example, the maximum role you can set is: In GitLab 14.8 and earlier, direct members of a project have a maximum role of Maintainer. The Owner [role](../../permissions.md#project-members-permissions) can be added for the group only. +## Inherited membership + +When your project belongs to a group, project members inherit their role +from the group. + + + +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role in the project from the **demo** group, + which contains the project. +- **User 1** has been added directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role in the project from the **demo** group. + +If a user is: + +- A direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. +- An inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group that the member originates from. + ## Add groups to a project > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. @@ -189,19 +154,27 @@ To add a group to a project: From that date onward, the group can no longer access the project. 1. Select **Invite**. -The members of the group are not displayed on the **Members** tab. +The invited group is displayed on the **Groups** tab. Private groups are masked from unauthorized users. +The members of the invited group are not displayed on the **Members** tab. The **Members** tab shows: -- Members who are directly assigned to the project. -- If the project was created in a group [namespace](../../namespace/index.md), members of that group. +- Members who were directly added to the project. +- Inherited members of the group [namespace](../../namespace/index.md) that the project was added to. + +## Share a project with a group + +Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). ## Import members from another project -You can import another project's members to your own project. +You can import another project's direct members to your own project. Imported project members retain the same permissions as the project you import them from. -Prerequisite: +NOTE: +Only direct members of a project are imported. Inherited or shared members of a project are not imported. + +Prerequisites: - You must have the Maintainer or Owner role. @@ -210,7 +183,7 @@ If the importing member's role in the target project is: - Maintainer, then members with the Owner role in the source project are imported with the Maintainer role. - Owner, then members with the Owner role in the source project are imported with the Owner role. -To import users: +To import a project's members: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. @@ -218,7 +191,8 @@ To import users: 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. -After the success message displays, refresh the page to view the new members. +If the import is successful, a success message is displayed. +To view the imported members on the **Members** tab, refresh the page. ## Remove a member from a project @@ -264,7 +238,7 @@ To avoid this problem, GitLab administrators can: - Remove the malicious user account. - Change the password for the malicious user account. -## Filter and sort members +## Filter and sort project members > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. @@ -272,6 +246,13 @@ To avoid this problem, GitLab administrators can: You can filter and sort members in a project. +### Display direct members + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Manage > Members**. +1. In the **Filter members** box, select `Membership` `=` `Direct`. +1. Press <kbd>Enter</kbd>. + ### Display inherited members 1. On the left sidebar, select **Search or go to** and find your project. @@ -279,28 +260,31 @@ You can filter and sort members in a project. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. - +### Search for members in a project -### Display direct members +To search for a project member: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. -1. In the **Filter members** box, select `Membership` `=` `Direct`. +1. In the search box, enter the member's name, username, or email. 1. Press <kbd>Enter</kbd>. - - -### Search - -You can search for members by name, username, or email. +### Sort members in a project - +You can sort members in ascending or descending order by: -### Sort +- **Account** name +- **Access granted** date +- **Max role** the members have in the group +- **User created** date +- **Last activity** date +- **Last sign-in** date -You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. +To sort members: - +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Manage > Members**. +1. At the top of the member list, from the dropdown list, select the item you want to sort by. ## Request access to a project @@ -311,24 +295,29 @@ GitLab users can request to become a member of a project.  -An email is sent to the most recently active project maintainers or owners. -Up to ten project maintainers or owners are notified. -Any project owner or maintainer can approve or decline the request. -Project maintainers cannot approve Owner role access requests. +An email is sent to the most recently active project Maintainers or Owners. +Up to ten project Maintainers or Owners are notified. +Any project Owner or Maintainer can approve or decline the request. +Project Maintainers cannot approve Owner role access requests. + +If a project does not have any direct Owners or Maintainers, the notification is sent to the +most recently active Owners of the project's parent group. + +### Withdraw an access request to a project -If a project does not have any direct owners or maintainers, the notification is sent to the -most recently active owners of the project's group. +You can withdraw an access request to a project before the request is approved. +To withdraw the access request: -If you change your mind before your request is approved, select -**Withdraw Access Request**. +1. On the left sidebar, select **Search or go to** and find the project you requested access to. +1. Next to the project name, select **Withdraw Access Request**. ## Prevent users from requesting access to a project You can prevent users from requesting access to a project. -Prerequisite: +Prerequisites: -- You must be the project owner. +- You must have the Owner role for the project. 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. @@ -336,6 +325,57 @@ Prerequisite: 1. Under **Project visibility**, select **Users can request access**. 1. Select **Save changes**. -## Share a project with a group +## Membership and visibility rights -Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). +Depending on their membership type, members of groups or projects are granted different [visibility levels](../../../user/public_access.md) +and rights into the group or project. + +The following table lists the membership and visibility rights of project members. + +| Action | Direct project member | Inherited project member | Direct shared project member | Inherited shared project member | +| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | +| Generate boards | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View issues of parent groups <sup>1</sup> | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View labels of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View milestones of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Be shared into other groups | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | +| Be imported into other projects | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | +| Share the project with other members | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | + +The following table lists the membership and visibility rights of group members. + +| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | +| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | +| Generate boards | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View issues of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View labels of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View milestones of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | + +<html> +<small>Footnotes: + <ol> + <li>Users can view only issues of projects they have access to.</li> + </ol> +</small> +</html> + +In the following example, `User` is a: + +- Direct member of `subgroup`. +- Inherited member of `subsubgroup`. +- Indirect member of `subgroup-2` and `subgroup-3`. +- Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`. + +```mermaid +graph TD + classDef user stroke:green,color:green; + + root --> subgroup --> subsubgroup + root-2 --> subgroup-2 --> subsubgroup-2 + root-3 --> subgroup-3 --> subsubgroup-3 + subgroup -. shared .-> subgroup-2 -. shared .-> subgroup-3 + + User-. member .- subgroup + + class User user +``` diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 94dbb922c0b..3881220ec7a 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Share a project with a group **(FREE ALL)** diff --git a/doc/user/project/merge_requests/ai_in_merge_requests.md b/doc/user/project/merge_requests/ai_in_merge_requests.md index 2b4b28dafa2..daddf5477ca 100644 --- a/doc/user/project/merge_requests/ai_in_merge_requests.md +++ b/doc/user/project/merge_requests/ai_in_merge_requests.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Duo in merge requests **(ULTIMATE SAAS EXPERIMENT)** @@ -61,8 +61,7 @@ This feature is an [Experiment](../../../policy/experiment-beta-support.md) on G When you've completed your review of a merge request and are ready to [submit your review](reviews/index.md#submit-a-review), generate a GitLab Duo Code review summary: 1. When you are ready to submit your review, select **Finish review**. -1. Select **AI Actions** (**{tanuki}**). -1. Select **Summarize my code review**. +1. Select **Summarize my pending comments**. The summary is displayed in the comment box. You can edit and refine the summary prior to submitting your review. @@ -80,7 +79,7 @@ Provide feedback on this experimental feature in [issue 408991](https://gitlab.c This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com. -When preparing to merge your merge request you may wish to edit the proposed squash or merge commit message. +When preparing to merge your merge request you might wish to edit the proposed squash or merge commit message. To generate a commit message with GitLab Duo: @@ -93,7 +92,7 @@ Provide feedback on this experimental feature in [issue 408994](https://gitlab.c **Data usage**: When you use this feature, the following data is sent to the large language model referenced above: - Contents of the file -- The filename +- The file name ## Generate suggested tests in merge requests @@ -118,4 +117,4 @@ Feedback on this experimental feature can be provided in [issue 408995](https:// **Data usage**: When you use this feature, the following data is sent to the large language model referenced above: - Contents of the file -- The filename +- The file name diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 8ca87f4518e..225ca0cc10d 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Collaborate on merge requests across forks **(FREE ALL)** diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index bace1dfb8b5..5436edf9f8d 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, concepts +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Merge request approvals **(FREE ALL)** @@ -26,7 +25,7 @@ group-level settings for merge request approval rules is tracked in this [GitLab Premium](https://about.gitlab.com/pricing/) and [GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances can also configure approvals -[for the entire instance](../../../admin_area/merge_requests_approvals.md). +[for the entire instance](../../../../administration/admin_area.md). ## How approvals work @@ -129,7 +128,7 @@ Invalid approval rules created through a scan result policy are presented with ## 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 +- [Instance-level approval rules](../../../../administration/admin_area.md) for self-managed installations <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 87ff6376ebd..c284df8d9aa 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approval rules **(PREMIUM ALL)** @@ -16,7 +16,7 @@ You can define approval rules: - [As project defaults](#add-an-approval-rule). - [Per merge request](#edit-or-override-merge-request-approval-rules). -- [At the instance level](../../../admin_area/merge_requests_approvals.md) +- [At the instance level](../../../../administration/admin_area.md) If you don't define a [default approval rule](#add-an-approval-rule), any user can approve a merge request. Even if you don't define a rule, you can still @@ -114,16 +114,23 @@ more of these: - The project. - The project's immediate parent [group](#group-approvers). -- A group that has access to the project via a [share](../../members/share_project_with_groups.md). +- A group that has been [shared](../../members/share_project_with_groups.md) with the project. - A [group added as approvers](#group-approvers). -The following users can approve merge requests if they have Developer or -higher [permissions](../../../permissions.md): +The following users can approve merge requests if they have at least the Developer role: - Users added as approvers at the project or merge request level. - Users who are [Code owners](#code-owners-as-eligible-approvers) of the files changed in the merge request. +Users with the Reporter role can approve only if both of the following are true: + +- The users are part of a group that has been [shared](../../members/share_project_with_groups.md) with the project. + The group must have at least the Reporter role. +- The group has been added as merge request approvers. + +For detailed instructions, see [Merge request approval segregation of duties](#merge-request-approval-segregation-of-duties). + To show who has participated in the merge request review, the Approvals widget in a merge request displays a **Commented by** column. This column lists eligible approvers who commented on the merge request. It helps authors and reviewers identify who to @@ -183,21 +190,24 @@ for protected branches. ## Merge request approval segregation of duties -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. -> - Moved to GitLab Premium in 13.9. - You may have to grant users with the Reporter role permission to approve merge requests before they can merge to a protected branch. Some users (like managers) may not need permission to push or merge code, but still need -oversight on proposed work. To enable approval permissions for these users without -granting them push access: +oversight on proposed work. + +Prerequisites: + +- You must select a specific branch, as this method does **not** work with `All Branches` or `All protected branches` settings. +- The shared group must be added to an approval rule and not individual users, even when the added user is part of the group. + +To enable approval permissions for these users without granting them push access: 1. [Create a protected branch](../../protected_branches.md) 1. [Create a new group](../../../group/index.md#create-a-group). 1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. 1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group), - based on the Reporter role. + with at least the Reporter role. 1. Go to your project and select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval rules**, and either: - For a new rule, select **Add approval rule** and target the protected branch. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 3be546faabe..f9e40a6714c 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approval settings **(PREMIUM ALL)** @@ -57,7 +57,7 @@ this setting, unless you configure one of these options: - [Prevent overrides of default approvals](#prevent-editing-approval-rules-in-merge-requests) at the project level. - *(Self-managed instances only)* Prevent overrides of default approvals - [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured + [at the instance level](../../../../administration/admin_area.md). When configured at the instance level, you can't edit this setting at the project or individual merge request levels. @@ -68,7 +68,7 @@ this setting, unless you configure one of these options: > - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131778) removed in GitLab 16.5. This check now includes merge commits. By default, users who commit to a merge request can still approve it. At both -the project level or [instance level](../../../admin_area/merge_requests_approvals.md), +the project level or [instance level](../../../../administration/admin_area.md), you can prevent committers from approving merge requests that are partially their own. To do this: @@ -76,7 +76,7 @@ their own. To do this: 1. In the **Merge request approvals** section, scroll to **Approval settings** and select **Prevent approvals by users who add commits**. If this checkbox is cleared, an administrator has disabled it - [at the instance level](../../../admin_area/merge_requests_approvals.md), and + [at the instance level](../../../../administration/admin_area.md), and it can't be changed at the project level. 1. Select **Save changes**. @@ -104,26 +104,38 @@ on merge requests, you can disable this setting: This change affects all open merge requests. +When this field is changed, it can affect all open merge requests depending on the setting: + +- If users could edit approval rules previously, and you disable this behavior, + all open merge requests are updated to enforce the approval rules. +- If users could **not** edit approval rules previously, and you enable approval rule + editing, open merge requests remain unchanged. This preserves any changes already + made to approval rules in those merge requests. + ## Require user re-authentication to approve -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. -> - Moved to GitLab Premium in 13.9. -> - SAML authentication for GitLab.com groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 16.6. +> - Requiring re-authentication by using SAML authentication for GitLab.com groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default. +> - Requiring re-authentication by using SAML authentication for self-managed instances [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431415) in GitLab 16.7 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default. + +FLAG: +On self-managed GitLab, by default requiring re-authentication by using SAML authentication is not available. To make it available, an administrator can +[enable the feature flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. On GitLab.com, this feature is not available. You can force potential approvers to first authenticate with either: - A password. -- SAML. Available on GitLab.com groups only. +- SAML. -This -permission enables an electronic signature for approvals, such as the one defined by -[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)): +This permission enables an electronic signature for approvals, such as the one defined by +[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). This +setting is only available on top-level groups. For more information, see [Settings cascading](#settings-cascading). -1. Enable password authentication and SAML authentication (available only on GitLab.com groups). For more information on: +1. Enable password authentication and SAML authentication. For more information on: - Password authentication, see [sign-in restrictions documentation](../../../../administration/settings/sign_in_restrictions.md#password-authentication-enabled). - SAML authentication for GitLab.com groups, see [SAML SSO for GitLab.com groups documentation](../../../../user/group/saml_sso). + - SAML authentication for self-managed instances, see [SAML SSO for self-managed GitLab instances](../../../../integration/saml.md). 1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval settings** and select **Require user re-authentication (password or SAML) to approve**. @@ -153,7 +165,7 @@ However, approvals are reset if the target branch is changed. If you only want to remove approvals by Code Owners whose files have been changed when a commit is added: -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for a project. @@ -172,7 +184,7 @@ To do this: You can also enforce merge request approval settings: -- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups +- At the [instance level](../../../../administration/admin_area.md), which apply to all groups on an instance and, therefore, all projects. - On a [top-level group](../../../group/manage.md#group-merge-request-approval-settings), which apply to all subgroups and projects. @@ -182,6 +194,6 @@ that inherited them. ## Related topics -- [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) +- [Instance-level merge request approval settings](../../../../administration/admin_area.md) - [Compliance center](../../../compliance/compliance_center/index.md) - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 75c9083332a..f0f2d3777f1 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request workflows **(FREE ALL)** @@ -64,7 +63,7 @@ forks. Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 18f19197f4c..780041ac411 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Changes in merge requests **(FREE ALL)** @@ -24,7 +23,8 @@ in our development documentation. To view the diff of changes included in a merge request: -1. Go to your merge request. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. 1. Below the merge request title, select **Changes**. 1. If the merge request changes many files, you can jump directly to a specific file: 1. Select **Show file browser** (**{file-tree}**) or press <kbd>F</kbd> to display the file tree. @@ -44,7 +44,9 @@ so it [applies to all merge requests](#in-all-merge-requests-show-only-one-file- To temporarily change your viewing preferences for a specific merge request: -1. Go to your merge request, and below the merge request title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the merge request title, select **Changes**. 1. Select **Preferences** (**{settings}**). 1. Select or clear the **Show one file at a time** checkbox. @@ -70,7 +72,9 @@ merge requests. To view other changed files, either: You can view the changes inline: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Select **Preferences** (**{settings}**). 1. In the **Compare changes** area, select **Inline**. @@ -80,10 +84,12 @@ The changes are displayed after the original text. ## Compare changes side-by-side -Depending on the length of the changes in your merge request, you may find it +Depending on the length of the changes in your merge request, you might find it easier to view the changes inline, or side-by-side: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Select **Preferences** (**{settings}**). 1. In the **Compare changes** area, select **Side-by-side**. @@ -95,14 +101,18 @@ The changes are displayed across from one another. When reviewing code changes, you can hide inline comments: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Scroll to the file that contains the comments you want to hide. 1. Scroll to the line the comment is attached to, and select **Collapse** (**{collapse}**):  To expand inline comments and show them again: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Scroll to the file that contains the collapsed comments you want to show. 1. Scroll to the line the comment is attached to, and select the user avatar:  @@ -112,7 +122,9 @@ To expand inline comments and show them again: Whitespace changes can make it more difficult to see the substantive changes in a merge request. You can choose to hide or show whitespace changes: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Before the list of changed files, select **Preferences** (**{settings}**). 1. Select or clear the **Show whitespace changes** checkbox: @@ -126,7 +138,9 @@ a merge request. You can choose to hide or show whitespace changes: When reviewing a merge request with many files multiple times, you can ignore files you've already reviewed. To hide files that haven't changed since your last review: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. In the file's header, select the **Viewed** checkbox. Files marked as viewed are not shown to you again unless either: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index af76aa100c1..3d3d302856f 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cherry-pick changes **(FREE ALL)** diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 5ca097da29f..2f4dae5178a 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Commit message templates **(FREE ALL)** @@ -23,7 +22,7 @@ Commit templates use syntax similar to the syntax for Change the commit templates for your project if the default templates don't contain the information you need. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for a project. @@ -37,7 +36,7 @@ To do this: 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. + with data, the final message might be longer. 1. Select **Save changes**. ## Default template for merge commits diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 502dfd7acab..f446750352e 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request commits **(FREE ALL)** @@ -83,3 +82,12 @@ To view the changes between previously merged commits: If you selected to add previously merged commits for context, those commits are also shown in the list. + +## Find the merge request that introduced a change + +When you view the commit details page, GitLab links to one or more merge requests +that contain that commit. + +This behavior only applies to commits that are in the most recent version of a merge +request. If the commits were in a merge request and were rebased out of that merge +request, the commits are not linked. diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 901da6d4cf8..1067beef909 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests for confidential issues **(FREE ALL)** @@ -33,8 +33,8 @@ permissions in your downstream private fork without action by you. These users c immediately push code to branches in your private fork to help fix the confidential issue. WARNING: -Your private fork may expose confidential information, if you create it in a different -namespace than the upstream repository. The two namespaces may not contain the same users. +Your private fork might expose confidential information, if you create it in a different +namespace than the upstream repository. The two namespaces might not contain the same users. Prerequisites: @@ -45,8 +45,9 @@ Prerequisites: To create a confidential merge request: -1. Go to the confidential issue's page. Scroll below the issue description and - select **Create confidential merge request**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues** and find the issue you want to create a merge request for. +1. Scroll below the issue description, and select **Create confidential merge request**. 1. Select the item that meets your needs: - *To create both a branch and a merge request,* select **Create confidential merge request and branch**. Your merge request will diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index e132ddfb729..53d1269a940 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -1,24 +1,44 @@ --- 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/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge conflicts **(FREE ALL)** -_Merge conflicts_ happen when the two branches in a merge request (the source and target) each have different +Merge conflicts happen when the two branches in a merge request (the source and target) each have different changes, and you must decide which change to accept. In a merge request, Git compares the two versions of the files line by line. In most cases, GitLab can merge changes together. However, if two branches both change the same lines, GitLab blocks the merge, -and you must choose which change you want to keep. +and you must choose which change you want to keep: -A merge request cannot merge until you either: + + +A merge request with conflicts cannot merge until you either: - Create a merge commit. - Resolve the conflict through a rebase. - +GitLab resolves conflicts by creating a merge commit in the source branch, but +does not merge it into the target branch. You can then review and test the +merge commit. Verify it contains no unintended changes and doesn't break your build. + +## Understand the conflict block + +When Git detects a conflict that requires a decision on your part, it marks the +beginning and end of the conflict block with conflict markers: + +- `<<<<<<< HEAD` marks the beginning of the conflict block. +- Your changes are shown. +- `=======` marks the end of your changes. +- The latest changes in the target branch are shown. +- `>>>>>>>` marks the end of the conflict. + +When you resolve a conflict, you delete: + +1. The version of the conflicted lines you don't want to keep. +1. The three conflict markers: the beginning, the end, and the `=======` line between + the two versions. ## Conflicts you can resolve in the user interface @@ -39,23 +59,23 @@ criteria, you must resolve the conflict manually. GitLab does not detect conflicts when both branches rename a file to different names. For example, these changes don't create a conflict: -1. On branch `a`, doing `git mv example.txt example1.txt` -1. On branch `b`, doing `git mv example1.txt example3.txt`. +1. Branch `one` renames `example.txt` to `example1.txt` +1. Branch `two` renames `example.txt` to `example_old.txt`. -When these branches merge, both `example1.txt` and `example3.txt` are present. +When these branches merge, both `example1.txt` and `example_old` are present. ## Methods of resolving conflicts GitLab shows [conflicts available for resolution](#conflicts-you-can-resolve-in-the-user-interface) in the user interface, and you can also resolve conflicts locally through the command line: -- [Interactive mode](#resolve-conflicts-in-interactive-mode): UI method best for +- **Interactive mode**: UI method best for conflicts that only require you to select which version of a line to keep, without edits. -- [Inline editor](#resolve-conflicts-in-the-inline-editor): UI method best for more complex conflicts that require you to +- **Inline editor**: UI method best for more complex conflicts that require you to edit lines and manually blend changes together. -- [Command line](#resolve-conflicts-from-the-command-line): provides complete control over the most complex conflicts. +- **Command line**: provides complete control over the most complex conflicts. -## Resolve conflicts in interactive mode +### In interactive mode To resolve less-complex conflicts from the GitLab user interface: @@ -63,14 +83,15 @@ To resolve less-complex conflicts from the GitLab user interface: 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. - GitLab shows a list of files with merge conflicts. The conflicts are + GitLab shows a list of files with merge conflicts. The lines that conflict are highlighted: -  +  + 1. For each conflict, select **Use ours** or **Use theirs** to mark the version of the conflicted lines you want to keep. This decision is known as "resolving the conflict." -1. Enter a **Commit message**. +1. When you've resolved all of the conflicts, enter a **Commit message**. 1. Select **Commit to source branch**. Resolving conflicts merges the target branch of the merge request into the @@ -78,27 +99,35 @@ source branch, using the version of the text you chose. If the source branch is `feature` and the target branch is `main`, these actions are similar to running `git switch feature; git merge main` locally. -## Resolve conflicts in the inline editor +### In the inline editor -Some merge conflicts are more complex, requiring you to manually modify lines to -resolve their conflicts. Use the merge conflict resolution editor to resolve complex -conflicts in the GitLab interface: +Some merge conflicts are more complex, and you must manually modify lines to +resolve their conflicts. The merge conflict resolution editor helps you resolve +these complex conflicts in the GitLab interface: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. -1. Select **Edit inline** to open the editor: -  +1. Find the file to edit manually, and scroll to the conflict block. +1. In the header for that file, select **Edit inline** to open the editor. In this + example, the conflict block begins at line 1350 and ends at line 1356: + +  + 1. After you resolve the conflict, enter a **Commit message**. 1. Select **Commit to source branch**. -## Resolve conflicts from the command line +### From the command line While most conflicts can be resolved through the GitLab user interface, some are too complex. Complex conflicts are best fixed locally, from the command line, to give you the -most control over each change: +most control over each change. + +Prerequisites: + +- You must have permission to force push to branches. 1. Open the terminal and check out your feature branch. For example, `my-feature-branch`: @@ -106,7 +135,7 @@ most control over each change: git switch my-feature-branch ``` -1. [Rebase your branch](../../../topics/git/git_rebase.md#regular-rebase) against the +1. [Rebase your branch](../../../topics/git/git_rebase.md#rebase-by-using-git) against the target branch (here, `main`) so Git prompts you with the conflicts: ```shell @@ -115,12 +144,7 @@ most control over each change: ``` 1. Open the conflicting file in your preferred code editor. -1. Find the conflict block: - - It begins with the marker: `<<<<<<< HEAD`. - - Next, it displays your changes. - - The marker `=======` indicates the end of your changes. - - Next, it displays the latest changes in the target branch. - - The marker `>>>>>>>` indicates the end of the conflict. +1. Find the conflict block. 1. Edit the file: 1. Choose which version (before or after `=======`) you want to keep. 1. Delete the version you don't want to keep. @@ -151,28 +175,10 @@ most control over each change: running `git rebase`. After you run `git rebase --continue`, you cannot abort the rebase. -1. [Force-push](../../../topics/git/git_rebase.md#force-push) the changes to your +1. [Force-push](../../../topics/git/git_rebase.md#force-pushing) the changes to your remote branch. -## Merge commit strategy - -GitLab resolves conflicts by creating a merge commit in the source branch, but -does not merge it into the target branch. You can then review and test the -merge commit. Verify it contains no unintended changes and doesn't break your build. - ## Related topics - [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md) - [Git applications for visualizing the Git workflow](https://git-scm.com/downloads/guis) - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index ec269bec84d..951c848dee1 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "How to create merge requests in GitLab." --- @@ -22,63 +22,71 @@ You can create a merge request from the list of merge requests. 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. In the upper-right corner, select **New merge request**. -1. Select a source and target branch and then **Compare branches and continue**. -1. Fill out the fields and select **Create merge request**. +1. Select a source and target branch, then select **Compare branches and continue**. +1. Complete the fields on the **New merge request** page, then 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. +Each branch can be associated with only one open merge request. If a merge request +already exists for this branch, a link to the existing merge request is shown. ## From an issue -> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) the behavior of the **Create merge request** button to open the merge request creation form in GitLab 14.8. If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. After merging the merge request, the issue is closed automatically, unless -[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown list below the issue description. +[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing): -NOTE: -In GitLab 14.8 and later, selecting **Create merge request** -[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) -instead of immediately creating the merge request. +::Tabs -**Create merge request** doesn't display if: +:::TabTitle Merge request and branch -- A branch with the same name already exists. -- A merge request already exists for this branch. -- Your project has an active fork relationship. -- Your project is private and the issue is confidential. +To create a branch and a merge request at the same time: -To make this button appear, one possible workaround is to -[remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork). -After removal, the fork relationship cannot be restored. This project can no longer -be able to receive or send merge requests to the source project, or other forks. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues** and find your issue. +1. Go to the bottom of the issue description. +1. Select **Create merge request > Create merge request and branch**. +1. In the dialog, review the suggested branch name. It's based on your project's + [branch name template](../repository/branches/index.md) Rename it if the + branch name is already taken, or you need a different branch name. +1. Select a source branch or tag. +1. Select **Create merge request**. -The dropdown list contains the options **Create merge request and branch** and **Create branch**. +:::TabTitle Branch only -After selecting one of these options, a new branch or branch and merge request -is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on your project's [branch name template](../repository/branches/index.md), -but this value can be changed. +To create only a branch directly from an issue: -When you select **Create branch** in an empty -repository project, GitLab performs these actions: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues** and find your issue. +1. Go to the bottom of the issue description. +1. Select **Create merge request > Create branch**. +1. In the dialog, review the suggested branch name. It's based on your project's + [branch name template](../repository/branches/index.md) Rename it if the + branch name is already taken, or you need a different branch name. +1. Select a source branch or tag. +1. Select **Create branch**. + +::EndTabs + +If your Git repository is empty, GitLab: - Creates a default branch. - Commits a blank `README.md` file to it. - Creates and redirects you to a new branch based on the issue title. -- _If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes,_ +- If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes, GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) by helping you create a `.gitlab-ci.yml` file. -After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly-created branch, -the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the -merge request is merged. +If the name of the branch you create is +[prefixed with the issue number](../repository/branches/index.md#prefix-branch-names-with-issue-numbers), +GitLab cross-links the issue and merge request, and adds the +[issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +to the description of the merge request. In most cases, this looks like `Closes #ID`, +where `ID` is the ID of the issue. If your project is configured with a +[closing pattern](../issues/managing_issues.md#default-closing-pattern), the issue closes +when the merge request merges. ## When you add, edit, or upload a file @@ -86,10 +94,11 @@ You can create a merge request when you add, edit, or upload a file to a reposit 1. [Add, edit, or upload](../repository/web_editor.md) a file to the repository. 1. In the **Commit message**, enter a reason for the commit. -1. Select the **Target branch** or create a new branch by typing the name (without spaces). +1. Select the **Target branch** or create a new branch by typing the name. 1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only if the target is not the same as the source branch, or if the source branch is protected. -1. Select **Commit changes**. +1. Select **Upload file**. +1. Fill out the fields and select **Create merge request**. ## When you create a branch @@ -112,20 +121,27 @@ You can create a merge request by running Git commands on your local machine. git checkout -b my-new-branch ``` -1. Create, edit, or delete files. The stage and commit them: +1. Create, edit, or delete files as needed. + +1. Mark the files as ready to commit (staging them) and commit them locally: ```shell + # Mark the files as ready to commit git add . + # Commit the changes locally git commit -m "My commit message" ``` -1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): +1. [Push your branch and its commits to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlab): ```shell git push origin my-new-branch ``` - GitLab prompts you with a direct link for creating a merge request: + To reduce the number of fields to edit later in the merge request, use + [push options](../push_options.md) to set the value of fields. + +1. In the response to the `git push`, GitLab provides a direct link to create the merge request: ```plaintext ... @@ -135,9 +151,6 @@ You can create a merge request by running Git commands on your local machine. 1. Copy the link and paste it in your browser. -You can add other [flags to commands when pushing through the command line](../push_options.md) -to reduce the need for editing merge requests manually through the UI. - ## When you work in a fork You can create a merge request from your fork to contribute back to the main project. @@ -189,8 +202,7 @@ A merge request is created. ### Add attachments when creating a merge request by email You can add commits to a merge request by adding -patches as attachments to the email. All attachments with a filename -ending in `.patch` are considered patches and are processed +patches as attachments to the email. All attachments with a file name ending in `.patch` are considered patches and are processed ordered by name. The combined size of the patches can be 2 MB. @@ -221,3 +233,19 @@ To have merge requests from a fork by default target your own fork 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. + +## Troubleshooting + +### No option to create a merge request on an issue + +The option to **Create merge request** doesn't display on an issue if: + +- A branch with the same name already exists. +- A merge request already exists for this branch. +- Your project has an active fork relationship. +- Your project is private and the issue is confidential. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index cc7fa050766..4f22b2ab273 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export merge requests to CSV **(FREE ALL)** diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 8fb5230c497..25e967a8f86 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -1,12 +1,14 @@ --- 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/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request dependencies **(PREMIUM ALL)** +> - Support for complex merge dependencies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. Disabled by default. +> - Support for complex merge dependencies [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136775) in GitLab 16.7. Feature flag `remove_mr_blocking_constraints` removed. + A single feature can span several merge requests, spread out across multiple projects, and the order in which the work merges can be significant. Use merge request dependencies when it's important to merge work in a specific order. Some examples: @@ -48,6 +50,26 @@ enforced only for the dependent merge request. A merge request in a **PREMIUM** project can depend on a merge request in a **FREE** project, but a merge request in a **FREE** project cannot be marked as dependent. +## Nested dependencies + +Indirect, nested dependencies are supported in GitLab 16.7 and later. +A single merge request can be blocked by up to 10 merge requests, and, +in turn, can block up to 10 merge requests. In this example, `myfriend/library!10` +depends on `herfriend/another-lib!1`, which in turn depends on `mycorp/example!100`: + +```mermaid +graph LR; + A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1] + B-->|depends on| C[mycorp/example!100] +``` + +Nested dependencies do not display in the GitLab UI, but UI support has +been proposed in [epic 5308](https://gitlab.com/groups/gitlab-org/-/epics/5308). + +NOTE: +A merge request can't be made dependent on itself (self-referential), but +it's possible to create circular dependencies. + ## View dependencies for a merge request If a merge request is dependent on another, the merge request reports section shows @@ -99,7 +121,7 @@ To create a new merge request and mark it as dependent on another: You can edit an existing merge request and mark it as dependent on another. -Prerequisite: +Prerequisites: - You must have at least the Developer role or be allowed to edit merge requests in the project. @@ -116,7 +138,7 @@ To do this: You can edit a dependent merge request and remove a dependency. -Prerequisite: +Prerequisites: - You must have a role in the project that allows you to edit merge requests. @@ -142,32 +164,3 @@ No API support exists for managing dependencies. For more information, read Dependencies are not preserved when projects are imported or exported. For more information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549). - -### Complex merge order dependencies are unsupported - -- Support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. -On GitLab.com, this feature is available. - -If you attempt to create an indirect, nested dependency, GitLab shows the error message: - -- Dependencies failed to save: Dependency chains are not supported - -GitLab supports direct dependencies between merge requests, but does not support -[indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393). - -Acceptable dependency patterns include: - -- A single merge request can directly depend on a single merge request. -- A single merge request can directly depend on multiple merge requests. -- Multiple merge requests can directly depend on a single merge request. - -The indirect, nested dependency between `myfriend/library!10` and `mycorp/example!100` shown in this example is not supported: - -```mermaid -graph LR; - A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1] - B-->|depends on| C[mycorp/example!100] -``` diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index a3b1920e375..67d24e72fed 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Draft merge requests **(FREE ALL)** @@ -56,7 +55,8 @@ are notified. When you view or search in your project's merge requests list, to include or exclude draft merge requests: -1. Go to your project and select **Code > Merge requests**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests**. 1. To filter by merge request status, select **Open**, **Merged**, **Closed**, or **All** in the navigation bar. 1. Select the search box to display a list of filters and select **Draft**, or @@ -78,7 +78,7 @@ if you want to run [merged results pipelines](../../../ci/pipelines/merged_resul Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/img/conflict_section.png b/doc/user/project/merge_requests/img/conflict_section.png Binary files differdeleted file mode 100644 index cfc17013218..00000000000 --- a/doc/user/project/merge_requests/img/conflict_section.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/conflict_section_v16_7.png b/doc/user/project/merge_requests/img/conflict_section_v16_7.png Binary files differnew file mode 100644 index 00000000000..40701e46b50 --- /dev/null +++ b/doc/user/project/merge_requests/img/conflict_section_v16_7.png diff --git a/doc/user/project/merge_requests/img/conflicts_v16_7.png b/doc/user/project/merge_requests/img/conflicts_v16_7.png Binary files differnew file mode 100644 index 00000000000..1de03b5cfe0 --- /dev/null +++ b/doc/user/project/merge_requests/img/conflicts_v16_7.png diff --git a/doc/user/project/merge_requests/img/merge_conflict_editor.png b/doc/user/project/merge_requests/img/merge_conflict_editor.png Binary files differdeleted file mode 100644 index f10efbce5f5..00000000000 --- a/doc/user/project/merge_requests/img/merge_conflict_editor.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_conflict_editor_v16_7.png b/doc/user/project/merge_requests/img/merge_conflict_editor_v16_7.png Binary files differnew file mode 100644 index 00000000000..b56ee2abdd7 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_conflict_editor_v16_7.png diff --git a/doc/user/project/merge_requests/img/merge_request_widget.png b/doc/user/project/merge_requests/img/merge_request_widget.png Binary files differdeleted file mode 100644 index 58562fcb034..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_widget.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions.png b/doc/user/project/merge_requests/img/versions.png Binary files differdeleted file mode 100644 index 8355fd62dcb..00000000000 --- a/doc/user/project/merge_requests/img/versions.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_compare.png b/doc/user/project/merge_requests/img/versions_compare.png Binary files differdeleted file mode 100644 index 0957a0310ac..00000000000 --- a/doc/user/project/merge_requests/img/versions_compare.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png b/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png Binary files differdeleted file mode 100644 index 61cf72e7bf9..00000000000 --- a/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_dropdown.png b/doc/user/project/merge_requests/img/versions_dropdown.png Binary files differdeleted file mode 100644 index 831c92db2c0..00000000000 --- a/doc/user/project/merge_requests/img/versions_dropdown.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_dropdown_v16_6.png b/doc/user/project/merge_requests/img/versions_dropdown_v16_6.png Binary files differnew file mode 100644 index 00000000000..9dd6b63d26f --- /dev/null +++ b/doc/user/project/merge_requests/img/versions_dropdown_v16_6.png diff --git a/doc/user/project/merge_requests/img/versions_system_note.png b/doc/user/project/merge_requests/img/versions_system_note.png Binary files differdeleted file mode 100644 index 97d552692c9..00000000000 --- a/doc/user/project/merge_requests/img/versions_system_note.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_system_note_v16_6.png b/doc/user/project/merge_requests/img/versions_system_note_v16_6.png Binary files differnew file mode 100644 index 00000000000..b26e58c7697 --- /dev/null +++ b/doc/user/project/merge_requests/img/versions_system_note_v16_6.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 63e5cc93e7d..3555d9ffa01 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,13 +1,12 @@ --- 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/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests **(FREE ALL)** -To incorporate changes from a source branch to a target branch, you use a *merge request* (MR). +A merge request (MR) is a proposal to incorporate changes from a source branch to a target branch. When you open a merge request, you can visualize and collaborate on the changes before merge. Merge requests include: @@ -463,7 +462,7 @@ merge request to display an incorrect message: `merged into <branch-name>`. ### Close a merge request from the Rails console **(FREE SELF)** -If closing a merge request doesn't work through the UI or API, you may want to attempt to close it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): +If closing a merge request doesn't work through the UI or API, you might want to attempt to close it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): WARNING: Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. @@ -477,7 +476,7 @@ MergeRequests::CloseService.new(project: p, current_user: u).execute(m) ### Delete a merge request from the Rails console **(FREE SELF)** -If deleting a merge request doesn't work through the UI or API, you may want to attempt to delete it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): +If deleting a merge request doesn't work through the UI or API, you might want to attempt to delete it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): WARNING: Any command that changes data directly could be damaging if not run correctly, @@ -514,6 +513,7 @@ This error can happen if your merge request: - Contains many diffs. - Is many commits behind the target branch. +- References a Git LFS file that is locked. Users in self-managed installations can request an administrator review server logs to determine the cause of the error. GitLab SaaS users should diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index c4c38ef9eaf..a9cad78449b 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auto-merge **(FREE ALL)** @@ -110,7 +109,7 @@ When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent merge requests from being merged. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role in the project. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 959ada4928e..dd70052cd31 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge methods **(FREE ALL)** @@ -199,7 +198,7 @@ In these merge methods, you can merge only when your source branch is up-to-date If a fast-forward merge is not possible but a conflict-free rebase is possible, GitLab provides: -- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#from-the-gitlab-ui). +- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-ui). - The option to select **Rebase** in the user interface. You must rebase the source branch locally before a fast-forward merge if both @@ -220,8 +219,11 @@ considered equivalent to rebasing. To rebase a merge request's branch without triggering a CI/CD pipeline, select **Rebase without pipeline** from the merge request reports section. -This option is available when fast-forward merge is not possible but a conflict-free -rebase is possible. + +This option is: + +- Available when fast-forward merge is not possible but a conflict-free rebase is possible. +- Not available when the **Pipelines must succeed** option is enabled. Rebasing without a CI/CD pipeline saves resources in projects with a semi-linear workflow that requires frequent rebases. diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 4476ec8c670..07523b9f34c 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Revert changes **(FREE ALL)** @@ -92,7 +92,7 @@ you must revert the commit from the command line: Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index b32c527ab75..0499e5a0bb7 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -1,8 +1,7 @@ --- stage: AI-powered group: AI Model Validation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Suggested Reviewers Data Usage **(ULTIMATE SAAS)** diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png Binary files differdeleted file mode 100644 index 476c50b9098..00000000000 --- a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview_v16_6.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview_v16_6.png Binary files differnew file mode 100644 index 00000000000..f35a2c5e8a1 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview_v16_6.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v16_6.png Binary files differindex 6f29107146d..6f29107146d 100644 --- a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v16_6.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index d3124b716da..23b1207619e 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request reviews **(FREE ALL)** @@ -15,7 +14,7 @@ from the user interface. When your work is reviewed, your team members can choos to accept or reject it. You can review merge requests from the GitLab interface. If you install the -[GitLab Workflow VS Code extension](../../repository/vscode.md), you can also +[GitLab Workflow VS Code extension](../../../../editor_extensions/visual_studio_code/index.md), you can also review merge requests in Visual Studio Code. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 90a276dc303..908e8c67c3b 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Suggest changes **(FREE ALL)** @@ -18,9 +17,8 @@ merge request, authored by the user who suggested the changes. 1. Select **Code > Merge requests** and find your merge request. 1. On the secondary menu, select **Changes**. 1. Find the lines of code you want to change. - - To select a single line: - - Hover over the line number, and - select **Add a comment to this line** (**{comment}**). + - To select a single line, hover over the line number and + select **Add a comment to this line** (**{comment}**). - To select multiple lines: 1. Hover over the line number, and select **Add a comment to this line** (**{comment}**). 1. Select and drag your selection until all desired lines are included. To @@ -35,8 +33,11 @@ merge request, authored by the user who suggested the changes. ```` 1. Edit the pre-populated code block to add your suggestion. -1. Select either **Start a review** or **Add to review** to add your comment to a - [review](index.md), or **Add comment now** to add the comment to the thread immediately. +1. Select whether you want your comment to appear immediately: + + - **Start a review** or **Add to review** creates your comment in a pending state + as part of a [review](index.md). + - **Add comment now** adds your comment immediately. ### Multi-line suggestions @@ -45,23 +46,24 @@ in a single suggestion, by either: - Selecting and dragging, as described in [Create suggestions](#create-suggestions). GitLab creates a suggestion block for you. -- Selecting a single line, then manually adjusting the range offsets. +- Selecting a single line, then manually editing the range offsets in the suggestion block. The range offsets in the first line of the suggestion describe line numbers relative to the line you selected. The offsets specify the lines your suggestion intends to replace. -For example, this suggestion covers 3 lines above and 4 lines below the +For example, this suggestion covers 2 lines above and 2 lines below the commented line: ````markdown -```suggestion:-3+4 - "--talk-name=ca.desrt.dconf", - "--socket=wayland", +```suggestion:-2+2 +## Prevent approval by author + +By default, the author of a merge request cannot approve it. To change this setting: ``` ```` -When applied, the suggestion replaces from 3 lines above to 4 lines below the commented line: +When applied, the suggestion replaces from 2 lines above to 2 lines below the commented line: - + Suggestions for multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line. This allows for up to 200 changed lines per @@ -74,7 +76,7 @@ suggestion. > - Feature flag `content_editor_on_issues` removed in GitLab 16.5. When you insert suggestions, you can use the WYSIWYG -[rich text editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/) to move +[rich text editor](../../../rich_text_editor.md) to move up and down the source file's line numbers in the UI. To add or subtract changed lines, next to **From line**, select **+** or **-**. @@ -119,7 +121,7 @@ git config --global receive.advertisepushoptions true ```` ````` - + ## Configure the commit message for applied suggestions @@ -133,9 +135,14 @@ Apply 3 suggestion(s) to 2 file(s) ``` Merge requests created from forks use the template defined in the target project. +To meet your project's needs, customize these messages and include other +placeholder variables. + +Prerequisites: -To meet your project's needs, you can customize these messages and include other -placeholder variables: +- You must have the Maintainer role. + +To do this: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. @@ -166,12 +173,16 @@ For example, to customize the commit message to output > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. -To reduce the number of commits added to your branch, you can apply multiple +Prerequisites: + +- You must have a role in the project that allows you to commit to the source branch. + +To reduce the number of commits added to your branch, apply multiple suggestions in a single commit. 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. -1. For each suggestion you want to apply, and select **Add suggestion to batch**. +1. For each suggestion you want to apply, select **Add suggestion to batch**. 1. Optional. To remove a suggestion, select **Remove from batch**. 1. After you add your desired suggestions, select **Apply suggestions**. diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index a6d55ee44e2..d7635763f9e 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Squash and merge **(FREE ALL)** diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index c330af0fc9b..b13f0a70295 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -1,8 +1,7 @@ --- stage: Govern group: Compliance -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, concepts +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # External status checks **(ULTIMATE ALL)** @@ -172,8 +171,7 @@ To retry a failed status check: An organization might have a policy that does not allow merging merge requests if external status checks do not pass. However, the details in the widget are for informational -purposes only. GitLab does not prevent merging of merge requests that fail status checks. -Support to allow merges to be blocked when external status checks fail is proposed in epic [&8516](https://gitlab.com/groups/gitlab-org/-/epics/8516). +purposes only. NOTE: GitLab cannot guarantee that the external status checks are properly processed by diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index a5635d22530..62cee897b49 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,78 +1,69 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Merge requests versions **(FREE ALL)** +# Merge request diff versions **(FREE ALL)** -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 -more than one pushes, you can select and compare the versions of those merge -request diffs. +When you create a merge request, you select two branches to compare. The differences +between the two branches are shown as a **diff** in the merge request. Each time +you push commits to a branch connected to a merge request, GitLab updates the +merge request diff to a new **diff version**. - +NOTE: +Diff versions are updated on each push, not each commit. If a push contains multiple +commits, only one new diff version is created. -## Selecting a version +By default, GitLab compares the latest push in your source branch (`feature`) +against the most recent commit in the target branch, often `main`. -By default, the latest version of changes is shown. However, you -can select an older one from version dropdown list. +## Compare diff versions - +If you've pushed to your branch multiple times, the diff version from each previous push +is available for comparison. When your merge request contains many changes or +sequential changes to the same file, you might want to compare a smaller number of changes. -Merge request versions are based on push not on commit. So, if you pushed 5 -commits in a single push, it displays as a single option in the dropdown list. If you -pushed 5 times, that counts for 5 options. +Prerequisites: -You can also compare the merge request version with an older one to see what has -changed since then. +- The merge request branch must contain commits from multiple pushes. Individual commits + in the same push do not generate new diff versions. - +To compare diff versions: -Comments are disabled while viewing outdated merge versions or comparing to -versions other than base. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests**. +1. Select a merge request. +1. To view the current diff version for this merge request, select **Changes**. +1. Next to **Compare** (**{file-tree}**), select the pushes to compare. This example + compares `main` to the most recent push (latest diff version) of the branch: -Every time you push new changes to the branch, a link to compare the last -changes appears as a system note. +  - + This example branch has four commits, but the branch contains only three diff versions + because two commits were pushed at the same time. -## Find the merge request that introduced a change +## View diff versions from a system note -When viewing the commit details page, GitLab links to the merge request (or -merge requests, if it's in more than one) containing that commit. +GitLab adds a system note to a merge request each time you push new changes to +the merge request's branch. In this example, a single push added two commits: -This only applies to commits that are in the most recent version of a merge -request - if commits were in a merge request, then rebased out of that merge -request, they aren't linked. + -## `HEAD` comparison mode for merge requests +To view the diff for that commit, select the commit SHA. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) in GitLab 12.10. +For more information, see how to [show or filter system notes on a merge request](../system_notes.md#on-a-merge-request). -Merge requests, particularly the **Changes** tab, is where source code -is reviewed and discussed. In circumstances where the target branch was -merged into the source branch of the merge request, the changes in the -source and target branch can be shown mixed together making it hard to -understand which changes are being added and which already exist in the -target branch. +## Related topics -In GitLab 12.10, we added a comparison mode, which -shows a diff calculated by simulating how it would look like once merged - a more accurate -representation of the changes rather than using the base of the two -branches. The new mode is available from the comparison target drop down -by selecting **main (HEAD)**. In GitLab 13.9, it -[replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the -old default comparison. For technical details, additional information is available in the -[developer documentation](../../../development/merge_request_concepts/diffs/index.md#merge-request-diffs-against-the-head-of-the-target-branch). - - +- [Merge request diffs for developers](../../../development/merge_request_concepts/diffs/index.md) +- [Merge request diff storage for administrators](../../../administration/merge_request_diffs.md) <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index da766b685a3..d60bd660b53 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -1,8 +1,7 @@ --- 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/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request widgets **(FREE ALL)** diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 65cc9477c49..b67078614a8 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Burndown and burnup charts **(PREMIUM ALL)** diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 328e56e2bd8..a959507b338 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -1,8 +1,7 @@ --- -type: index, reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Milestones **(FREE ALL)** @@ -46,7 +45,7 @@ In a group, GitLab displays milestones that belong to the group and all projects ### View milestones in a project with issues turned off If a project has issue tracking -[turned off](../settings/index.md#configure-project-features-and-permissions), +[turned off](../settings/project_features_permissions.md#configure-project-features-and-permissions), to get to the milestones page, enter its URL. To do so: diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md index 9cedb5780ed..35972f0ad7f 100644 --- a/doc/user/project/ml/experiment_tracking/mlflow_client.md +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -1,20 +1,20 @@ --- -stage: Create -group: Incubation -info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. +stage: ModelOps +group: MLOps +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# MLflow client compatibility **(FREE ALL)** +# MLflow client compatibility **(FREE ALL EXPERIMENT)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. NOTE: -Model experiment tracking is an [experimental feature](../../../../policy/experiment-beta-support.md). -Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. +Model registry and model experiment tracking are [Experiments](../../../../policy/experiment-beta-support.md). +Provide feedback [for model experiment tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/381660). Provide feedback for [model registry](https://gitlab.com/gitlab-org/gitlab/-/epics/9423). [MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. -GitLab [Model experiment tracking](index.md) is compatible with MLflow Client, -[logging experiments](index.md). The setup requires minimal changes to existing code. +GitLab [Model experiment tracking](index.md) and GitLab +[Model registry](../model_registry/index.md) are compatible with the MLflow client. The setup requires minimal changes to existing code. GitLab plays the role of a MLflow server. Running `mlflow server` is not necessary. @@ -37,18 +37,18 @@ To use MLflow client compatibility from a local environment: export MLFLOW_TRACKING_TOKEN="<your_access_token>" ``` -1. If your training code contains the call to `mlflow.set_tracking_uri()`, remove it. +1. If the training code contains the call to `mlflow.set_tracking_uri()`, remove it. -When running the training code, MLflow creates experiments, runs, log parameters, metrics, metadata -and artifacts on GitLab. +## Model experiments + +When running the training code, MLflow client can be used to create experiments, runs, +models, model versions, log parameters, metrics, metadata and artifacts on GitLab. After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. -Runs are registered as: -- Model Candidates, which can be explored by selecting an experiment. -- Tags, which are registered as metadata. +Runs are registered as candidates, which can be explored by selecting an experiment, model, or model version. -## Associating a candidate to a CI/CD job +### Associating a candidate to a CI/CD job > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1. @@ -71,10 +71,179 @@ candidate metadata. To associate a candidate to a CI/CD job: # End of snippet to be included ``` +## Model registry + +You can also manage models and model versions by using the MLflow +client. Models are registered under `/<your project>/-/ml/models`. + +### Models + +#### Creating a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +description = 'Model description' +model = client.create_registered_model(model_name, description=description) +``` + +**Notes** + +- `create_registered_model` argument `tags` is ignored. +- `name` must be unique within the project. +- `name` cannot be the name of an existing experiment. + +#### Fetching a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +model = client.get_registered_model(model_name) +``` + +#### Updating a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +description = 'New description' +client.update_registered_model(model_name, description=description) +``` + +#### Deleting a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +client.delete_registered_model(model_name) +``` + +### Logging candidates to a model + +Every model has an associated experiment with the same name. To log a candidate/run to the model, +use the experiment with the name of the model: + +```python +client = MlflowClient() +model_name = '<your_model_name>' +exp = client.get_experiment_by_name(model_name) +run = client.create_run(exp.experiment_id) +``` + +### Model version + +#### Creating a model version + +```python +client = MlflowClient() +model_name = '<your_model_name>' +description = 'Model version description' +model_version = client.create_model_version(model_name, source="", description=description) +``` + +**Notes** + +- Argument `run_id` is ignored. Every model version behaves as a Candidate/Run. Creating a mode version from a run is not yet supported. +- Argument `source` is ignored. GitLab will create a package location for the model version files. +- Argument `tags` is ignored. +- Argument `run_link` is ignored. +- Argument `await_creation_for` is ignored. + +#### Updating a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +description = 'New description' +client.update_model_version(model_name, version, description=description) +``` + +#### Fetching a model version + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +client.get_model_version(model_name, version) +``` + +#### Getting latest versions of a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +client.get_latest_versions(model_name) +``` + +**Notes** + +- Argument `stages` is ignored. +- Versions are ordered by last created. + +#### Logging metrics and parameters to a model version + +Every model version is also a candidate/run, allowing users to log parameters +and metrics. The run ID can either be found at the Model version page in GitLab, +or by using the MLflow client: + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +model_version = client.get_model_version(model_name, version) +run_id = model_version.run_id + +# Your training code + +client.log_metric(run_id, '<metric_name>', '<metric_value>') +client.log_param(run_id, '<param_name>', '<param_value>') +client.log_batch(run_id, metric_list, param_list, tag_list) +``` + +#### Logging artifacts to a model version + +GitLab creates a package that can be used by the MLflow client to upload files. + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +model_version = client.get_model_version(model_name, version) +run_id = model_version.run_id + +# Your training code + +client.log_artifact(run_id, '<local/path/to/file.txt>', artifact_path="") +client.log_figure(run_id, figure, artifact_file="my_plot.png") +client.log_dict(run_id, my_dict, artifact_file="my_dict.json") +client.log_image(run_id, image, artifact_file="image.png") +``` + +Artifacts will then be available under `https/<your project>/-/ml/models/<model_id>/versions/<version_id>`. + +#### Linking a model version to a CI/CD job + +Similar to candidates, it is also possible to link a model version to a CI/CD job: + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +model_version = client.get_model_version(model_name, version) +run_id = model_version.run_id + +# Your training code + +if os.getenv('GITLAB_CI'): + client.set_tag(model_version.run_id, 'gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID')) +``` + ## Supported MLflow client methods and caveats GitLab supports these methods from the MLflow client. Other methods might be supported but were not -tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). +tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). The MlflowClient counterparts +of the methods below are also supported with the same caveats. | Method | Supported | Version Added | Comments | |--------------------------|------------------|----------------|-------------------------------------------------------------------------------------| @@ -102,9 +271,23 @@ tested. More information can be found in the [MLflow Documentation](https://www. | `update_run` | Yes | 15.11 | | | `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. | +Other MLflowClient methods: + +| Method | Supported | Version added | Comments | +|---------------------------|------------------|---------------|--------------------------------------------------| +| `create_registered_model` | Yes with caveats | 16.8 | [See notes](#creating-a-model) | +| `get_registered_model` | Yes | 16.8 | | +| `delete_registered_model` | Yes | 16.8 | | +| `update_registered_model` | Yes | 16.8 | | +| `create_model_version` | Yes with caveats | 16.8 | [See notes](#creating-a-model-version) | +| `get_model_version` | Yes | 16.8 | | +| `get_latest_versions` | Yes with caveats | 16.8 | [See notes](#getting-latest-versions-of-a-model) | +| `update_model_version` | Yes | 16.8 | | +| `create_registered_model` | Yes | 16.8 | | +| `create_registered_model` | Yes | 16.8 | | + ## Limitations -- The API GitLab supports is the one defined at MLflow version 1.28.0. -- API endpoints not listed above are not supported. +- The API GitLab supports is the one defined at MLflow version 2.7.1. +- MLflow client methods not listed above are not supported. - During creation of experiments and runs, ExperimentTags are stored, even though they are not displayed. -- MLflow Model Registry is not supported. diff --git a/doc/user/project/ml/model_registry/index.md b/doc/user/project/ml/model_registry/index.md new file mode 100644 index 00000000000..492ec9940ab --- /dev/null +++ b/doc/user/project/ml/model_registry/index.md @@ -0,0 +1,79 @@ +--- +stage: ModelOps +group: MLOps +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Model registry **(FREE ALL EXPERIMENT)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9423) in GitLab 16.8 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. To enable the feature, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `model_registry`. + +NOTE: +Model registry is an [Experiment](../../../../policy/experiment-beta-support.md). [Provide feedback](https://gitlab.com/groups/gitlab-org/-/epics/9423). + +Model registry allows data scientists and developers to manage their machine learning +models, along with all metadata associated with their creation: parameters, performance +metrics, artifacts, logs and more. For the full list of currently supported features, +see [epic 9423](https://gitlab.com/groups/gitlab-org/-/epics/9423). + +## Access the model registry + +To set the model registry [visibility level](../../../public_access.md) to public, private or disabled: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Under **Model registry**, ensure the toggle is on and select who you want to have access. + Users must have +at least the [Reporter role](../../../permissions.md#roles) to modify or delete models and model versions. + +## Exploring models, model versions and model candidates + +Model registry can be accessed on `https/<your-project>-/ml/models`. + +## Creating machine learning models and model versions + +Models and model versions can be created using the [MLflow](https://www.mlflow.org/docs/latest/tracking.html) client compatibility. +See [MLflow client compatibility](../experiment_tracking/mlflow_client.md#model-registry) on how to +create and manage models and model versions. + +## Upload files, log metrics, log parameters to a model version + +Files can either be uploaded to a model version using: + +- The package registry, where a model version is associated to a package of name `<model_name>/<model_version>`. +- The MLflow client compatibility. [View details](../experiment_tracking/mlflow_client.md#logging-artifacts-to-a-model-version). + +Users can log metrics and a parameters of a model version through the MLflow client compatibility, [see details](../experiment_tracking/mlflow_client.md#logging-metrics-and-parameters-to-a-model-version) + +## Link a model version to a CI/CD job + +When creating a model version through a GitLab CI/CD job, you can link the model +version to the job, giving easy access to the job's logs, merge request, and pipeline. +This can be done through the MLflow client compatibility. [View details](../experiment_tracking/mlflow_client.md#linking-a-model-version-to-a-cicd-job). + +## Model versions and semantic versioning + +The version of a model version in GitLab must follow [Semantic Version specification](https://semver.org/). +Using semantic versioning facilitates model deployment, by communicating which +if a new version can be deployed without changes to the application: + +- A change in the major component signifies a breaking change in the model, and that the application + that consumes the model must be updated to properly use this new version. + A new algorithm or the addition of a mandatory feature column are examples of breaking + changes that would require a bump at the major component. + +- A change in the minor component signifies a non-breaking change, and that the + consumer can safely use the new version without breaking, although it might + need to be updated to use its new functionality. For example, adding a non-mandatory + feature column to the model is a minor bump, because when that feature is not passed, + it will still work. + +- A change in the patch component means that a new version is out that does not + require any action by the application. For example, a daily retrain of the + model does not change the feature set or how the application consumes the + model version. Auto updating to a new patch is a safe update. + +## Related topics + +- Development details, feedback, and feature requests in [epic 9423](https://gitlab.com/groups/gitlab-org/-/epics/9423). diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index b280a2645c5..d41825af613 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Organize work with projects **(FREE ALL)** 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 4d8675b104d..5f55aca93b0 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 @@ -1,8 +1,7 @@ --- -type: concepts stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages DNS records **(FREE ALL)** 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 1c2b342f5d3..345a30da198 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 @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages custom domains **(FREE ALL)** @@ -273,7 +273,7 @@ meet these requirements. **Do not** open certificates or encryption keys in regular text editors. Always use code editors (such as -Sublime Text, Atom, Dreamweaver, Brackets, etc). +Sublime Text, Dreamweaver, Brackets, etc). ## Force HTTPS for GitLab Pages websites 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 3d9fe4b04e9..6ccd3033b57 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 @@ -1,9 +1,8 @@ --- -type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages Let's Encrypt certificates **(FREE ALL)** @@ -43,7 +42,7 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. Turn on the **Automatic certificate management using Let's Encrypt** toggle. @@ -70,7 +69,7 @@ associated Pages domain. GitLab also renews it automatically. 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. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). 1. If you're still getting the same error: @@ -85,7 +84,7 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Next to the domain name, select **Remove**. 1. [Add the domain again, and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index f42fdf4fc40..50ccc885bcb 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -1,8 +1,7 @@ --- -type: concepts stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages SSL/TLS certificates **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 90fc1a72eb3..07b400710f0 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages website from a CI/CD template **(FREE ALL)** 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 e3b3b99b8e1..e3c374eaacc 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 @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages website from a forked sample project **(FREE ALL)** 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 545fc6a568b..9de2703b82b 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create a GitLab Pages website from scratch **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index fe073fe6de7..b931d2d3911 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages website from a project template **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 8fa927bd61c..25f91880d5a 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages deployment for a static site **(FREE ALL)** @@ -34,7 +34,7 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. A **Get Started with Pages** form appears. If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index ec511ee0a5f..e9e8d5d69de 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages default domain names and URLs **(FREE ALL)** diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 418c97c9433..d658a09e760 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -2,7 +2,7 @@ description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages **(FREE ALL)** @@ -154,3 +154,106 @@ cookies manually with JavaScript. By default, every project in a group shares the same domain, for example, `group.gitlab.io`. This means that cookies are also shared for all projects in a group. To ensure each project uses different cookies, enable the Pages [unique domains](introduction.md#enable-unique-domains) feature for your project. + +## Create multiple deployments **(PREMIUM ALL EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [Experiment](../../../policy/experiment-beta-support.md) [with a flag](../../feature_flags.md) named `pages_multiple_versions_setting`, disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +an administrator can [enable the feature flag](../../../administration/feature_flags.md) named +`pages_multiple_versions_setting`. On GitLab.com, this feature is not available. This feature is not ready for production use. + +Use the [`pages.path_prefix`](../../../ci/yaml/index.md#pagespagespath_prefix) CI/CD option to configure a prefix for the GitLab Pages URL. A prefix allows you +to differentiate between multiple GitLab Pages deployments. + +Multiple GitLab Pages deployments (pages created with a `path_prefix`) count toward your [storage](../../../user/usage_quotas.md) usage. + +### Enable multiple deployments + +To enable multiple GitLab Pages deployments: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Deploy > Pages**. +1. Select **Use multiple deployments**. + +### Path clash + +`pages.path_prefix` can take dynamic values from [CI/CD variables](../../../ci/variables/index.md) +that can create pages deployments which could clash with existing paths in your site. +For example, given an existing GitLab Pages site with the following paths: + +```plaintext +/index.html +/documents/index.html +``` + +If a `pages.path_prefix` is `documents`, that version will override the existing path. +In other words, `https://namespace.gitlab.io/project/documents/index.html` will point to the +`/index.html` on the `documents` deployment of the site, instead of `documents/index.html` of the +`main` deployment of the site. + +Mixing [CI/CD variables](../../../ci/variables/index.md) with other strings can reduce the path clash +possibility. For example: + +```yaml +pages: + stage: deploy + script: + - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}" + variables: + PAGES_PREFIX: "" # No prefix by default (master) + pages: + path_prefix: "$PAGES_PREFIX" + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run on default branch (with default PAGES_PREFIX) + - if: $CI_COMMIT_BRANCH == "staging" # Run on master (with default PAGES_PREFIX) + variables: + PAGES_PREFIX: '_stg' # Prefix with _stg for the staging branch + - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Conditionally change the prefix for Merge Requests + when: manual # Run pages manually on Merge Requests + variables: + PAGES_PREFIX: 'mr$CI_MERGE_REQUEST_IID' # Prefix with the mr<iid>, like `mr123` +``` + +Some other examples of mixing [variables](../../../ci/variables/index.md) with strings for dynamic prefixes: + +- `pages.path_prefix: '__$CI_COMMIT_REF_SLUG'`: Branch or tag name prefixed with `__`, like `__branch-name`. +- `pages.path_prefix: '-${CI_MERGE_REQUEST_IID}-'`: Merge request number prefixed and suffixed with `-`, like `-123-`. + +### Use multiple deployments to create pages environments + +You can use multiple GitLap Pages deployments to create a new [environment](../../../ci/environments/index.md). +For example: + +```yaml +pages: + stage: deploy + script: + - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}" + variables: + PAGES_PREFIX: "" # no prefix by default (master) + pages: + path_prefix: "$PAGES_PREFIX" + environment: + name: "Pages ${PAGES_PREFIX}" + url: "${CI_PAGES_URL}/${PAGES_PREFIX}" + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == "staging" # ensure to run on master (with default PAGES_PREFIX) + variables: + PAGES_PREFIX: '_stg' # prefix with _stg for the staging branch + - if: $CI_PIPELINE_SOURCE == "merge_request_event" # conditionally change the prefix on Merge Requests + when: manual # run pages manually on Merge Requests + variables: + PAGES_PREFIX: 'mr$CI_MERGE_REQUEST_IID' # prefix with the mr<iid>, like `mr123` +``` + +With this configuration, users will have the access to each GitLab Pages deployment through the UI. +When using [environments](../../../ci/environments/index.md) for pages, all pages environments are +listed on the project environment list. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 664c80e0351..42a05e0b1bb 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages settings **(FREE ALL)** @@ -65,7 +65,7 @@ You can configure redirects for your site using a `_redirects` file. For more in To remove your pages: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Select **Remove pages**. ## Subdomains of subdomains @@ -100,7 +100,7 @@ By default, every project in a group shares the same domain, for example, `group To ensure your project uses a unique Pages domain, enable the unique domains feature for the project: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Select the **Use unique domain** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 26f28be72ae..1c7aa0f182c 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages access control **(FREE ALL)** @@ -15,8 +15,9 @@ on your GitLab instance. When enabled, only authenticated <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v=tSPAr5mQYc8). -1. Navigate to your project's **Settings > General** and expand **Visibility, project features, permissions**. - +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Toggle the **Pages** button to enable the access control. If you don't see the toggle button, that means it isn't enabled. Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 39d80517bc7..4f8549c1589 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -3,7 +3,7 @@ description: 'Learn how to configure the build output folder for the most common static site generators' stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages public folder **(FREE ALL)** diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index ff1f138e5b7..d13f30060e7 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages redirects **(FREE ALL)** diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index f8f44d344d1..0377ab389a5 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected branches **(FREE ALL)** @@ -43,6 +43,9 @@ When a branch is protected, the default behavior enforces these restrictions on for that branch at the project level are ignored. All other protections continue to use project level settings. +You can implement a [scan result policy](../application_security/policies/scan-result-policies.md#approval_settings) +to prevent protected branches being unprotected or deleted. + ### When a branch matches multiple rules When a branch matches multiple rules, the **most permissive rule** determines the @@ -128,7 +131,7 @@ specific branch is configured with **Allowed to force push** settings at both th group and project levels, the **Allowed to force push** setting at the _project_ level is ignored in favor of the group level setting. -Prerequisite: +Prerequisites: - You must have the Owner role in the group. @@ -153,7 +156,7 @@ If more than one rule applies to a branch, the _most permissive_ rule controls how the branch behaves. For merge controls to work properly, set **Allowed to push and merge** to a broader set of users than **Allowed to merge**. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role. @@ -264,7 +267,7 @@ Deploy keys are not available in the **Allowed to merge** dropdown list. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 [with a flag](../../administration/feature_flags.md) named `allow_force_push_to_protected_branches`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. Feature flag `allow_force_push_to_protected_branches` removed. -You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to +You can allow [force pushes](../../topics/git/git_rebase.md#force-pushing) to protected branches. To protect a new branch and enable force push: @@ -360,6 +363,10 @@ Thus, they can skip merge request approval rules, Code Owners included. The permission to merge or push to protected branches defines whether or not a user can run CI/CD pipelines and execute actions on jobs. +Because [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) run on the source +branch, a pipeline isn't created if the user opening a merge request does not have permission to merge +or push to the source branch. + See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches) for details about the pipelines security model. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index b312acd49f4..104433be2dc 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected tags **(FREE ALL)** @@ -125,7 +125,7 @@ To allow a deploy key to create a protected tag: You can manually delete protected tags with the GitLab API, or the GitLab user interface. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role in your project. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 6c89e09bd47..a129e6f6cd0 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Push options **(FREE ALL)** diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 16967a3a46e..be119275cd3 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab quick actions **(FREE ALL)** @@ -55,7 +54,6 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | | `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | | `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | -| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. | | `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | | `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | | `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line created a specific type of to-do item notification. | @@ -88,6 +86,7 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md). | +| `/react :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from `/award` in GitLab 16.7. `/award` is still available as an aliased command. | | `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | | `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 17ea0e3f694..6c31b2ad5d3 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Releases **(FREE ALL)** @@ -75,7 +75,7 @@ Prerequisites: To create a release in the Releases page: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Releases** and select **New release**. +1. Select **Deploy > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown list, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error. @@ -216,7 +216,7 @@ To delete a release, use either the In the UI: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Releases**. +1. Select **Deploy > Releases**. 1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. @@ -321,7 +321,7 @@ To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with the Maintainer role. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. +1. Select **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Select **Expand** to see the deploy freeze table. 1. Select **Add deploy freeze** to open the deploy freeze modal. @@ -360,7 +360,7 @@ Releases can be made accessible to non-project members while keeping repository- projects that use releases as a way to give access to new versions of software but do not want the source code to be public. -To make releases available publicly, set the following [project settings](../settings/index.md#configure-project-features-and-permissions): +To make releases available publicly, set the following [project settings](../settings/project_features_permissions.md#configure-project-features-and-permissions): - Repository is enabled and set to **Only Project Members** - Releases is enabled and set to **Everyone With Access** diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index 7b5e808641c..fc21e157753 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release CI/CD examples diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 9daa6705ad8..1770b7b0931 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -29,7 +29,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description \ ## Install the `release-cli` for the Shell executor **(FREE ALL)** > - [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/gitlab-org/release-cli/-/packages). +> - [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/gitlab-org/release-cli/-/packages). When you use a runner with the Shell executor, you can download and install the `release-cli` manually for your [supported OS and architecture](https://release-cli-downloads.s3.amazonaws.com/latest/index.html). @@ -37,7 +37,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ### Install on Unix/Linux -1. Download the binary for your system from the GitLab Package Registry. +1. Download the binary for your system from the GitLab package registry. For example, if you use an amd64 system: ```shell diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md index 7f8624fc520..83865b95c1f 100644 --- a/doc/user/project/releases/release_evidence.md +++ b/doc/user/project/releases/release_evidence.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release evidence **(FREE ALL)** diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index d26ca87e384..c74ebaab89d 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release fields @@ -182,7 +182,7 @@ to store any artifacts from a release or tag pipeline, that can also be used for attaching binary files to an individual release entry. You basically need to: -1. [Push the artifacts to the Generic Package Registry](../../packages/generic_packages/index.md#publish-a-package-file). +1. [Push the artifacts to the Generic package registry](../../packages/generic_packages/index.md#publish-a-package-file). 1. [Attach the package link to the release](#links). The following example generates release assets, publishes them diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index 6bbc0b8123a..cf46774741c 100644 --- a/doc/user/project/remote_development/connect_machine.md +++ b/doc/user/project/remote_development/connect_machine.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Connect a remote machine to the Web IDE **(FREE ALL BETA)** diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 8ca505be500..ac8d7102e40 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Remote development **(FREE ALL BETA)** diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index fdc822ca49f..4fc83cf77ea 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: concepts, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Default branch **(FREE ALL)** @@ -68,8 +67,7 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. @@ -128,8 +126,7 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). @@ -146,8 +143,7 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand the **Default branch** section. 1. Clear the **Allow owners to manage default branch protection per group** checkbox. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 3640beebdfb..0a0cbcbb9c8 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Branches **(FREE ALL)** @@ -289,7 +289,8 @@ To do this: ## Configure rules for target branches **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127115) in GitLab 16.4 [with a flag](../../../../administration/feature_flags.md) named `target_branch_rules_flag`. Enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127115) in GitLab 16.4 [with a flag](../../../../administration/feature_flags.md) named `target_branch_rules_flag`. Enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136431) in GitLab 16.7. Some projects use multiple long-term branches for development, like `develop` and `qa`. In these projects, you might want to keep `main` as the default branch, but expect diff --git a/doc/user/project/repository/code_suggestions/index.md b/doc/user/project/repository/code_suggestions/index.md index b44e26f8daf..9e52da6068c 100644 --- a/doc/user/project/repository/code_suggestions/index.md +++ b/doc/user/project/repository/code_suggestions/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Suggestions **(FREE ALL BETA)** @@ -17,16 +16,18 @@ Beta users should read about the [known limitations](#known-limitations). We loo Write code more efficiently by using generative AI to suggest code while you're developing. -Code Suggestions supports two distinct types of interactions: +With Code Suggestions, you get: - Code Completion, which suggests completions the current line you are typing. These suggestions are usually low latency. - Code Generation, which generates code based on a natural language code comment block. Generating code can exceed multiple seconds. +## Start using Code Suggestions + GitLab Duo Code Suggestions are available: -- On [self-managed](self_managed.md) and [SaaS](saas.md). +- On [self-managed](self_managed.md) and [SaaS](saas.md). View these pages to get started. - In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. -- In the GitLab WebIDE. +- In the GitLab Web IDE. <div class="video-fallback"> <a href="https://youtu.be/wAYiy05fjF0">View how to setup and use GitLab Duo Code Suggestions</a>. @@ -36,34 +37,7 @@ GitLab Duo Code Suggestions are available: </figure> During Beta, usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). -Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). As Code Suggestions matures to General Availibility it will be governed by our [AI Functionality Terms](https://about.gitlab.com/handbook/legal/ai-functionality-terms/). - -## Use Code Suggestions - -Prerequisites: - -- Code Suggestions must be enabled for [SaaS](saas.md#enable-code-suggestions) or for [self-managed](self_managed.md#enable-code-suggestions-on-self-managed-gitlab). -- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). - -To use Code Suggestions: - -1. Author your code. As you type, suggestions are displayed. Code Suggestions, depending on the cursor position, either provides code snippets or completes the current line. -1. Describe the requirements in natural language. Be concise and specific. Code Suggestions generates functions and code snippets as appropriate. -1. To accept a suggestion, press <kbd>Tab</kbd>. -1. To ignore a suggestion, keep typing as you usually would. -1. To explicitly reject a suggestion, press <kbd>esc</kbd>. - -Things to remember: - -- AI is non-deterministic, so you may not get the same suggestion every time with the same input. -- Just like product requirements, writing clear, descriptive, and specific tasks results in quality generated code. - -### Progressive enhancement - -This feature is designed as a progressive enhancement to developer's IDEs. -Code Suggestions offer a completion if a suitable recommendation is provided to the user in a timely matter. -In the event of a connection issue or model inference failure, the feature gracefully degrades. -Code Suggestions do not prevent you from writing code in your IDE. +Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). As Code Suggestions matures to General Availability it will be governed by our [AI Functionality Terms](https://about.gitlab.com/handbook/legal/ai-functionality-terms/). ## Supported languages @@ -168,6 +142,13 @@ However, Code Suggestions may generate suggestions that are: - Insecure code - Offensive or insensitive +## Progressive enhancement + +This feature is designed as a progressive enhancement to developer's IDEs. +Code Suggestions offer a completion if a suitable recommendation is provided to the user in a timely matter. +In the event of a connection issue or model inference failure, the feature gracefully degrades. +Code Suggestions do not prevent you from writing code in your IDE. + ## Feedback Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). diff --git a/doc/user/project/repository/code_suggestions/saas.md b/doc/user/project/repository/code_suggestions/saas.md index ac64aba4335..1af5eef585c 100644 --- a/doc/user/project/repository/code_suggestions/saas.md +++ b/doc/user/project/repository/code_suggestions/saas.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Suggestions on GitLab SaaS **(FREE SAAS BETA)** @@ -20,12 +19,11 @@ Learn about [data usage when using Code Suggestions](index.md#code-suggestions-d ## Enable Code Suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. -You must enable Code Suggestions for both your user account and your group: - -- [Enable Code Suggestions for all group members](../../../group/manage.md#enable-code-suggestions). (You must be a group owner). -- [Enable Code Suggestions for your own account](../../../profile/preferences.md#enable-code-suggestions). +A group owner must +[enable Code Suggestions for your top-level group](../../../group/manage.md#enable-code-suggestions-for-a-group). NOTE: If you are having issues enabling Code Suggestions, view the @@ -35,7 +33,31 @@ If you are having issues enabling Code Suggestions, view the Prerequisites: -- Ensure Code Suggestions is enabled for your user and group. -- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). +- You must have configured Code Suggestions in a + [supported IDE editor extension](index.md#supported-editor-extensions). +- Code Suggestions must be enabled for: + - [The top-level group](../../../group/manage.md#enable-code-suggestions-for-a-group). + - [Your own account](../../../profile/preferences.md#enable-code-suggestions), if your + account is not part of the percentage rollout. + +To use Code Suggestions: + +1. Determine if your user account is part of the percentage rollout. See + [Enable Code Suggestions](../../../profile/preferences.md#enable-code-suggestions) + for more information. +1. Author your code. As you type, suggestions are displayed. + Code Suggestions provide code snippets or complete the current line, depending on the cursor position. +1. Describe the requirements in natural language. Be concise and specific. Code Suggestions generates functions and code snippets as appropriate. +1. To accept a suggestion, press <kbd>Tab</kbd>. +1. To ignore a suggestion, keep typing as you usually would. +1. To explicitly reject a suggestion, press <kbd>Esc</kbd>. + +Things to remember: + +- AI is non-deterministic, so you may not get the same suggestion every time with the same input. +- Just like product requirements, writing clear, descriptive, and specific tasks results in quality generated code. + +## Disable Code Suggestions -[Use Code Suggestions](index.md#use-code-suggestions). +Individual users can disable Code Suggestions by disabling the feature in their +[installed IDE editor extension](index.md#supported-editor-extensions). diff --git a/doc/user/project/repository/code_suggestions/self_managed.md b/doc/user/project/repository/code_suggestions/self_managed.md index fd363e56021..26850bc8b5f 100644 --- a/doc/user/project/repository/code_suggestions/self_managed.md +++ b/doc/user/project/repository/code_suggestions/self_managed.md @@ -1,11 +1,10 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Code Suggestions on self-managed GitLab **(PREMIUM SELF BETA)** +# Code Suggestions on self-managed GitLab **(SELF BETA)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta) on self-managed GitLab. > - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. @@ -15,28 +14,30 @@ type: index, reference Write code more efficiently by using generative AI to suggest code while you're developing. GitLab Duo Code Suggestions are available on GitLab Enterprise Edition. -Cloud licensing is required for Premium and Ultimate subscription tiers. Code Suggestions are not available for GitLab Community Edition. -WARNING: -In GitLab 16.3 and later, only Premium and Ultimate customers can participate in the free trial of Code Suggestions on self-managed GitLab. +> In GitLab 16.3 and later, to participate in the free trial of Code Suggestions on self-managed GitLab, you must: +> +> - Be a Premium or Ultimate customer. +> - Have activated cloud licensing. Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). Learn about [data usage when using Code Suggestions](index.md#code-suggestions-data-usage). -## Enable Code Suggestions on self-managed GitLab **(FREE SELF)** +## Enable Code Suggestions on self-managed GitLab -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. When you enable Code Suggestions for your self-managed instance, you: - Agree to the [GitLab testing agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). - Acknowledge that GitLab sends data from the instance, including personal data, to GitLab.com infrastructure. -How you enable Code Suggestions differs depending on your version of GitLab. +How you enable Code Suggestions for your instance differs depending on your version of GitLab. -### GitLab 16.3 and later +### GitLab 16.3 and later **(PREMIUM)** Prerequisites: @@ -46,9 +47,8 @@ Prerequisites: To enable Code Suggestions for your self-managed GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Code Suggestions** and select **Turn on Code Suggestions for this instance**. In GitLab 16.3, you do not need to enter anything into the **Personal access token** field. In GitLab 16.4 and later, there is no **Personal access token** field. @@ -65,6 +65,9 @@ The users in your instance can now use Code Suggestions. ### GitLab 16.2 and earlier +FLAG: +On self-managed GitLab 16.0 and earlier, GitLab Duo Code Suggestions is not available. To use this feature, you must have GitLab 16.1 or later. For optimal performance and full feature access, you should upgrade to GitLab 16.3 or later, which supports cloud licensing. + Prerequisites: - You are an administrator. @@ -95,9 +98,8 @@ To enable Code Suggestions for your GitLab SaaS account: To enable Code Suggestions for your self-managed GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Code Suggestions** and: - Select **Turn on Code Suggestions for this instance**. - In **Personal access token**, enter your GitLab SaaS personal access token. @@ -126,14 +128,14 @@ If your GitLab instance uses an HTTP proxy server to access the internet, ensure the server is configured to allow outbound connections, including the [`gitlab_workhorse` environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html). -### Update GitLab +### Upgrade GitLab In GitLab 16.3 and later, GitLab is enforcing the cloud licensing requirement for Code Suggestions: -- The Premium and Ultimate subscription tiers support cloud Licensing. +- The Premium and Ultimate subscription tiers support cloud licensing. - GitLab Free does not have cloud licensing support. -If you have a GitLab Free subscription and update to GitLab 16.3 or later, +If you have a GitLab Free subscription and upgrade to GitLab 16.3 or later, to continue having early access to Code Suggestions, you must: 1. Have a [subscription that supports cloud licensing](https://about.gitlab.com/pricing/). @@ -144,8 +146,8 @@ to continue having early access to Code Suggestions, you must: You must [manually synchronize your subscription](../../../../subscriptions/self_managed/index.md#manually-synchronize-your-subscription-details) if either: -- You have already updated to GitLab 16.3 and have just bought a Premium or Ultimate tier subscription. -- You already have a Premium or Ultimate tier subscription and have just updated to GitLab 16.3. +- You have already upgraded to GitLab 16.3 and have just bought a Premium or Ultimate tier subscription. +- You already have a Premium or Ultimate tier subscription and have just upgraded to GitLab 16.3. Without the manual synchronization, it might take up to 24 hours to active Code Suggestions on your instance. @@ -153,10 +155,22 @@ Without the manual synchronization, it might take up to 24 hours to active Code Prerequisites: -- Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). -- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). +- You must have a [supported IDE editor extension](index.md#supported-editor-extensions). +- Code Suggestions must be enabled [for your instance](self_managed.md#enable-code-suggestions-on-self-managed-gitlab). + +To use Code Suggestions: + +1. Author your code. As you type, suggestions are displayed. + Code Suggestions provide code snippets or complete the current line, depending on the cursor position. +1. Describe the requirements in natural language. Be concise and specific. Code Suggestions generates functions and code snippets as appropriate. +1. To accept a suggestion, press <kbd>Tab</kbd>. +1. To ignore a suggestion, keep typing as you usually would. +1. To explicitly reject a suggestion, press <kbd>Esc</kbd>. -[Use Code Suggestions](index.md#use-code-suggestions). +Things to remember: + +- AI is non-deterministic, so you may not get the same suggestion every time with the same input. +- Just like product requirements, writing clear, descriptive, and specific tasks results in quality generated code. ### Data privacy @@ -170,3 +184,8 @@ The Code Suggestions service then securely returns an AI-generated code suggesti Neither GitLab nor Google Vertex AI Codey APIs have any visibility into a self-managed customer's code other than what is sent to generate the code suggestion. + +## Disable Code Suggestions + +Individual users can disable Code Suggestions by disabling the feature in their +[installed IDE editor extension](index.md#supported-editor-extensions). diff --git a/doc/user/project/repository/code_suggestions/troubleshooting.md b/doc/user/project/repository/code_suggestions/troubleshooting.md index 86400ea8860..c18ea2dd26b 100644 --- a/doc/user/project/repository/code_suggestions/troubleshooting.md +++ b/doc/user/project/repository/code_suggestions/troubleshooting.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Code Suggestions **(FREE ALL BETA)** @@ -11,12 +10,12 @@ When working with GitLab Duo Code Suggestions, you might encounter the following ## Code Suggestions aren't displayed -If Code Suggestions are not displayed, try the following troubleshooting steps. +If Code Suggestions are not displayed, and you have [installed a supported IDE extension](index.md#supported-editor-extensions), try the following troubleshooting steps. In GitLab, ensure Code Suggestions is enabled: - [For your user account](../../../profile/preferences.md#enable-code-suggestions). -- [For *all* top-level groups your account belongs to](../../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. +- [For **all** top-level groups your account belongs to](../../../group/manage.md#enable-code-suggestions-for-a-group). If you don't have a role that lets you view the top-level group's settings, contact a group owner. ### Code Suggestions not displayed in VS Code or GitLab WebIDE diff --git a/doc/user/project/repository/csv.md b/doc/user/project/repository/csv.md index fcf8d538431..8f0596bddeb 100644 --- a/doc/user/project/repository/csv.md +++ b/doc/user/project/repository/csv.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CSV files **(FREE ALL)** diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 5dd8ad39889..a2084d8a157 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File finder **(FREE ALL)** diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index c71c89b68c3..a1efb7b1ea6 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -1,10 +1,10 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Project forking workflow **(FREE ALL)** +# Forks **(FREE ALL)** Whenever possible, it's recommended to work in a common Git repository and use branching strategies to manage your work. However, @@ -69,6 +69,10 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 16.0. Feature flag `synchronize_fork` removed. +Prerequisite: + +- The fork must be created from an [unprotected branch](../protected_branches.md) in upstream repository. + To update your fork from the GitLab UI: 1. On the left sidebar, select **Search or go to**. @@ -78,7 +82,7 @@ To update your fork from the GitLab UI: information box to determine if your fork is ahead, behind, or both. In this example, the fork is behind the upstream repository: -  +  1. If your fork is **ahead** of the upstream repository, select **Create merge request** to propose adding your fork's changes to the upstream repository. diff --git a/doc/user/project/repository/geojson.md b/doc/user/project/repository/geojson.md index eb66a667deb..e454387b7f1 100644 --- a/doc/user/project/repository/geojson.md +++ b/doc/user/project/repository/geojson.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GeoJSON files **(FREE ALL)** diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 3f49f1e05f2..a602638d244 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Documentation on Git file blame." --- @@ -21,48 +20,59 @@ Prerequisites: To view the blame for a file: -1. Go to your project's **Code > Repository**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Repository**. 1. Select the file you want to review. -1. In the upper-right corner, select **Blame**. +1. In the upper-right corner, select **Blame**, and go to the line you want to see. When you select **Blame**, this information is displayed: - + -If you hover over a commit in the UI, the commit's precise date and time -are shown. +To see the precise date and time of the commit, hover over the date. The vertical bar +to the left of the user avatar shows the general age of the commit. The newest +commits have a dark blue bar. As the age of the commit increases, the bar color +changes to light gray. -## Blame previous commit +### Blame previous commit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19299) in GitLab 12.7. +To see earlier revisions of a specific line: -To see earlier revisions of a specific line, select **View blame prior to this change** -until you've found the changes you're interested in viewing: - - +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Repository**. +1. Select the file you want to review. +1. In the upper-right corner, select **Blame**, and go to the line you want to see. +1. Select **View blame prior to this change** (**{doc-versions}**) + until you've found the changes you're interested in viewing. ## Associated `git` command If you're running `git` from the command line, the equivalent command is `git blame <filename>`. For example, if you want to find `blame` information -about a `README.md` file in the local directory, run the following command: +about a `README.md` file in the local directory: -```shell -git blame README.md -``` +1. Run this command `git blame README.md`. +1. If the line you want to see is not in the first page of results, press <kbd>Space</kbd> + until you find the line you want. +1. To exit out of the results, press <kbd>Q</kbd>. -The output looks similar to the following, which includes the commit time -in UTC format: +The `git blame` output in the CLI looks like this: ```shell -62e2353a (Achilleas Pipinellis 2019-07-11 14:52:18 +0300 1) [](https://gitlab.com/gitlab-com/gitlab-docs/commits/master) -fb0fc7d6 (Achilleas Pipinellis 2016-11-07 22:21:22 +0100 2) -^764ca75 (Connor Shea 2016-10-05 23:40:24 -0600 3) # GitLab Documentation -^764ca75 (Connor Shea 2016-10-05 23:40:24 -0600 4) -0e62ed6d (Mike Jang 2019-11-26 21:44:53 +0000 5) This project hosts the repository used to generate the GitLab -0e62ed6d (Mike Jang 2019-11-26 21:44:53 +0000 6) documentation website and deployed to https://docs.gitlab.com. It uses the +58233c4f1054c (Dan Rhodes 2022-05-13 07:02:20 +0000 1) ## Contributor License Agreement +b87768f435185 (Jamie Hurewitz 2017-10-31 18:09:23 +0000 2) +8e4c7f26317ff (Brett Walker 2023-10-20 17:53:25 +0000 3) Contributions to this repository are subject to the +58233c4f1054c (Dan Rhodes 2022-05-13 07:02:20 +0000 4) ``` -## File blame through the API +The output includes: + +- The SHA of the commit. +- The name of the committer. +- The date and time in UTC format. +- The line number. +- The contents of the line. + +## Related topics -You can also get this information over the [Git file blame REST API](../../../api/repository_files.md#get-file-blame-from-repository). +- [Git file blame REST API](../../../api/repository_files.md#get-file-blame-from-repository). diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index db50e6d185e..45c59a02f8b 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/img/file_blame_output_v12_6.png b/doc/user/project/repository/img/file_blame_output_v12_6.png Binary files differdeleted file mode 100644 index c1186429917..00000000000 --- a/doc/user/project/repository/img/file_blame_output_v12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_blame_output_v16_6.png b/doc/user/project/repository/img/file_blame_output_v16_6.png Binary files differnew file mode 100644 index 00000000000..5eff95541fe --- /dev/null +++ b/doc/user/project/repository/img/file_blame_output_v16_6.png diff --git a/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png b/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png Binary files differdeleted file mode 100644 index 2da9e28c84f..00000000000 --- a/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png +++ /dev/null diff --git a/doc/user/project/repository/img/update-fork_v15_11.png b/doc/user/project/repository/img/update-fork_v15_11.png Binary files differdeleted file mode 100644 index 244868d80ae..00000000000 --- a/doc/user/project/repository/img/update-fork_v15_11.png +++ /dev/null diff --git a/doc/user/project/repository/img/update-fork_v16_6.png b/doc/user/project/repository/img/update-fork_v16_6.png Binary files differnew file mode 100644 index 00000000000..59901db6a49 --- /dev/null +++ b/doc/user/project/repository/img/update-fork_v16_6.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 96b92a057cf..dd8ee61f6ae 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository **(FREE ALL)** @@ -23,9 +23,25 @@ To create a repository, you can: You can add files to a repository: - When you create a project. -- After you create a project: - - By using [the web editor](web_editor.md). - - From the command line. +- After you create a project, by using: + - [The web editor](web_editor.md#upload-a-file). + - [The UI](#add-a-file-from-the-ui). + - [The command line](../../../topics/git/git_add.md). + +### Add a file from the UI + +You can upload a file from the GitLab UI. + +<!-- Original source for this list: doc/user/project/repository/web_editor.md#upload-a-file --> +<!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> + +1. On the left sidebar, select **Search or go to** and find your project. +1. Go to the directory where you want to upload the file. +1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). +1. Select **Upload file**. ## Commit changes to a repository @@ -80,7 +96,7 @@ prompted to open Xcode. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. All projects can be cloned into Visual Studio Code from the GitLab user interface, but you -can also install the [GitLab Workflow VS Code extension](vscode.md) to clone from +can also install the [GitLab Workflow VS Code extension](../../../editor_extensions/visual_studio_code/index.md) to clone from Visual Studio Code: - From the GitLab interface: @@ -90,7 +106,7 @@ Visual Studio Code: 1. Select a folder to clone the project into. After Visual Studio Code clones your project, it opens the folder. -- From Visual Studio Code, with the [extension](vscode.md) installed, use the +- From Visual Studio Code, with the [extension](../../../editor_extensions/visual_studio_code/index.md) installed, use the extension's [`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). ### Clone and open in IntelliJ IDEA @@ -193,8 +209,7 @@ These files can either be plain text or have the extension of a > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19515) in GitLab 12.6. -GitLab can render OpenAPI specification files. The filename -must include `openapi` or `swagger` and the extension must be `yaml`, +GitLab can render OpenAPI specification files. The file name must include `openapi` or `swagger` and the extension must be `yaml`, `yml`, or `json`. The following examples are all correct: - `openapi.yml` @@ -237,12 +252,12 @@ updated, at most, every 15 minutes. The file size includes repository files, art The size can differ slightly from one instance to another due to compression, housekeeping, and other factors. -Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md). +Administrators can set a [repository size limit](../../../administration/settings/account_and_limit_settings.md). [GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). -## Repository contributor statistics +## Repository contributor analytics -You can view a list and charts of commits made by project members in [Contributor statistics](../../analytics/contributor_statistics.md). +You can view a list and charts of commits made by project members in [Contributor analytics](../../analytics/contributor_analytics.md). ## Repository history graph @@ -259,7 +274,7 @@ When a repository path changes, GitLab handles the transition from the old location to the new one with a redirect. When you [rename a user](../../profile/index.md#change-your-username), -[change a group path](../../group/manage.md#change-a-groups-path), or [rename a repository](../settings/index.md#rename-a-repository): +[change a group path](../../group/manage.md#change-a-groups-path), or [rename a repository](../../project/working_with_projects.md#rename-a-repository): - URLs for the namespace and everything under it, like projects, are redirected to the new URLs. @@ -270,15 +285,19 @@ When you [rename a user](../../profile/index.md#change-your-username), work after a rename. - The redirects are available as long as the original path is not claimed by another group, user, or project. +- [API redirects](../../../api/rest/index.md#redirects) may need to be followed explicitly. + +After you change a path, you must update the existing URL in the following resources, +because they can't follow redirects: -WARNING: -The [CI/CD `includes` keyword](../../../ci/yaml/includes.md) can't follow project -redirects. Pipelines fail with a syntax error when configured to use `includes` -to fetch configuration from a project that is renamed or moved. +- [Include statements](../../../ci/yaml/includes.md) except [`include:component`](../../../ci/components/index.md), otherwise pipelines fail with a syntax error. CI/CD component references can follow redirects. +- Namespaced API calls that use the [encoded path](../../../api/rest/index.md#namespaced-path-encoding) instead of the numeric namespace and project IDs. +- [Docker image references](../../../ci/yaml/index.md#image). +- Variables that specify a project or namespace. ## Related topics -- [GitLab Workflow VS Code extension](vscode.md) +- [GitLab Workflow VS Code extension](../../../editor_extensions/visual_studio_code/index.md) - [Lock files and prevent change conflicts](../file_lock.md) - [Repository API](../../../api/repositories.md) - [Find files](file_finder.md) diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 2a1fc0cddf8..2e14c52d2a7 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Jupyter Notebook files **(FREE ALL)** diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 9d97f53cb43..d4ab550cb8a 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Bidirectional mirroring **(PREMIUM ALL)** @@ -45,7 +45,7 @@ To create the webhook in the downstream instance: 1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > Webhooks**. +1. Select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after a repository update: diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index b16197e45b2..34a2757bb67 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository mirroring **(FREE ALL)** @@ -107,7 +107,7 @@ While mirrors are scheduled to update automatically, you can force an immediate - The [interval, in seconds](../../../../administration/instance_limits.md#pull-mirroring-interval) for pull mirroring limits has not elapsed after its last update. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 5b3c76d982a..0a57681c90d 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pull from a remote repository **(PREMIUM ALL)** diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index e18e3631d7f..3aa4c768ebe 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Push mirroring **(FREE ALL)** diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md index a83231ceb63..57a9351e85d 100644 --- a/doc/user/project/repository/mirror/troubleshooting.md +++ b/doc/user/project/repository/mirror/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting repository mirroring **(FREE ALL)** diff --git a/doc/user/project/repository/monorepos/index.md b/doc/user/project/repository/monorepos/index.md index 144f46cd7d5..36b0521235d 100644 --- a/doc/user/project/repository/monorepos/index.md +++ b/doc/user/project/repository/monorepos/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing monorepos @@ -20,7 +20,7 @@ size. Monorepos can be large for [many reasons](https://about.gitlab.com/blog/2022/09/06/speed-up-your-monorepo-workflow-in-git/#characteristics-of-monorepos). -Large repositories pose a performance risk performance when used in GitLab, especially if a large monorepo receives many clones or pushes a day, which is common for them. +Large repositories pose a performance risk when used in GitLab, especially if a large monorepo receives many clones or pushes a day, which is common for them. Git itself has performance limitations when it comes to handling monorepos. @@ -189,7 +189,7 @@ You might experience a `fatal: the remote end hung up unexpectedly` error when a - The same large repository in parallel. You can attempt to mitigate this issue by increasing the default negotiation timeout values. For more information, see -[Configure negotiation timeouts](../../../../administration/gitaly/configure_gitaly.md#configure-negotiation-timeouts). +[Configure the negotiation timeouts](../../../../administration/settings/gitaly_timeouts.md#configure-the-negotiation-timeouts). ## Optimize your repository diff --git a/doc/user/project/repository/monorepos/observability.md b/doc/user/project/repository/monorepos/observability.md index a54b4bef9d5..9d99dac2eba 100644 --- a/doc/user/project/repository/monorepos/observability.md +++ b/doc/user/project/repository/monorepos/observability.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics for measuring monorepo performance diff --git a/doc/user/project/repository/monorepos/troubleshooting.md b/doc/user/project/repository/monorepos/troubleshooting.md new file mode 100644 index 00000000000..208464c3e0f --- /dev/null +++ b/doc/user/project/repository/monorepos/troubleshooting.md @@ -0,0 +1,98 @@ +--- +stage: Systems +group: Gitaly +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting monorepo performance + +Review these suggestions for performance problems with monorepos. + +## Slowness during `git clone` or `git fetch` + +There are a few key causes of slowness with clones and fetches. + +### High CPU utilization + +If the CPU utilization on your Gitaly nodes is high, you can also check +how much CPU is taken up from clones by [filtering on certain values](../../../../user/project/repository/monorepos/observability.md#cpu-and-memory). + +In particular, the `command.cpu_time_ms` field can indicate how +much CPU is being taken up by clones and fetches. + +In most cases, the bulk of server load is generated from `git-pack-objects` +processes, which is initiated during clones and fetches. Monorepos are often very busy +and CI/CD systems send a lot of clone and fetch commands to the server. + +High CPU utilization is a common cause of slow performance. +The following non-mutually exclusive causes are possible: + +- [Too many clones for Gitaly to handle](#cause-too-many-large-clones). +- [Poor read distribution on Gitaly Cluster](#cause-poor-read-distribution). + +#### Cause: too many large clones + +You might have too many large clones for Gitaly to handle. Gitaly can struggle to keep up +because of a number of factors: + +- The size of a repository. +- The volume of clones and fetches. +- Lack of CPU capacity. + +To help Gitaly process many large clones, you might need to reduce the burden on Gitaly servers through some optimization strategies +such as: + +- Turn on [pack-objects-cache](../../../../administration/gitaly/configure_gitaly.md#pack-objects-cache) + to reduce the work that `git-pack-objects` has to do. +- Change [Git strategy](../../../../user/project/repository/monorepos/index.md#git-strategy) + in CI/CD settings from `clone` to `fetch` or `none`. +- [Stop fetching tags](../../../../user/project/repository/monorepos/index.md#git-fetch-extra-flags), + unless your tests require them. +- [Use shallow clones](../../../../user/project/repository/monorepos/index.md#shallow-cloning) + whenever possible. + +The other option is to increase CPU capacity on Gitaly servers. + +#### Cause: poor read distribution + +You might have poor read distribution on Gitaly Cluster. + +To observe if most read traffic is going to the primary Gitaly node instead of +getting distributed across the cluster, use the +[read distribution Prometheus metric](observability.md#read-distribution). + +If the secondary Gitaly nodes aren't receiving much traffic, it might be that +the secondary nodes are perpetually out of sync. This problem is exacerbated in +a monorepo. + +Monorepos are often both large and busy. This leads to two effects. Firstly, +monorepos are pushed to often and have lots of CI jobs running. There can be +times when write operations such as deleting a branch fails a proxy call to the +secondary nodes. This triggers a replication job in Gitaly Cluster so that +the secondary node will catch up eventually. + +The replication job is essentially a `git fetch` from the secondary node to the +primary node, and because monorepos are often very large, this fetch can take a +long time. + +If the next call fails before the previous replication job completes, and this +keeps happening, you can end up in a state where your monorepo is constantly +behind in its secondaries. This leads to all traffic going to the primary node. + +One reason for these failed proxied writes is a known issue with the Git +`$GIT_DIR/packed-refs` file. The file must be locked to +remove an entry in the file, which can lead to a race condition that causes a +delete to fail when concurrent deletes happen. + +Engineers at GitLab have developed mitigations to try to batch reference deletions. + +Turn on the following [feature flags](../../../../administration/feature_flags.md) to allow GitLab to batch ref deletions. +These feature flags do not need downtime to enable. + +- `merge_request_cleanup_ref_worker_async` +- `pipeline_cleanup_ref_worker_async` +- `pipeline_delete_gitaly_refs_in_batches` +- `merge_request_delete_gitaly_refs_in_batches` + +[Epic 4220](https://gitlab.com/groups/gitlab-org/-/epics/4220) proposes to add RefTable support in GitLab, +which is considered a long-term solution. diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index d61d09301a5..fc36748a8dd 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Push rules **(PREMIUM ALL)** @@ -33,14 +33,13 @@ All projects created after you configure global push rules inherit this configuration. However, each existing project must be updated manually, using the process described in [Override global push rules per project](#override-global-push-rules-per-project). -Prerequisite: +Prerequisites: - You must be an administrator. To create global push rules: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Push Rules**. 1. Expand **Push rules**. 1. Set the rule you want. @@ -80,6 +79,19 @@ Use these rules for your commit messages. The word boundary character (`\b`) prevents false negatives, because Git adds a newline character (`\n`) to the end of the commit message. + Commit messages created in GitLab UI set `\r\n` as a newline character. + Use `(\r\n?|\n)` instead of `\n` in your regular expression to correctly match + it. + + For example, given the following multi-line commit description: + + ```plaintext + JIRA: + Description + ``` + + You can validate it with this regular expression: `JIRA:(\r\n?|\n)\w+`. + - **Reject expression in commit messages**: Commit messages must not match the expression. To allow any commit message, leave empty. Uses multiline mode, which can be disabled by using `(?-m)`. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index ca7f2ae2043..a060973d89f 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce repository size **(FREE ALL)** diff --git a/doc/user/project/repository/signed_commits/gpg.md b/doc/user/project/repository/signed_commits/gpg.md index 88f6917d4b6..4b644a79c71 100644 --- a/doc/user/project/repository/signed_commits/gpg.md +++ b/doc/user/project/repository/signed_commits/gpg.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign commits with GPG **(FREE ALL)** diff --git a/doc/user/project/repository/signed_commits/index.md b/doc/user/project/repository/signed_commits/index.md index e6632ecb81a..cbea5e4e2f5 100644 --- a/doc/user/project/repository/signed_commits/index.md +++ b/doc/user/project/repository/signed_commits/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Signed commits **(FREE ALL)** @@ -22,15 +22,14 @@ Sign commits with your: ## Verify commits You can review commits for a merge request, or for an entire project, to confirm -they are signed: - -1. To review commits for a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Commits**. -1. To review commits for a merge request: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. On the left sidebar, select **Merge requests**, then select your merge request. - 1. Select **Commits**. +they are signed. + +1. On the left sidebar, select **Search or go to** and find your project. +1. To review commits: + - For a project, select **Code > Commits**. + - For a merge request: + 1. Select **Code > Merge requests**, then select your merge request. + 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** or **Unverified** badge, depending on the verification status of the signature. Unsigned commits do not display a badge: diff --git a/doc/user/project/repository/signed_commits/ssh.md b/doc/user/project/repository/signed_commits/ssh.md index c87a992fdac..e1c2a73be3e 100644 --- a/doc/user/project/repository/signed_commits/ssh.md +++ b/doc/user/project/repository/signed_commits/ssh.md @@ -48,8 +48,7 @@ To configure Git to use your key: git config --global gpg.format ssh ``` -1. Specify which public SSH key to use as the signing key and change the filename - (`~/.ssh/examplekey.pub`) to the location of your key. The filename might +1. Specify which public SSH key to use as the signing key and change the file name (`~/.ssh/examplekey.pub`) to the location of your key. The file name might differ, depending on how you generated your key: ```shell diff --git a/doc/user/project/repository/signed_commits/x509.md b/doc/user/project/repository/signed_commits/x509.md index 17767cbd8f4..18c967698fa 100644 --- a/doc/user/project/repository/signed_commits/x509.md +++ b/doc/user/project/repository/signed_commits/x509.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign commits and tags with X.509 certificates **(FREE ALL)** diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index 1f1b8dfc9cd..232f2e387d1 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tags **(FREE ALL)** diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md deleted file mode 100644 index 476cfc55298..00000000000 --- a/doc/user/project/repository/vscode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../editor_extensions/visual_studio_code/index.md' -remove_date: '2023-10-31' ---- - -This document was moved to [another location](../../../editor_extensions/visual_studio_code/index.md). - -<!-- This redirect file can be deleted after <2023-10-31>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 3acc62186a3..3899890ea7e 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,114 +1,97 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web Editor **(FREE ALL)** -You can use the Web Editor to make changes to a single file directly from the -GitLab UI. To make changes to multiple files, see [Web IDE](../web_ide/index.md). +You can use the Web Editor to make changes to a single file directly from the GitLab UI. +To make changes to multiple files, see [Web IDE](../web_ide/index.md). -In the Web Editor, you can: - -- [Create a file](#create-a-file). -- [Edit a file](#edit-a-file). -- [Upload a file](#upload-a-file). -- [Create a directory](#create-a-directory). -- [Create a branch](#create-a-branch). -- [Create a tag](#create-a-tag). - -Your [primary email address is used by default](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) -for any change you commit through the Web Editor. +Your [primary email address](../../profile/index.md#change-the-email-displayed-on-your-commits) +is used by default for any change you commit with the Web Editor. ## Create a file To create a text file in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, - select the plus icon (**{plus}**). -1. From the dropdown list, select **New file**. +1. Go to the directory where you want to create the new file. +1. Next to the directory name, select the plus icon (**{plus}**) > **New file**. 1. Complete the fields. -1. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected, if you had chosen a **Target branch** other than the [default branch (such as `main`)](../../../user/project/repository/branches/default.md). + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). 1. Select **Commit changes**. -### Create a file from a template +### From a template + +To create a text file from a template in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Code > Repository**. -1. Next to the project name, select the plus icon (**{plus}**) to display a - dropdown list, then select **New file** from the list. -1. For **Filename**, provide one of the filenames that GitLab provides a template for: +1. Go to the directory where you want to create the new file. +1. Next to the directory name, select the plus icon (**{plus}**) > **New file**. +1. In **Filename**, enter a filename that GitLab provides a template for: - `.gitignore` - `.gitlab-ci.yml` - `LICENSE` - `Dockerfile` -1. Select **Apply a template**, then select the template you want to apply. -1. Make your changes to the file. -1. Provide a **Commit message**. -1. Enter a **Target branch** to merge into. To create a new merge request with - your changes, enter a branch name that is not your repository's - [default branch](../../../user/project/repository/branches/default.md), -1. Select **Commit changes** to add the commit to your branch. +1. From the **Apply a template** dropdown list, select a template. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). +1. Select **Commit changes**. ## Edit a file To edit a text file in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. Go to your file. -1. In the upper right, select **Edit > Edit single file**. - -### Keyboard shortcuts - -When you [edit a file](#edit-a-file) in the Web Editor, you can use the same keyboard shortcuts for the Web IDE. -See the [available shortcuts](../../shortcuts.md#web-ide). +1. Go to the file you want to edit. +1. Select **Edit > Edit single file**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). +1. Select **Commit changes**. ### Preview Markdown > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6. -To preview Markdown content in the Web Editor: - -1. [Edit a file](#edit-a-file). -1. Do one of the following: - - Select the **Preview** tab. - - From the context menu, select **Preview Markdown**. +To preview a Markdown file in the Web Editor: -In the **Preview** tab, you can see a live Markdown preview alongside your content. +1. On the left sidebar, select **Search or go to** and find your project. +1. Go to the file you want to preview. +1. Select **Edit > Edit single file**. +1. Select the **Preview** tab. -To close the preview panel, do one of the following: +You can see a live Markdown preview alongside your content. -- Select the **Write** tab. -- From the context menu, select **Hide Live Preview**. +To close the preview panel, select the **Write** tab. ### Link to specific lines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11. - To link to single or multiple lines in the Web Editor, add hash information to the filename segment of the URL. For example: - `MY_FILE.js#L3` highlights line 3 in `MY_FILE.js`. - `MY_FILE.js#L3-10` highlights lines 3 to 10 in `MY_FILE.js`. -To link to a single line, you can also: - -1. [Edit a file](#edit-a-file). -1. Select a line number. +When you edit a file, you can also link to a single line by selecting a line number. ## Upload a file -To upload a binary file in the Web Editor: +To upload a file in the Web Editor: -<!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> +<!-- This list is duplicated at doc/user/project/repository/index.md#add-a-file-from-the-ui --> <!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **Upload file**. -1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Go to the directory where you want to upload the file. +1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). 1. Select **Upload file**. ## Create a directory @@ -116,9 +99,11 @@ To upload a binary file in the Web Editor: To create a directory in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **New directory**. -1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Go to the directory where you want to create the new directory. +1. Next to the directory name, select the plus icon (**{plus}**) > **New directory**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). 1. Select **Create directory**. ## Create a branch @@ -126,8 +111,7 @@ To create a directory in the Web Editor: To create a [branch](branches/index.md) in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **New branch**. +1. Next to the repository name, select the plus icon (**{plus}**) > **New branch**. 1. Complete the fields. 1. Select **Create branch**. @@ -137,7 +121,6 @@ You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **New tag**. +1. Next to the repository name, select the plus icon (**{plus}**) > **New tag**. 1. Complete the fields. 1. Select **Create tag**. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index d99729e3c1b..0594f3fe2ee 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -1,8 +1,7 @@ --- -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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Requirements management **(ULTIMATE ALL)** @@ -43,7 +42,7 @@ For a more in-depth walkthrough see [GitLab Requirements Traceability Walkthroug A paginated list of requirements is available in each project, and there you can create a new requirement. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -73,7 +72,7 @@ next to the requirement title. You can edit a requirement from the requirements list page. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -89,7 +88,7 @@ To edit a requirement: You can archive an open requirement while you're in the **Open** tab. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -101,7 +100,7 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab. You can view the list of archived requirements in the **Archived** tab. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -294,7 +293,7 @@ By exporting requirements, you and your team can import them into another tool o your customers. Exporting requirements can aid collaboration with higher-level systems, as well as audit and regulatory compliance tasks. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md deleted file mode 100644 index cd09f84641e..00000000000 --- a/doc/user/project/service_desk.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'service_desk/index.md' -remove_date: '2023-10-24' ---- - -This document was moved to [another location](service_desk/index.md). - -<!-- This redirect file can be deleted after <2023-10-24>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/service_desk/configure.md b/doc/user/project/service_desk/configure.md index 8d0fbd81ebd..91dbe7a38dd 100644 --- a/doc/user/project/service_desk/configure.md +++ b/doc/user/project/service_desk/configure.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Service Desk **(FREE ALL)** @@ -17,7 +17,7 @@ Prerequisites: [email sub-addressing](../../../administration/incoming_email.md#email-sub-addressing), but you can also use [catch-all mailboxes](../../../administration/incoming_email.md#catch-all-mailbox). To do this, you must have administrator access. -- You must have enabled [issue](../settings/index.md#configure-project-features-and-permissions) +- You must have enabled [issue](../settings/project_features_permissions.md#configure-project-features-and-permissions) tracker for the project. To enable Service Desk in your project: @@ -120,7 +120,7 @@ You can set description templates at various levels: The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. -Prerequisite: +Prerequisites: - You must have [created a description template](../description_templates.md#create-an-issue-template). @@ -155,15 +155,36 @@ To edit the custom email display name: 1. Below **Email display name**, enter a new name. 1. Select **Save changes**. +## Reopen issues when an external participant comments + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8549) in GitLab 16.7 + +You can configure GitLab to reopen closed issues when an external participant adds +a new comment on an issue by email. This also adds an internal comment that mentions +the assignees of the issue and creates to-do items for them. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a walkthrough, see [a short showcase video](https://youtu.be/163wDM1e43o). + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To enable this setting: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Select the **Reopen issues on a new note from an external participant** checkbox. +1. Select **Save changes**. + ## Custom email address **(BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329990) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `service_desk_custom_email`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.4. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for -your entire instance, an administrator can [disable the feature flag](../../../administration/feature_flags.md) -named `service_desk_custom_email`. On GitLab.com, this feature is available. +> - Ability to select the SMTP authentication method [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429680) in GitLab 16.6. +> - [Feature flag `service_desk_custom_email` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.7. +> - Local network allowed for SMTP host on GitLab self-managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435206) in GitLab 16.7 Configure a custom email address to show as the sender of your support communication. Maintain brand identity and instill confidence among support requesters with a domain they recognize. @@ -193,6 +214,8 @@ The custom email address you want to use must meet all of the following requirem - You have SMTP credentials (ideally, you should use an app password). The username and password are stored in the database using the Advanced Encryption Standard (AES) with a 256-bit key. +- The **SMTP host** must be resolvable from the network of your GitLab instance (on GitLab self-managed) + or the public internet (on GitLab SaaS). - You must have at least the Maintainer role for the project. - Service Desk must be configured for the project. @@ -206,8 +229,7 @@ Configure and verify a custom email address when you want to send Service Desk e 1. Note the presented Service Desk address of this project, and with your email provider (for example, Gmail), set up email forwarding from the custom email address to the Service Desk address. -1. Back in GitLab, complete the fields. **SMTP host** must be resolvable from the network of your GitLab instance (on GitLab self-managed) - or the public internet (on GitLab SaaS). +1. Back in GitLab, complete the fields. 1. Select **Save & test settings**. The configuration has been saved and the verification of the custom email address is triggered. @@ -237,6 +259,56 @@ If the verification failed, the email also contains details of the reason. If the verification was successful, the custom email address is ready to be used. You can now enable sending Service Desk emails via the custom email address. +#### Troubleshooting your configuration + +When configuring a custom email you might encounter the following issues. + +##### Invalid credentials + +You might get an error that states that invalid credentials were used. + +This occurs when the SMTP server returns that the authentication wasn't successful. + +To troubleshoot this: + +1. Check your SMTP credentials, especially the username and password. +1. Sometimes GitLab cannot automatically select an authentication method that the SMTP server supports. Either: + - Try the available authentication methods (**Plain**, **Login** and **CRAM-MD5**). + - Check which authentication methods your SMTP server supports, using the + [`swaks` command line tool](https://www.jetmore.org/john/code/swaks/): + 1. Run the following command with your credentials and look for a line that starts with `250-AUTH`: + + ```shell + swaks --to user@example.com \ + --from support@example.com \ + --auth-user support@example.com \ + --server smtp@example.com:587 \ + -tls-optional \ + --auth-password your-app-password + ``` + + 1. Select one of the supported authentication methods in the custom email setup form. + +##### Incorrect forwarding target + +You might get an error that states that an incorrect forwarding target was used. + +This occurs when the verification email was forwarded to a different email address than the +project-specific Service Desk address that's displayed in the custom email configuration form. + +You must use the Service Desk address generated from `incoming_email`. Forwarding to the additional +Service Desk alias address generated from `service_desk_email` is not supported because it doesn't support +all reply by email functionalities. + +To troubleshoot this: + +1. Find the correct email address to forward emails to. Either: + - Note the address from the verification result email that all project owners and the user that + triggered the verification process receive. + - Copy the address from the **Service Desk email address to forward emails to** input in the + custom email setup form. +1. Forward all emails to the custom email address to the correct target email address. + ### Enable or disable the custom email address After the custom email address has been verified, administrators can enable or disable sending Service Desk emails via the custom email address. @@ -353,6 +425,7 @@ In GitLab: - **SMTP port**: `587`. - **SMTP username**: Prefilled with the custom email address. - **SMTP password**: The app password you previously created for the custom email account. + - **SMTP authentication method**: Let GitLab select a server-supported method (recommended) 1. Select **Save and test connection** 1. After the [verification process](#verification) you should be able to [enable the custom email address](#enable-or-disable-the-custom-email-address). diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md index ab807553436..9ab69c4bdb8 100644 --- a/doc/user/project/service_desk/index.md +++ b/doc/user/project/service_desk/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Desk **(FREE ALL)** @@ -46,6 +46,7 @@ Meanwhile: - [Customize emails sent to the requester](configure.md#customize-emails-sent-to-the-requester) - [Use a custom template for Service Desk tickets](configure.md#use-a-custom-template-for-service-desk-tickets) - [Support Bot user](configure.md#support-bot-user) + - [Reopen issues when an external participant comments](configure.md#reopen-issues-when-an-external-participant-comments) - [Custom email address (Beta)](configure.md#custom-email-address) - [Use an additional Service Desk alias email](configure.md#use-an-additional-service-desk-alias-email) - [Configure email ingestion in multi-node environments](configure.md#configure-email-ingestion-in-multi-node-environments) @@ -61,3 +62,33 @@ Meanwhile: Your emails might be ignored because they contain one of the [email headers that GitLab ignores](../../../administration/incoming_email.md#rejected-headers). + +### Email ingestion doesn't work in 16.6.0 self-managed + +GitLab self-managed `16.6.0` introduced a regression that prevents `mail_room` (email ingestion) from starting. +Service Desk and other reply-by-email features don't work. +[Issue 432257](https://gitlab.com/gitlab-org/gitlab/-/issues/432257) tracks fixing this problem. + +The workaround is to run the following commands in your GitLab installation +to patch the affected files: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +:::TabTitle Docker + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +cd /opt/gitlab/embedded/service/gitlab-rails +patch -p1 < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +::EndTabs diff --git a/doc/user/project/service_desk/using_service_desk.md b/doc/user/project/service_desk/using_service_desk.md index 5f3c725b83b..7db84f6988b 100644 --- a/doc/user/project/service_desk/using_service_desk.md +++ b/doc/user/project/service_desk/using_service_desk.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Service Desk **(FREE ALL)** diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 22eb7c54d12..fc9b24362e0 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Migrating projects using file exports **(FREE ALL)** @@ -86,8 +86,7 @@ Before you can migrate projects on a self-managed GitLab instance using file exp To enable file exports as an import source for the destination instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. @@ -206,7 +205,7 @@ may be possible for an attacker to steal your sensitive data. - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later - than the GitLab version you exported to. + than the GitLab version you exported from. - Review [compatibility](#compatibility) for any issues. - At least the Maintainer role on the destination group to migrate to. diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 79401a7734a..3f2b9a23f2d 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Troubleshooting file export project migrations @@ -86,7 +86,7 @@ reduce the repository size for another import attempt: 1. To reduce the repository size, work on this `smaller-tmp-main` branch: [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) - or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) + or [interactively rebase and fixup](../../../topics/git/git_rebase.md#rebase-interactively-by-using-git) to reduce the number of commits. ```shell diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 623c61744f7..0456577f1ff 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,368 +1,11 @@ --- -stage: Data Stores -group: Tenant Scale -info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments' -type: reference, index, howto +redirect_to: '../working_with_projects.md' +remove_date: '2024-02-28' --- -# Project settings **(FREE ALL)** +This document was moved to [another location](../working_with_projects.md). -Use the **Settings** page to manage the configuration options in your [project](../index.md). - -## View project settings - -Prerequisite: - -- You must have at least the Maintainer role for the project. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. To display all settings in a section, select **Expand**. -1. Optional. Use the search box to find a setting. - -## Edit project name and description - -Use the project general settings to edit your project details. - -Prerequisite: - -- You must have at least the Maintainer role for the project. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. In the **Project name** text box, enter your project name. -1. In the **Project description** text box, enter your project description. -1. Under **Project avatar**, to change your project avatar, select **Choose file**. - -## Assign topics to a project - -Use [topics](../working_with_projects.md#organizing-projects-with-topics) to categorize projects and find similar new projects. - -To assign topics to a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings** > **General**. -1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. -1. Select **Save changes**. - -If you're an instance administrator, you can administer all project topics from the -[Admin Area's Topics page](../../../administration/admin_area.md#administering-topics). - -NOTE: -The assigned topics are visible only to users with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. - -## Rename a repository - -A project's repository name defines its URL and its place on the file disk -where GitLab is installed. - -Prerequisite: - -- You must be an administrator or have the Maintainer or Owner role for the project. - -NOTE: -When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see -[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). - -To rename a repository: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Change path** text box, edit the path. -1. Select **Change path**. - -## Configure project features and permissions - -To configure features and permissions for a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. To allow users to request access to the project, select the **Users can request access** checkbox. -1. To enable or disable features in the project, use the feature toggles. -1. Select **Save changes**. - -When you disable a feature, the following additional features are also disabled: - -- If you disable the **Issues** feature, project users cannot use: - - - **Issue Boards** - - **Service Desk** - - Project users can still access **Milestones** from merge requests. - -- If you disable **Issues** and **Merge Requests**, project users cannot use: - - - **Labels** - - **Milestones** - -- If you disable **Repository**, project users cannot access: - - - **Merge requests** - - **CI/CD** - - **Git Large File Storage** - - **Packages** - -- The metrics dashboard requires read access to project environments and deployments. - Users with access to the metrics dashboard can also access environments and deployments. - -## Configure merge request settings for a project - -Configure your project's merge request settings: - -- Set up the [merge request method](../merge_requests/methods/index.md) (merge commit, fast-forward merge). -- Add merge request [description templates](../description_templates.md). -- Enable: - - [Merge request approvals](../merge_requests/approvals/index.md). - - [Status checks](../merge_requests/status_checks.md). - - [Merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - - [Merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). - - [Required associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - - [GitLab Duo Suggested Reviewers](../merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) - - [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). -- Configure: - - [Suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - - [Merge and squash commit message templates](../merge_requests/commit_templates.md). - - [Default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. - -### Delete the source branch on merge by default - -In merge requests, you can change the default behavior so that the -**Delete the source branch** checkbox is always selected. - -To set this default: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > Merge requests**. -1. Select **Enable "Delete source branch" option by default**. -1. Select **Save changes**. - -## Export project - -You can [export a project and its data](import_export.md#export-a-project-and-its-data). - -## Transfer a project to another namespace - -When you transfer a project to another namespace, you move the project to a different group. - -Prerequisites: - -- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) you are transferring to. -- You must be the Owner of the project you transfer. -- The group must allow creation of new projects. -- The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). -- The project must not have a security policy. - If a security policy is assigned to the project, it is automatically unassigned during the transfer. -- If the root namespace changes, you must remove npm packages that follow the [naming convention](../../../user/packages/npm_registry/index.md#naming-convention) from the project. - After you transfer the project you can either: - - - Update the package scope with the new root namespace path, and publish it again to the project. - - Republish the package to the project without updating the root namespace path, which causes the package to no longer follow the naming convention. - If you republish the package without updating the root namespace path, it will not be available at the [instance level endpoint](../../../user/packages/npm_registry/index.md#install-from-the-instance-level). - -To transfer a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. Under **Transfer project**, choose the namespace to transfer the project to. -1. Select **Transfer project**. -1. Enter the project's name and select **Confirm**. - -You are redirected to the project's new page and GitLab applies a redirect. For more information about repository redirects, see [What happens when a repository path changes](../repository/index.md#what-happens-when-a-repository-path-changes). - -NOTE: -If you are an administrator, you can also use the [administration interface](../../../administration/admin_area.md#administering-projects) -to move any project to any namespace. - -### Transferring a GitLab SaaS project to a different subscription tier - -When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free: - -- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked. -- [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) - and [test cases](../../../ci/test_cases/index.md) are deleted. - -## Archive a project - -When you archive a project, the repository, packages, issues, merge requests, and all -other features become read-only. Archived projects are also hidden from project lists. - -To archive a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Archive project** section, select **Archive project**. -1. To confirm, select **OK**. - -## Unarchive a project - -When you unarchive a project, the read-only restriction is removed, -and the project becomes available in project lists. - -Prerequisite: - -- You must be an administrator or have the Owner role for the project. - -1. Find the archived project. - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. Select **Explore projects**. - 1. In the **Sort projects** dropdown list, select **Show archived projects**. - 1. In the **Filter by name** field, enter the project name. - 1. Select the project link. -1. On the left sidebar, select **Settings > General**. -1. Under **Advanced**, select **Expand**. -1. In the **Unarchive project** section, select **Unarchive project**. -1. To confirm, select **OK**. - -## Delete a project - -> - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. -> - Default deletion behavior for projects changed to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -> - Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0. -> - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -You can mark a project to be deleted. -After you delete a project: - -- Projects in personal namespaces are deleted immediately. -- Projects in groups are deleted after a retention period. - -Prerequisite: - -- You must have the Owner role for a project. - -To delete a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Delete this project** section, select **Delete project**. -1. On the confirmation dialog, enter the project name and select **Yes, delete project**. - -This action deletes the project and all associated resources (such as issues and merge requests). - -You can also [delete projects using the Rails console](../working_with_projects.md#delete-a-project-using-console). - -### Delayed project deletion **(PREMIUM ALL)** - -> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. -> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. -> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -Prerequisite: - -- You must have the Owner role for the project. - -Projects in a group (not a personal namespace) can be deleted after a delay period. - -On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. -On SaaS, there is a non-adjustable default retention period of seven days. - -You can [view projects that are pending deletion](../working_with_projects.md#view-projects-pending-deletion), -and use the Rails console to -[find projects that are pending deletion](../working_with_projects.md#find-projects-that-are-pending-deletion). - -### Delete a project immediately - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. -> - Option to delete projects immediately from the Admin Area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -Prerequisites: - -- You must have the Owner role for the project. -- The project must be [marked for deletion](#delete-a-project). - -If you don't want to wait for delayed deletion, you can delete a project immediately. To do this, perform the steps for [deleting a projects](#delete-a-project) again. - -In the first cycle of deleting a project, the project is moved to the delayed deletion queue and automatically deleted after the retention period has passed. -If during this delayed deletion time you run a second deletion cycle, the project is deleted immediately. - -To immediately delete a project marked for deletion: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Delete this project** section, select **Delete project**. -1. On the confirmation dialog, enter the project name and select **Yes, delete project**. - -## Restore a project **(PREMIUM ALL)** - -Prerequisites: - -- You must have the Owner role for the project. -- The project must be [marked for deletion](#delete-a-project). - -To restore a project marked for deletion: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the Restore project section, select **Restore project**. - -## Disable project analytics - -By default, [analytics for a project](../../analytics/index.md#project-level-analytics) are displayed under the **Analyze** item in the left sidebar. -To disable this feature and remove the **Analyze** item from the left sidebar: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Turn off the **Analytics** toggle. -1. Select **Save changes**. - -## Disable CVE identifier request in issues **(FREE SAAS)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. - -In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. - -To disable the CVE identifier request option in issues in your project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. -1. Select **Save changes**. - -## Disable project email notifications - -Prerequisite: - -- You must have the Owner role for the project. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Clear the **Disable email notifications** checkbox. - -## Related topics - -- [Alert integrations](../../../operations/incident_management/integrations.md#configuration) -- [PagerDuty incident management](../../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook) -- [SLA countdown timer](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) -- [Error tracking](../../../operations/error_tracking.md) -- [Incidents sync](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) -- [Service Desk](../service_desk/index.md) - -## Troubleshooting - -When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. - -### Transfer a project through console - -If transferring a project through the UI or API is not working, you can attempt the transfer in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -```ruby -p = Project.find_by_full_path('<project_path>') - -# To set the owner of the project -current_user = p.creator - -# Namespace where you want this to be moved -namespace = Namespace.find_by_full_path("<new_namespace>") - -Projects::TransferService.new(p, current_user).execute(namespace) -``` +<!-- This redirect file can be deleted after <2024-02-28>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/settings/migrate_projects.md b/doc/user/project/settings/migrate_projects.md new file mode 100644 index 00000000000..70e6ff5da28 --- /dev/null +++ b/doc/user/project/settings/migrate_projects.md @@ -0,0 +1,126 @@ +--- +stage: Data Stores +group: Tenant Scale +info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments' +--- + +# Migrate projects **(FREE ALL)** + +## Export a project + +You can [export a project and its data](import_export.md#export-a-project-and-its-data). + +## Transfer a project to another namespace + +When you transfer a project to another namespace, you move the project to a different group. + +Prerequisites: + +- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) you are transferring to. +- You must be the Owner of the project you transfer. +- The group must allow creation of new projects. +- The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). +- The project must not have a security policy. + If a security policy is assigned to the project, it is automatically unassigned during the transfer. +- If the root namespace changes, you must remove npm packages that follow the [naming convention](../../../user/packages/npm_registry/index.md#naming-convention) from the project. + After you transfer the project you can either: + + - Update the package scope with the new root namespace path, and publish it again to the project. + - Republish the package to the project without updating the root namespace path, which causes the package to no longer follow the naming convention. + If you republish the package without updating the root namespace path, it will not be available at the [instance level endpoint](../../../user/packages/npm_registry/index.md#install-from-the-instance-level). + +To transfer a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. Under **Transfer project**, choose the namespace to transfer the project to. +1. Select **Transfer project**. +1. Enter the project's name and select **Confirm**. + +You are redirected to the project's new page and GitLab applies a redirect. For more information about repository redirects, see [What happens when a repository path changes](../repository/index.md#what-happens-when-a-repository-path-changes). + +NOTE: +If you are an administrator, you can also use the [administration interface](../../../administration/admin_area.md#administering-projects) +to move any project to any namespace. + +### Transferring a GitLab SaaS project to a different subscription tier + +When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free: + +- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked. +- [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) + and [test cases](../../../ci/test_cases/index.md) are deleted. + +## Archive a project + +When you archive a project, the repository, packages, issues, merge requests, and all +other features become read-only. Archived projects are also hidden from project lists. + +To archive a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Archive project** section, select **Archive project**. +1. To confirm, select **OK**. + +## Unarchive a project + +When you unarchive a project, the read-only restriction is removed, +and the project becomes available in project lists. + +Prerequisites: + +- You must be an administrator or have the Owner role for the project. + +1. Find the archived project. + 1. On the left sidebar, select **Search or go to**. + 1. Select **View all my projects**. + 1. Select **Explore projects**. + 1. In the **Sort projects** dropdown list, select **Show archived projects**. + 1. In the **Filter by name** field, enter the project name. + 1. Select the project link. +1. On the left sidebar, select **Settings > General**. +1. Under **Advanced**, select **Expand**. +1. In the **Unarchive project** section, select **Unarchive project**. +1. To confirm, select **OK**. + +## Restore a project **(PREMIUM ALL)** + +Prerequisites: + +- You must have the Owner role for the project. +- The project must be [marked for deletion](../working_with_projects.md#delete-a-project). + +To restore a project marked for deletion: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the Restore project section, select **Restore project**. + +## Troubleshooting + +When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. + +### Transfer a project through console + +If transferring a project through the UI or API is not working, you can attempt the transfer in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +p = Project.find_by_full_path('<project_path>') + +# To set the owner of the project +current_user = p.creator + +# Namespace where you want this to be moved +namespace = Namespace.find_by_full_path("<new_namespace>") + +Projects::TransferService.new(p, current_user).execute(namespace) +``` + +## Related topics + +- [Migrating projects using file exports](import_export.md) +- [Troubleshooting file export project migrations](import_export_troubleshooting.md) diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 3526425c912..f22fe603f81 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Project access tokens @@ -24,7 +23,7 @@ Use a project access token to authenticate: - The project access token as the password. Project access tokens are similar to [group access tokens](../../group/settings/group_access_tokens.md) -and [personal access tokens](../../profile/personal_access_tokens.md). +and [personal access tokens](../../profile/personal_access_tokens.md), but project access tokens are scoped to a project, so you cannot use them to access resources from other projects. In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. @@ -57,6 +56,7 @@ To create a project access token: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. +1. Select **Add new token**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Enter an expiry date for the token. - The token expires on that date at midnight UTC. @@ -65,7 +65,7 @@ To create a project access token: - An instance-wide [maximum lifetime](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). -1. Select **Create project access token**. +1. Select **Create project access token**. 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. @@ -75,7 +75,7 @@ To revoke a project access token: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. -1. Next to the project access token to revoke, select **Revoke**. +1. Next to the project access token to revoke, select **Revoke** (**{remove}**). ## Scopes for a project access token @@ -87,17 +87,17 @@ The scope determines the actions you can perform when you authenticate with a pr NOTE: See the warning in [create a project access token](#create-a-project-access-token) regarding internal projects. -| 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` | Grants read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | Grants write access (push) to the [Container Registry](../../packages/container_registry/index.md). | -| `read_repository` | Grants read access (pull) to the repository. | -| `write_repository` | Grants read and write access (pull and push) to the repository. | -| `create_runner` | Grants permission to create runners in the project. | -| `ai_features` | Grants permission to perform API actions for GitLab Duo. | -| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project. | +| Scope | Description | +|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped project API, including the [container registry](../../packages/container_registry/index.md), the [dependency proxy](../../packages/dependency_proxy/index.md), and 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` | Grants read access (pull) to the [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Grants write access (push) to the [container registry](../../packages/container_registry/index.md). | +| `read_repository` | Grants read access (pull) to the repository. | +| `write_repository` | Grants read and write access (pull and push) to the repository. | +| `create_runner` | Grants permission to create runners in the project. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project. | ## Enable or disable project access token creation @@ -108,7 +108,7 @@ To enable or disable project access token creation for all projects in a top-lev 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. -1. Under **Permissions**, turn on or off **Allow project and group access token creation**. +1. In **Permissions**, select or clear the **Users can create project access tokens and group access tokens in this group** checkbox. Even when creation is disabled, you can still use and revoke existing project access tokens. diff --git a/doc/user/project/settings/project_features_permissions.md b/doc/user/project/settings/project_features_permissions.md new file mode 100644 index 00000000000..27c0668079c --- /dev/null +++ b/doc/user/project/settings/project_features_permissions.md @@ -0,0 +1,206 @@ +--- +stage: Data Stores +group: Tenant Scale +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Project features and permissions **(FREE ALL)** + +## Configure project features and permissions + +To configure features and permissions for a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. To allow users to request access to the project, select the **Users can request access** checkbox. +1. To enable or disable features in the project, use the feature toggles. +1. Select **Save changes**. + +When you disable a feature, the following additional features are also disabled: + +- If you disable the **Issues** feature, project users cannot use: + + - **Issue Boards** + - **Service Desk** + - Project users can still access **Milestones** from merge requests. + +- If you disable **Issues** and **Merge Requests**, project users cannot use: + + - **Labels** + - **Milestones** + +- If you disable **Repository**, project users cannot access: + + - **Merge requests** + - **CI/CD** + - **Git Large File Storage** + - **Packages** + +- The metrics dashboard requires read access to project environments and deployments. + Users with access to the metrics dashboard can also access environments and deployments. + +## Enable and disable project features + +Enabled project features are visible and accessible to project members. +You can disable specific project features, so that they are not visible and accessible to project members, regardless of their role. + +To enable or disable individual features in a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. To enable a feature, turn on the toggle. To disable a feature, turn off the toggle. +1. Select **Save changes**. + +## Disable project analytics + +By default, [analytics for a project](../../analytics/index.md#project-level-analytics) +are displayed under the **Analyze** item in the left sidebar. +To disable this feature and remove the **Analyze** item from the left sidebar: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn off the **Analytics** toggle. +1. Select **Save changes**. + +## Disable CVE identifier request in issues **(FREE SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. + +In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. + +To disable the CVE identifier request option in issues in your project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. +1. Select **Save changes**. + +## Disable project email notifications + +Prerequisites: + +- You must have the Owner role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Clear the **Disable email notifications** checkbox. + +## Configure merge request settings for a project + +Configure your project's merge request settings: + +- Set up the [merge request method](../merge_requests/methods/index.md) (merge commit, fast-forward merge). +- Add merge request [description templates](../description_templates.md). +- Enable: + - [Merge request approvals](../merge_requests/approvals/index.md). + - [Status checks](../merge_requests/status_checks.md). + - [Merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). + - [Merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). + - [Required associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). + - [GitLab Duo Suggested Reviewers](../merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) + - [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). +- Configure: + - [Suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). + - [Merge and squash commit message templates](../merge_requests/commit_templates.md). + - [Default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. + +### Delete the source branch on merge by default + +In merge requests, you can change the default behavior so that the +**Delete the source branch** checkbox is always selected. + +To set this default: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > Merge requests**. +1. Select **Enable "Delete source branch" option by default**. +1. Select **Save changes**. + +## Project topics + +Topics are labels that you can assign to projects to help you organize and find them. +A topic is typically a short name that describes the content or purpose of a project. +You can assign a topic to several projects. + +For example, you can create and assign the topics `python` and `hackathon` to all projects that use Python and are intended for Hackathon contributions. + +Topics assigned to a project are listed in the **Project overview**, below the project name and activity information. + +Only users with access to the project can see the topics assigned to that project, +but everyone (including unauthenticated users) can see the topics available on the GitLab instance. +Do not include sensitive information in the name of a topic. + +### Explore topics + +To explore project topics: + +1. On the left sidebar, select **Search or go to**. +1. Select **Explore**. +1. On the left sidebar, select **Topics**. +1. To view projects associated with a topic, select a topic. + +The **Explore topics** page shows a list of projects with this topic. + +### Filter and sort topics + +You can filter the list of projects that have a certain topic by: + +- Name +- Language +- Owner +- Archive status +- Visibility + +You can sort the projects by: + +- Date created +- Date updated +- Name +- Number of stars + +### Subscribe to a topic + +If you want to know when new projects are added to a topic, you can use its RSS feed. + +You can do this either from the **Explore topics** page or a project with topics. + +To subscribe to a topic: + +- From the **Explore topics** page: + + 1. On the left sidebar, expand the top-most chevron ({**chevron-down**}). + 1. Select **Explore**. + 1. Select **Topics**. + 1. Select the topic you want to subscribe to. + 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). + +- From a project: + + 1. On the left sidebar, select **Search or go to** and find your project. + 1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to. + 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). + +The results are displayed as an RSS feed in Atom format. +The URL of the result contains a feed token and the list of projects that have the topic. You can add this URL to your feed reader. + +### Assign topics to a project + +To assign topics to a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings** > **General**. +1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. +1. Select **Save changes**. + +NOTE: +The assigned topics are visible only to users with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. + +### Administer topics + +Instance administrators can administer all project topics from the +[Admin Area's Topics page](../../../administration/admin_area.md#administering-topics). diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 546b3250180..22ecf9833ac 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # System notes **(FREE ALL)** diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index f1e5247efdb..5f06098f8f6 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -1,8 +1,7 @@ --- -type: reference 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Time tracking **(FREE ALL)** @@ -83,7 +82,7 @@ Prerequisites: To add a time entry using the user interface: -1. In the **Time tracking** section of the sidebar, select **Add time entry** (**{plus}**). A modal opens. +1. In the **Time tracking** section of the sidebar, select **Add time entry** (**{plus}**). A dialog opens. 1. Enter: - The amount of time spent. @@ -155,11 +154,9 @@ To delete all the time spent at once, use the `/remove_time_spent` [quick action ## View a time tracking report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271409) in GitLab 13.12. +### For an issue or merge request -You can view a breakdown of time spent on an issue or merge request. - -To view a time tracking report: +To view a time tracking report of time spent on an issue or merge request: 1. Go to an issue or a merge request. 1. In the right sidebar, select **Time tracking report**. @@ -168,22 +165,46 @@ To view a time tracking report: The breakdown of spent time displayed is limited to a maximum of 100 entries. +### Global time tracking report **(EXPERIMENT)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344002) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `global_time_tracking_report`. Disabled by default. +> - Enabled on GitLab.com in GitLab 16.5. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `global_time_tracking_report`. +On GitLab.com, this feature is available. +This feature is not ready for production use. + +View a report of time spent in issues and merge requests across all of GitLab. + +This feature is an [Experiment](../../policy/experiment-beta-support.md). +If you find a bug, let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/435222). + +To view the global time tracking report: + +1. In your browser, enter the global report's URL: + - For self-managed, add `/-/timelogs` to your base URL. For example, `https://gitlab.example.com/-/timelogs`. + - For GitLab.com, go to <https://gitlab.com/-/timelogs>. +1. Optional. To filter by a specific user, enter their username without the `@` symbol. +1. Select start and end dates. +1. Select **Run report**. + + + ## Available time units The following time units are available: | Time unit | What to type | Conversion rate | | --------- | --------------------------- | --------------- | -| Month | `mo`, `month`, or `months` | 4 w (160 h) | -| Week | `w`, `week`, or `weeks` | 5 d (40 h) | -| Day | `d`, `day`, or `days` | 8 h | -| Hour | `h`, `hour`, or `hours` | 60 m | +| Month | `mo`, `month`, or `months` | 4 w (160 h) | +| Week | `w`, `week`, or `weeks` | 5 d (40 h) | +| Day | `d`, `day`, or `days` | 8 h | +| Hour | `h`, `hour`, or `hours` | 60 m | | Minute | `m`, `minute`, or `minutes` | | ### Limit displayed units to hours **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29469/) in GitLab 12.1. - In GitLab self-managed instances, you can limit the display of time units to hours. To do so: diff --git a/doc/user/project/use_project_as_go_package.md b/doc/user/project/use_project_as_go_package.md new file mode 100644 index 00000000000..54e9eac7756 --- /dev/null +++ b/doc/user/project/use_project_as_go_package.md @@ -0,0 +1,178 @@ +--- +stage: Data Stores +group: Tenant Scale +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" +--- + +# Use a project as a Go package **(FREE ALL)** + +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) with `read_api` scope. + +To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: + +```plaintext +machine gitlab.example.com +login <gitlab_user_name> +password <personal_access_token> +``` + +On Windows, Go reads `~/_netrc` instead of `~/.netrc`. + +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. + +## Authenticate Git requests + +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. + +Configure Git to either: + +- Embed credentials in the request URL: + + ```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): + +- `GOPRIVATE` +- `GONOPROXY` +- `GONOSUMDB` + +To disable fetching: + +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`. + +- 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. + +## Authenticate Git requests to private subgroups + +If the Go module is located under a private subgroup like +`gitlab.com/namespace/subgroup/go-module`, then the Git authentication doesn't work. +It happens, because `go get` makes an unauthenticated request to discover +the repository path. +Without an HTTP authentication via `.netrc` file, GitLab responds with +`gitlab.com/namespace/subgroup.git` to prevent a security risk of exposing +the project's existence for unauthenticated users. +As a result, the Go module cannot be downloaded. + +Unfortunately, Go doesn't provide any means of request authentication apart +from `.netrc`. In a future version, Go may add support for arbitrary +authentication headers. +Follow [`golang/go#26232`](https://github.com/golang/go/issues/26232) for details. + +### Workaround: use `.git` in the module name + +There is a way to skip `go get` request and force Go to use a Git authentication +directly, but it requires a modification of the module name. + +<!-- markdownlint-disable proper-names --> + +> If the module path has a VCS qualifier (one of .bzr, .fossil, .git, .hg, .svn) +> at the end of a path component, the go command will use everything up to that +> path qualifier as the repository URL. For example, for the module +> example.com/foo.git/bar, the go command downloads the repository +> at example.com/foo.git using git, expecting to find the module +> in the bar subdirectory. + +<!-- markdownlint-enable proper-names --> + +[From Go documentation](https://go.dev/ref/mod#vcs-find) + +1. Go to `go.mod` of the Go module in a private subgroup. +1. Add `.git` to the module name. + For example, rename`module gitlab.com/namespace/subgroup/go-module` to `module gitlab.com/namespace/subgroup/go-module.git`. +1. Commit and push this change. +1. Visit Go projects that depend on this module and adjust their `import` calls. + For example, `import gitlab.com/namespace/subgroup/go-module.git`. + +The Go module should be correctly fetched after this change. +For example, `GOPRIVATE=gitlab.com/namespace/* go mod tidy`. + +## 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: + + ```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" + ``` + + - 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 + +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 access the Geo secondary server with HTTP: + +1. Add a Git `insteadOf` redirect on the client: + + ```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 + add the credentials in the client's `~/.netrc` file: + + ```shell + machine gitlab.example.com login USERNAME password TOKEN + machine gitlab-secondary.example.com login USERNAME password TOKEN + ``` + +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. diff --git a/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png b/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png Binary files differdeleted file mode 100644 index 66ebae15e98..00000000000 --- a/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index fb2bd707c56..49efd463334 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web IDE **(FREE ALL)** @@ -58,8 +58,6 @@ To open any file by its name: 1. Press <kbd>Command</kbd>+<kbd>P</kbd>. 1. Enter the name of your file. - - ## Search across files You can use the Web IDE to search all files in the opened folder. @@ -232,6 +230,10 @@ However, you can use a terminal to install dependencies and compile and debug co For more information about configuring a workspace that supports interactive web terminals, see [remote development](../remote_development/index.md). +## Related topics + +- [GitLab Duo Chat in the Web IDE](../../gitlab_duo_chat.md#web-ide) + ## Troubleshooting When working with the Web IDE, you might encounter the following issues. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index ae182f1f183..64f6fa2c75e 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group wikis **(PREMIUM ALL)** diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index fd543263ebd..f4946230360 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Wiki **(FREE ALL)** @@ -272,7 +272,7 @@ A `_sidebar` example, formatted with Markdown: Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) can enable or disable a project wiki by following the instructions in -[Sharing and permissions](../settings/index.md#configure-project-features-and-permissions). +[Sharing and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). Administrators for self-managed GitLab installs can [configure additional wiki settings](../../../administration/wikis/index.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 2a4f0b99246..1c60f3bebf3 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Manage projects **(FREE ALL)** @@ -50,92 +50,101 @@ To view projects you have [starred](#star-a-project): 1. On the left sidebar, select your avatar and then your username. 1. On the left sidebar, select **Starred projects**. -## Organizing projects with topics +## Edit project name and description -Topics are labels that you can assign to projects to help you organize and find them. -A topic is typically a short name that describes the content or purpose of a project. -You can assign a topic to several projects. +Use the project general settings to edit your project details. -For example, you can create and assign the topics `python` and `hackathon` to all projects that use Python and are intended for Hackathon contributions. +Prerequisites: -Topics assigned to a project are listed in the **Project overview**, below the project name and activity information. +- You must have at least the Maintainer role for the project. -Only users with access to the project can see the topics assigned to that project, -but everyone (including unauthenticated users) can see the topics available on the GitLab instance. -Do not include sensitive information in the name of a topic. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. In the **Project name** text box, enter your project name. See the [limitations on project names](../../user/reserved_names.md). +1. In the **Project description** text box, enter your project description. The description is limited to 500 characters. +1. Under **Project avatar**, to change your project avatar, select **Choose file**. -### Explore topics +## Star a project -To explore project topics: +You can add a star to projects you use frequently to make them easier to find. -1. On the left sidebar, select **Search or go to**. -1. Select **Explore**. -1. On the left sidebar, select **Topics**. -1. To view projects associated with a topic, select a topic. +To add a star to a project: -The **Explore topics** page shows a list of projects with this topic. +1. On the left sidebar, select **Search or go to** and find your project. +1. In the upper-right corner of the page, select **Star**. -### Filter and sort topics +## Delete a project -You can filter the list of projects that have a certain topic by: +> - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. +> - Default deletion behavior for projects changed to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> - Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0. +> - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. -- Name -- Language -- Owner -- Archive status -- Visibility +You can mark a project to be deleted. +After you delete a project: -You can sort the projects by: +- Projects in personal namespaces are deleted immediately. +- Projects in groups are deleted after a retention period. -- Date created -- Date updated -- Name -- Number of stars +Prerequisites: -### Subscribe to a topic +- You must have the Owner role for a project. -If you want to know when new projects are added to a topic, you can use its RSS feed. +To delete a project: -You can do this either from the **Explore topics** page or a project with topics. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Delete this project** section, select **Delete project**. +1. On the confirmation dialog, enter the project name and select **Yes, delete project**. -To subscribe to a topic: +This action deletes the project and all associated resources (such as issues and merge requests). -- From the **Explore topics** page: +You can also [delete projects using the Rails console](#delete-a-project-using-console). - 1. On the left sidebar, expand the top-most chevron ({**chevron-down**}). - 1. Select **Explore**. - 1. Select **Topics**. - 1. Select the topic you want to subscribe to. - 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). +### Delayed project deletion **(PREMIUM ALL)** -- From a project: +> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. +> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. +> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - 1. On the left sidebar, select **Search or go to** and find your project. - 1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to. - 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). +Prerequisites: -The results are displayed as an RSS feed in Atom format. -The URL of the result contains a feed token and the list of projects that have the topic. You can add this URL to your feed reader. +- You must have the Owner role for the project. -### Assign a topic to a project +Projects in a group (not a personal namespace) can be deleted after a delay period. -You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). +On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. +On SaaS, there is a non-adjustable default retention period of seven days. -### Administer topics +You can [view projects that are pending deletion](#view-projects-pending-deletion), +and use the Rails console to +[find projects that are pending deletion](#find-projects-that-are-pending-deletion). -Instance administrators can administer all project topics from the -[Admin Area's Topics page](../../administration/admin_area.md#administering-topics). +### Delete a project immediately -## Star a project +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. +> - Option to delete projects immediately from the Admin Area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. -You can add a star to projects you use frequently to make them easier to find. +Prerequisites: -To add a star to a project: +- You must have the Owner role for the project. +- The project must be [marked for deletion](#delete-a-project). + +If you don't want to wait for delayed deletion, you can delete a project immediately. To do this, perform the steps for [deleting a projects](#delete-a-project) again. + +In the first cycle of deleting a project, the project is moved to the delayed deletion queue and automatically deleted after the retention period has passed. +If during this delayed deletion time you run a second deletion cycle, the project is deleted immediately. + +To immediately delete a project marked for deletion: 1. On the left sidebar, select **Search or go to** and find your project. -1. In the upper-right corner of the page, select **Star**. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Delete this project** section, select **Delete project**. +1. On the confirmation dialog, enter the project name and select **Yes, delete project**. -## View projects pending deletion **(PREMIUM ALL)** +### View projects pending deletion > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. > - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. @@ -206,32 +215,45 @@ You can filter projects by the programming language they use. To do this: A list of projects that use the selected language is displayed. -## Change the visibility of individual features in a project +## Rename a repository -You can change the visibility of individual features in a project. +A project's repository name defines its URL and its place on the file disk +where GitLab is installed. -Prerequisite: +Prerequisites: -- You must have the Owner role for the project. +- You must be an administrator or have the Maintainer or Owner role for the project. + +NOTE: +When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see +[redirects when renaming repositories](../project/repository/index.md#what-happens-when-a-repository-path-changes). + +To rename a repository: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Use the toggle by each feature you want to turn on or off, or change access for. -1. Select **Save changes**. +1. Expand **Advanced**. +1. In the **Change path** text box, edit the path. +1. Select **Change path**. -## Access the Project overview page by using the project ID +## Access the project overview page by using the project ID -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. +> Project ID [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. To access a project by using the project ID instead of its name, -go to `https://gitlab.example.com/projects/:id`. +go to `https://gitlab.example.com/projects/<id>`. + +To copy the project ID: -The project ID is displayed in the **Project overview** page, under the project name. +1. On the left sidebar, select **Search or go to** and find your project. +1. On the project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**). +1. Select **Copy project ID**. For example, if in your personal namespace `alex` you have a project `my-project` with the ID `123456`, you can access the project either at `https://gitlab.example.com/alex/my-project` or `https://gitlab.example.com/projects/123456`. +You might also need the project ID if you want to interact with it using the [GitLab API](../../api/index.md). + ## Who can view the Project overview page When you select a project, the **Project overview** page shows the project contents. @@ -250,147 +272,24 @@ For users without permission to view the project's code, the landing page shows: ## Leave a project +> The button to leave a project [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. + When you leave a project: - You are no longer a project member and cannot contribute. - All the issues and merge requests that were assigned to you are unassigned. -To leave a project: - -1. On the left sidebar, select **Search or go to** and find your 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](../namespace/index.md). - -## 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) with `read_api` scope. - -To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: - -```plaintext -machine gitlab.example.com -login <gitlab_user_name> -password <personal_access_token> -``` - -On Windows, Go reads `~/_netrc` instead of `~/.netrc`. - -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. - -### Authenticate Git requests - -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. - -Configure Git to either: - -- Embed credentials in the request URL: - - ```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): - -- `GOPRIVATE` -- `GONOPROXY` -- `GONOSUMDB` - -To disable fetching: - -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`. - -- 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. - -### 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: - - ```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" - ``` - - - 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. +- You can leave a project this way only when a project is part of a group under a [group namespace](../namespace/index.md). +- You must be a [direct member](members/index.md#membership-types) of the project. -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 - -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 access the Geo secondary server with HTTP: - -1. Add a Git `insteadOf` redirect on the client: - - ```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 - add the credentials in the client's `~/.netrc` file: - - ```shell - machine gitlab.example.com login USERNAME password TOKEN - machine gitlab-secondary.example.com login USERNAME password TOKEN - ``` +To leave a project: -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. +1. On the left sidebar, select **Search or go to** and find your project. +1. On the project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**). +1. Select **Leave project**, then **Leave project** again. ## Add a compliance framework to a project **(PREMIUM)** @@ -412,14 +311,6 @@ Prerequisites: 1. To use LDAP groups to manage access to a project, [add the LDAP-synchronized group as a member](../group/manage.md) to the project. -## Related topics - -- [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#create-a-fork). -- Adjust [project visibility](../../user/public_access.md#change-project-visibility) and [permissions](settings/index.md#configure-project-features-and-permissions). -- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) - ## Troubleshooting When working with projects, you might encounter the following issues, or require alternate methods to complete specific tasks. @@ -519,3 +410,11 @@ end To find features that can be toggled, run `pp p.project_feature`. Available permission levels are listed in [concerns/featurable.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/featurable.rb). + +## Related topics + +- [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#create-a-fork). +- Adjust [project visibility](../../user/public_access.md#change-project-visibility) and [permissions](settings/project_features_permissions.md#configure-project-features-and-permissions). +- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 37b79c8f1a8..b7ee354ed9a 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project and group visibility **(FREE ALL)** @@ -35,7 +34,7 @@ For internal projects, **any authenticated user**, including users with the Gues Only internal members can view internal content. -[External users](admin_area/external_users.md) cannot clone the project. +[External users](../administration/external_users.md) cannot clone the project. Internal groups can have internal or private subgroups. @@ -63,18 +62,32 @@ then `/public` is visible only to authenticated users. You can change the visibility of a project. -Prerequisite: +Prerequisites: - You must have the Owner role for a project. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. -1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. +1. From the **Project visibility** dropdown list, select an option. The visibility setting for a project must be at least as restrictive as the visibility of its parent group. 1. Select **Save changes**. +## Change the visibility of individual features in a project + +You can change the visibility of individual features in a project. + +Prerequisites: + +- You must have the Owner role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. To enable or disable a feature, turn on or off the feature toggle. +1. Select **Save changes**. + ## Change group visibility You can change the visibility of all projects in a group. @@ -87,9 +100,9 @@ Prerequisites: to private if a subgroup or project in that group is public. 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Naming, visibility**. -1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. +1. For **Visibility level**, select an option. The visibility setting for a project must be at least as restrictive as the visibility of its parent group. 1. Select **Save changes**. @@ -101,10 +114,6 @@ This setting can help prevent users from publicly exposing their repositories by For more information, see [Restrict visibility levels](../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). -## Related topics - -- [Change the visibility of features](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project) - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md index d5697ec5a94..ee89a84e3a9 100644 --- a/doc/user/read_only_namespaces.md +++ b/doc/user/read_only_namespaces.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Read-only namespaces **(FREE SAAS)** @@ -22,7 +22,7 @@ information, see [Restricted actions](#restricted-actions). To restore a namespace to its standard state, you can: - For exceeded free user limits: - - [Reduce the number of members](free_user_limit.md#manage-members-in-your-namespace) in your namespace. + - [Reduce the number of members](free_user_limit.md#manage-members-in-your-group-namespace) in your namespace. - [Start a free trial](https://gitlab.com/-/trial_registrations/new), which includes an unlimited number of members. - [Purchase a paid tier](https://about.gitlab.com/pricing/). - For exceeded storage quota: @@ -33,9 +33,9 @@ To restore a namespace to its standard state, you can: | Feature | Action restricted | |---------|-------------------| -| Container Registry | Create, edit, and delete cleanup policies <br> Push an image to the container registry | +| Container registry | Create, edit, and delete cleanup policies <br> Push an image to the container registry | | Merge Requests | Create and update an MR | -| Package Registry | Publish a package | +| Package registry | Publish a package | | Repositories | Add tags <br> Create new branches <br> Create and update commit status <br> Push and force push to non-protected branches <br> Push and force push to protected branches <br> Upload files <br> Create merge requests | | CI/CD | Create, edit, admin, and run pipelines <br> Create, edit, admin, and run builds <br> Create and edit admin environments <br> Create and edit admin deployments <br> Create and edit admin clusters <br> Create and edit admin releases | | Namespaces | **For exceeded free user limits:** Invite new users | diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index 9e13d1fe263..1eb02b2f263 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Report abuse **(FREE ALL)** @@ -43,7 +43,7 @@ To report abuse from a user's profile page: To report abuse from a user's comment: 1. In the comment, in the upper-right corner, select **More actions** (**{ellipsis_v}**). -1. Select **Report abuse to administrator**. +1. Select **Report abuse**. 1. Select a reason for reporting the user. 1. Complete an abuse report. 1. Select **Send report**. @@ -63,7 +63,7 @@ A URL to the reported user's comment is pre-filled in the abuse report's ## Report abuse from a merge request 1. On the merge request, in the upper-right corner, select **Merge request actions** (**{ellipsis_v}**). -1. Select **Report abuse to administrator**. +1. Select **Report abuse**. 1. Select a reason for reporting this user. 1. Complete an abuse report. 1. Select **Send report**. diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 697f5711396..24610e25542 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reserved project and group names **(FREE ALL)** diff --git a/doc/user/rich_text_editor.md b/doc/user/rich_text_editor.md index fe3ac56b79c..24293b9f3b1 100644 --- a/doc/user/rich_text_editor.md +++ b/doc/user/rich_text_editor.md @@ -1,8 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rich text editor **(FREE ALL)** diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index c1da3e9e2ba..3b715fb13da 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Advanced search **(PREMIUM ALL)** @@ -23,7 +22,7 @@ You can use advanced search in: - Merge requests - Milestones - Users -- Epics (in groups only) +- Epics - Code - Comments - Commits @@ -34,6 +33,7 @@ You can use advanced search in: - On GitLab.com, advanced search is enabled for groups with paid subscriptions. - For self-managed GitLab instances, an administrator must [enable advanced search](../../integration/advanced_search/elasticsearch.md#enable-advanced-search). +- For GitLab Dedicated, advanced search is enabled. ## Syntax diff --git a/doc/user/search/command_palette.md b/doc/user/search/command_palette.md index 0f42e727eda..21c0a915e3d 100644 --- a/doc/user/search/command_palette.md +++ b/doc/user/search/command_palette.md @@ -1,8 +1,7 @@ --- stage: Manage group: Foundations -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Command palette **(FREE ALL)** @@ -17,7 +16,7 @@ find an object more quickly. To open the command palette: -1. On the left sidebar, at the top, select **Search or go to** or use the <kbd>/</kbd> key to enable. +1. On the left sidebar, select **Search or go to** or use the <kbd>/</kbd> key to enable. 1. Type one of the special characters: - <kbd>></kbd> - Create a new object or find a menu item. diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md index 48445ccfc3c..f3554804397 100644 --- a/doc/user/search/exact_code_search.md +++ b/doc/user/search/exact_code_search.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Exact Code Search **(PREMIUM ALL)** @@ -33,6 +32,7 @@ This table shows some example queries for exact code search. | Query | Description | | -------------------- |-------------------------------------------------------------------------------------- | | `foo` | Returns files that contain `foo` | +| `foo file:^doc/` | Returns files that contain `foo` in directories that start with `doc/` | | `"class foo"` | Returns files that contain the exact string `class foo` | | `class foo` | Returns files that contain both `class` and `foo` | | `foo or bar` | Returns files that contain either `foo` or `bar` | @@ -42,5 +42,5 @@ This table shows some example queries for exact code search. | `foo file:js` | Searches for `foo` in files with names that contain `js` | | `foo -file:test` | Searches for `foo` in files with names that do not contain `test` | | `foo lang:ruby` | Searches for `foo` in Ruby source code | -| `foo f:\.js$` | Searches for `foo` in files with names that end with `.js` | +| `foo file:\.js$` | Searches for `foo` in files with names that end with `.js` | | `foo.*bar` | Searches for strings that match the regular expression `foo.*bar` | diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 79782b1c880..6faf45cbc3d 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Global Search -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Searching in GitLab **(FREE ALL)** diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index e504ee90821..ff1e065de65 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,8 +1,7 @@ --- stage: Manage group: Foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab keyboard shortcuts **(FREE ALL)** @@ -14,7 +13,7 @@ To display a window in GitLab that lists its keyboard shortcuts, use one of the following methods: - Press <kbd>?</kbd>. -- In the Help menu, in the upper-right corner of the application, select **Keyboard shortcuts**. +- In the lower-left corner of the application, select **Help** and then **Keyboard shortcuts**. Although [global shortcuts](#global-shortcuts) work from any area of GitLab, you must be in specific pages for the other shortcuts to be available, as @@ -77,7 +76,7 @@ relatively quickly to work, and they take you to another page in the project. | <kbd>g</kbd> + <kbd>n</kbd> | Go to the [repository graph](#repository-graph) page (**Code > Repository graph**). | | <kbd>g</kbd> + <kbd>d</kbd> | Go to repository charts (**Analyze > Repository analytics**). | | <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Plan > Issues**). | -| <kbd>i</kbd> | Go to the New Issue page (**Pan > Issues**, select **New issue** ). | +| <kbd>i</kbd> | Go to the New Issue page (**Plan > Issues**, select **New issue** ). | | <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Plan > Issue boards**). | | <kbd>g</kbd> + <kbd>m</kbd> | Go to the project [merge requests](project/merge_requests/index.md) list (**Code > Merge requests**). | | <kbd>g</kbd> + <kbd>p</kbd> | Go to the CI/CD pipelines list (**Build > Pipelines**). | diff --git a/doc/user/snippets.md b/doc/user/snippets.md index fe782227701..e1d6b857b31 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Snippets **(FREE ALL)** @@ -15,7 +14,7 @@ You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and and you can maintain your snippets with the [snippets API](../api/snippets.md). You can create and manage your snippets through the GitLab user interface, or by -using the [GitLab Workflow VS Code extension](project/repository/vscode.md). +using the [GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md).  @@ -43,20 +42,22 @@ You can create snippets in multiple ways, depending on whether you want to creat **New snippet**. - From a project: On the left sidebar, select **Create new** (**{plus}**). Below **In GitLab**, select **New snippet**. - From any other page: On the left sidebar, select **Create new** (**{plus}**) and then **New snippet**. - - If you installed the [GitLab Workflow VS Code extension](project/repository/vscode.md), + - If you installed the [GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md), use the [`Gitlab: Create snippet` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet). - **To create a project snippet**: Go to your project's page. Select **Create new** (**{plus}**). Below **In this project**, select **New snippet**. -1. Add a **Title** and **Description**. -1. Name your **File** with an appropriate extension, such as `example.rb` or `index.html`. +1. In **Title**, add a title. +1. Optional. In **Description**, describe the snippet. +1. In **Files**, give your file an appropriate name and extension, such as `example.rb` or `index.html`. 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). + [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). + If you do not provide a filename, GitLab [creates a name for you](#filenames). 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). -In GitLab versions 13.0 and later, snippets are [versioned by default](#versioned-snippets). +In GitLab 13.0 and later, snippets are [versioned by default](#versioned-snippets). ## Discover snippets @@ -84,8 +85,7 @@ To discover all snippets visible to you in GitLab, you can: Project snippets are enabled and available by default. To change their default visibility: -1. In your project, - go to **Settings**. +1. In your project, go to **Settings > General**. 1. Expand the **Visibility, project features, permissions** section, and scroll to **Snippets**. 1. Toggle the default visibility, and select whether snippets can be viewed by everyone, or only project members. @@ -95,7 +95,7 @@ default visibility: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/239) in GitLab 13.0. -In GitLab versions 13.0 and later, snippets (both personal and project snippets) +In GitLab 13.0 and later, snippets (both personal and project snippets) have version control enabled by default. This means that all snippets get their own underlying repository initialized with @@ -104,7 +104,7 @@ new commit to the default branch is recorded. Commit messages are automatically generated. The snippet's repository has only one branch. You can't delete this branch, or create other branches. -Existing snippets were automatically migrated in 13.0. Their current +Existing snippets were automatically migrated in GitLab 13.0. Their current content was saved as the initial commit to the snippets' repository. ## Filenames @@ -186,9 +186,10 @@ To embed a snippet: 1. Confirm your snippet is publicly visible: - *If it's a project snippet*, the project must be public. - The snippet is publicly visible. - - In **Project > Settings > Permissions**, the snippets - permissions are set to **Everyone with access**. -1. In your snippet's **Embed** section, select **Copy** to copy a one-line script you can add to any website or blog post. For example: + - In your project, go to **Settings > General**. Expand the **Visibility, project features, permissions** + section, and scroll to **Snippets**. Set the snippet permission to **Everyone with access**. +1. In your snippet's **Embed** section, select **Copy** to copy a one-line script + you can add to any website or blog post. For example: ```html <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> @@ -231,7 +232,7 @@ Prerequisites: To do this task: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Code > Snippets**. +1. Select **Code > Snippets**. 1. Select the snippet you want to report as spam. 1. Select **Submit as spam**. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index 482c473e285..1cce1cda20b 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use SSH keys to communicate with GitLab **(FREE ALL)** @@ -352,6 +352,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: Verify that your SSH key was added correctly. The following commands use the example hostname `gitlab.example.com`. Replace this example hostname with your GitLab instance's hostname, for example, `git@gitlab.com`. +By default, GitLab uses `git` username to authenticate. It can be different if it was [changed by the administrator](https://docs.gitlab.com/omnibus/settings/configuration.html#change-the-name-of-the-git-user-or-group). 1. To ensure you're connecting to the correct server, check the server's SSH host keys fingerprint. For: - GitLab.com, see the [SSH host keys fingerprints](gitlab_com/index.md#ssh-host-keys-fingerprints) documentation. diff --git a/doc/user/storage_management_automation.md b/doc/user/storage_management_automation.md index a83af4ab6c6..f25ae8ba92d 100644 --- a/doc/user/storage_management_automation.md +++ b/doc/user/storage_management_automation.md @@ -1,8 +1,7 @@ --- -type: howto stage: Fulfillment group: Utilization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automate storage management **(FREE ALL)** @@ -838,8 +837,8 @@ you can configure: - The number of days before an image tag can be deleted (`older_than`) WARNING: -On GitLab.com, due to the scale of the Container Registry, the number of tags deleted by this API is limited. -If your Container Registry has a large number of tags to delete, only some of them are deleted. You might need +On GitLab.com, due to the scale of the container registry, the number of tags deleted by this API is limited. +If your container registry has a large number of tags to delete, only some of them are deleted. You might need to call the API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](#create-a-cleanup-policy-for-containers) instead. The following example uses the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/repository_tags.html) to fetch a list of tags, and calls the `delete_in_bulk()` method with filter parameters. @@ -892,7 +891,7 @@ echo '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":tr You can optimize container images to reduce the image size and overall storage consumption in the container registry. Learn more in the [pipeline efficiency documentation](../ci/pipelines/pipeline_efficiency.md#optimize-docker-images). -## Manage Package Registry storage +## Manage package registry storage Package registries are available [for projects](../api/packages.md#for-a-project) or [for groups](../api/packages.md#for-a-group). diff --git a/doc/user/tasks.md b/doc/user/tasks.md index 173d2e44cf1..1ec211dcab3 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tasks **(FREE ALL)** @@ -53,6 +53,8 @@ Prerequisites: To create a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select **Add**. 1. Select **New task**. 1. Enter the task title. @@ -66,9 +68,9 @@ Prerequisites: - You must have at least the Reporter role for the project. -In an issue description with task list items: - -1. Hover over a task list item and select the options menu (**{ellipsis_v}**). +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, hover over a task list item and select the options menu (**{ellipsis_v}**). 1. Select **Convert to task**. The task list item is removed from the issue description and a task is created in the tasks widget from its contents. @@ -84,6 +86,8 @@ Prerequisites: To add a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select **Add**. 1. Select **Existing task**. 1. Search tasks by title. @@ -98,6 +102,8 @@ Prerequisites: To edit a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the task you want to edit. The task window opens. 1. Optional. To edit the title, select it and make your changes. @@ -124,7 +130,9 @@ Prerequisites: To edit the description of a task: -1. In the **Tasks** section, select the title of the task you want to edit. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Description**, select the edit icon (**{pencil}**). The description text box appears. 1. Above the text box, select **Rich text**. @@ -151,7 +159,10 @@ It's not possible to connect them again. To remove a task from an issue: -1. In the issue description, in the **Tasks** section, next to the task you want to remove, select the options menu (**{ellipsis_v}**). +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select the options menu (**{ellipsis_v}**) + next to the task you want to remove. 1. Select **Remove task**. ## Delete a task @@ -164,6 +175,8 @@ Prerequisites: To delete a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the task you want to edit. 1. In the task window, in the options menu (**{ellipsis_v}**), select **Delete task**. 1. Select **OK**. @@ -195,6 +208,8 @@ Prerequisites: To change the assignee on a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Assignees**, select **Add assignees**. @@ -211,6 +226,8 @@ Prerequisites: To add [labels](project/labels.md) to a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Labels**, select **Add labels**. 1. From the dropdown list, select the labels to add. @@ -231,6 +248,8 @@ You can set start and due dates on a task to show when work should begin and end To set a due date: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. If the task already has a due date next to **Due date**, select it. Otherwise, select **Add due date**. @@ -263,6 +282,8 @@ Prerequisites: To add a task to a milestone: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Milestone**, select **Add to milestone**. @@ -271,7 +292,8 @@ To add a task to a milestone: ## Set task weight **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3. +> - Edit button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429137) in GitLab 16.7. Prerequisites: @@ -282,10 +304,13 @@ This value is visible only when you view a task. To set issue weight of a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. -1. Next to **Weight**, enter a whole, positive number. -1. Select the close icon (**{close}**). +1. Next to **Weight**, select **Edit**. +1. Enter a whole, positive number. +1. Select **Apply** or press <kbd>Enter</kbd>. ## Add a task to an iteration **(PREMIUM ALL)** @@ -306,6 +331,8 @@ Prerequisites: To add a task to an iteration: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Iteration**, select **Add to iteration**. @@ -337,7 +364,8 @@ To refer to a task elsewhere in GitLab, you can use its full URL or a short refe To copy the task reference to your clipboard: 1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Plan > Issues**, then select your task to view it. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select your task. 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. You can now paste the reference into another description or comment. @@ -364,13 +392,15 @@ To copy the task's email address: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.5. -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the project. - The issue and task must belong to the same project. To set an issue as a parent of a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Parent**, from the dropdown list, select the parent to add. @@ -461,16 +491,16 @@ When enabled, tasks use a two-column layout, similar to issues. The description and threads are on the left, and attributes, such as labels or assignees, on the right. - + -## Linked items in Tasks +## Linked items in tasks -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `linked_work_items`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `linked_work_items`. +On GitLab.com, this feature is available. Linked items are a bi-directional relationship and appear in a block below the emoji reactions section. You can link an objective, key result, or a task in the same project with each other. @@ -479,14 +509,17 @@ The relationship only shows up in the UI if the user can see both items. ### Add a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. To link an item to a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select your task. 1. In the **Linked items** section of a task, - select the **Add** button. + select **Add**. 1. Select the relationship between the two items. Either: - **relates to** - **blocks** @@ -501,11 +534,14 @@ them categorized so their relationships can be better understood visually. ### Remove a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. -In the **Linked items** section of a task, -next to each item, select the vertical ellipsis (**{ellipsis_v}**) and then select **Remove**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select your task. +1. In the **Linked items** section of a task, next to each item, select the vertical + ellipsis (**{ellipsis_v}**) and then select **Remove**. Due to the bi-directional relationship, the relationship no longer appears in either item. diff --git a/doc/user/todos.md b/doc/user/todos.md index 8e207a786c3..9de15480a5c 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -1,7 +1,7 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # To-Do List **(FREE ALL)** diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index ae47a9156c7..8641b73e3a8 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Updating to GitLab 13.2: Email confirmation issues diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 7dea2b97249..973ad9d0b07 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -1,112 +1,85 @@ --- -type: howto stage: Fulfillment group: Utilization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Storage **(FREE ALL)** +# Storage **(FREE SAAS)** -Storage usage statistics are available for projects and namespaces. You can use that information to -manage storage usage within the applicable quotas. +All projects on GitLab SaaS have 10 GiB of free storage for their Git repository and Large File Storage (LFS). -Statistics include: +When a project's repository and LFS exceed 10 GiB, the project is set to a read-only state. +You cannot push changes to a read-only project. To increase storage of the project's repository and LFS to more than 10 GiB, +you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). -- Storage usage across projects in a namespace. -- Storage usage that exceeds the storage SaaS limit or [self-managed storage quota](../administration/settings/account_and_limit_settings.md#repository-size-limit). -- Available purchased storage for SaaS. +GitLab plans to introduce storage limits for namespaces on GitLab SaaS. After these storage limits have been applied, +storage usage will be calculated across the entire namespace and project storage limits will no longer apply. -Storage and network usage are calculated with the binary measurement system (1024 unit multiples). -Storage usage is displayed in kibibytes (KiB), mebibytes (MiB), -or gibibytes (GiB). 1 KiB is 2^10 bytes (1024 bytes), -1 MiB is 2^20 bytes (1024 kibibytes), 1 GiB is 2^30 bytes (1024 mebibytes). +## View storage **(FREE ALL)** -NOTE: -Storage usage labels are being transitioned from `KB` to `KiB`, `MB` to `MiB`, and `GB` to `GiB`. During this transition, -you might see references to `KB`, `MB`, and `GB` in the UI and documentation. +You can view the following statistics for storage usage in projects and namespaces: -## View storage usage +- Storage usage that exceeds the GitLab SaaS storage limit or [self-managed storage limits](../administration/settings/account_and_limit_settings.md#repository-size-limit). +- Available purchased storage for GitLab SaaS. Prerequisites: - To view storage usage for a project, you must have at least the Maintainer role for the project or Owner role for the namespace. - To view storage usage for a group namespace, you must have the Owner role for the namespace. +To view storage: + 1. On the left sidebar, select **Search or go to** and find your project or group. -1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select **Settings > Usage Quotas**. 1. Select the **Storage** tab to see namespace storage usage. -1. To view storage usage for a project, select one of the projects from the table at the bottom of the **Storage** tab of the **Usage Quotas** page. - -The information on the **Usage Quotas** page is updated every 90 minutes. +1. To view storage usage for a project, in the table at the bottom, select a project. Storage usage is updated every 90 minutes. If your namespace shows `'Not applicable.'`, push a commit to any project in the namespace to recalculate the storage. -### View project fork storage usage **(FREE SAAS)** +Storage and network usage is calculated with the binary measurement system (1024 unit multiples). +Storage usage is displayed in kibibytes (KiB), mebibytes (MiB), +or gibibytes (GiB). 1 KiB is 2^10 bytes (1024 bytes), +1 MiB is 2^20 bytes (1024 kibibytes), and 1 GiB is 2^30 bytes (1024 mebibytes). + +NOTE: +Storage usage labels are being transitioned from `KB` to `KiB`, `MB` to `MiB`, and `GB` to `GiB`. During this transition, +you might see references to `KB`, `MB`, and `GB` in the UI and documentation. + +## View project fork storage usage A cost factor is applied to the storage consumed by project forks so that forks consume less namespace storage than their actual size. To view the amount of namespace storage the fork has used: 1. On the left sidebar, select **Search or go to** and find your project or group. -1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select **Settings > Usage Quotas**. 1. Select the **Storage** tab. The **Total** column displays the amount of namespace storage used by the fork as a portion of the actual size of the fork on disk. The cost factor applies to the project repository, LFS objects, job artifacts, packages, snippets, and the wiki. The cost factor does not apply to private forks in namespaces on the Free plan. -## Manage storage usage - -To manage your storage, if you are a namespace Owner you can [purchase more storage for the namespace](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). - -Depending on your role, you can also use the following methods to manage or reduce your storage: - -- [Reduce package registry storage](packages/package_registry/reduce_package_registry_storage.md). -- [Reduce dependency proxy storage](packages/dependency_proxy/reduce_dependency_proxy_storage.md). -- [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md). -- [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md). -- [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). -- [Manage artifact expiration period](../ci/yaml/index.md#artifactsexpire_in). -- [Reduce build artifact storage](../ci/jobs/job_artifacts.md#delete-job-log-and-artifacts). - -To automate storage usage analysis and management, see the [storage management automation](storage_management_automation.md) documentation. - -## Set usage quotas **(FREE SELF)** - -There are no application limits on the amount of storage and transfer for self-managed instances. The administrators are responsible for the underlying infrastructure costs. Administrators can set [repository size limits](../administration/settings/account_and_limit_settings.md#repository-size-limit) to manage your repositories’ size. - -## Storage limits **(FREE SAAS)** - -### Project storage limit - -Projects on GitLab SaaS have a 10 GiB storage limit on their Git repository and LFS storage. Limits on project storage -will be removed before limits are applied to GitLab SaaS namespace storage in the future. - -When a project's repository and LFS reaches the quota, the project is set to a read-only state. -You cannot push changes to a read-only project. To monitor the size of each -repository in a namespace, including a breakdown for each project, -[view storage usage](#view-storage-usage). To allow a project's repository and LFS to exceed the free quota -you must purchase additional storage. For more details, see [Excess storage usage](#excess-storage-usage). +## Excess storage usage -#### Excess storage usage +Excess storage usage is the amount that exceeds the 10 GiB free storage of a project's repository and LFS. If no purchased storage is available, +the project is set to a read-only state. You cannot push changes to a read-only project. -Excess storage usage is the amount that a project's repository and LFS exceeds the [project storage limit](#project-storage-limit). If no -purchased storage is available the project is set to a read-only state. You cannot push changes to a read-only project. -To remove the read-only state you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) -for the namespace. When the purchase is completed, read-only projects are automatically restored to their standard state. The -amount of purchased storage available must always be greater than zero. +To remove the read-only state, you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) +for the namespace. After the purchase has completed, the read-only state is removed and projects are automatically +restored. The amount of available purchased storage must always +be greater than zero. -The **Storage** tab of the **Usage Quotas** page warns you of the following: +The **Storage** tab of the **Usage Quotas** page displays the following: - Purchased storage available is running low. - Projects that are at risk of becoming read-only if purchased storage available is zero. - Projects that are read-only because purchased storage available is zero. Read-only projects are marked with an information icon (**{information-o}**) beside their name. -#### Excess storage example +### Excess storage example -The following example describes an excess storage scenario for a namespace: +The following example describes an excess storage scenario for projects in a namespace: | Repository | Storage used | Excess storage | Quota | Status | |------------|--------------|----------------|--------|----------------------| @@ -133,23 +106,47 @@ available decreases. All projects no longer have the read-only status because 40 | Yellow | 5 GiB | 0 GiB | 10 GiB | Not read-only | | **Totals** | **45 GiB** | **10 GiB** | - | - | -### Namespace storage limit **(FREE SAAS)** +## Namespace storage limit -GitLab plans to enforce a storage limit for namespaces on GitLab SaaS. For more information, see -the FAQs for the following tiers: +GitLab plans to introduce the following storage limits per top-level group: -- [Free tier](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier). -- [Premium and Ultimate](https://about.gitlab.com/pricing/faq-paid-storage-transfer/). +| Subscription tier | Storage limit | +|-----------------------|---------------| +| Free | 5 GiB | +| Premium | 50 GiB | +| Ultimate | 250 GiB <sup>1</sup> | -Namespaces on GitLab SaaS have a [10 GiB project limit](#project-storage-limit) with a soft limit on -namespace storage. Soft storage limits are limits that have not yet been enforced by GitLab, and will become -hard limits after namespace storage limits apply. To avoid your namespace from becoming -[read-only](../user/read_only_namespaces.md) after namespace storage limits apply, -you should ensure that your namespace storage adheres to the soft storage limit. +<html> +<small> + <ol> + <li>Applies to GitLab Trial, GitLab for Open Source, GitLab for Education, and GitLab for Startups.</li> + </ol> +</small> +</html> + +If you have a multi-year contract for GitLab Premium or Ultimate, storage limits will not apply until your first renewal after GitLab introduces the namespace storage limits. + +Any additional storage you purchase before the introduction of namespace storage limits, including additional storage purchased due to project storage limits, will apply to the top-level group. + +Namespaces have a 10 GiB project limit with +a soft limit on namespace storage. After GitLab applies namespace storage limits, +soft limits will become hard limits and your namespace will be [read-only](../user/read_only_namespaces.md). + +To prevent your namespace from becoming read-only: + +- Manage your storage usage. +- [Purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). +- If you are eligible, apply for a [community program subscription](../subscriptions/community_programs.md): + - GitLab for Education + - GitLab for Open Source + - GitLab for Startups +- If you have GitLab Free, [start a trial](https://about.gitlab.com/free-trial/) or upgrade to [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), which has higher storage limits and more features. +- Consider a self-managed subscription, which does not have storage limits. +- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. -Namespace storage limits do not apply to self-managed deployments, but administrators can [manage the repository size](../administration/settings/account_and_limit_settings.md#repository-size-limit). +### Storage types in namespace storage usage -Storage types that add to the total namespace storage are: +Storage types that count toward the total namespace storage are: - Git repository - Git LFS @@ -160,25 +157,33 @@ Storage types that add to the total namespace storage are: - Wiki - Snippets -If your total namespace storage exceeds the available namespace storage quota, all projects under the namespace become read-only. Your ability to write new data is restricted until the read-only state is removed. For more information, see [Restricted actions](../user/read_only_namespaces.md#restricted-actions). +### Excess storage notifications -To notify you that you have nearly exceeded your namespace storage quota: +Storage limits are included in GitLab subscription terms but do not apply. At least 60 days before GitLab introduces storage limits, +GitLab will notify you of namespaces that exceed, or are close to exceeding, the storage limit. -- In the command-line interface, a notification displays after each `git push` action when your namespace has reached between 95% and 100%+ of your namespace storage quota. -- In the GitLab UI, a notification displays when your namespace has reached between 75% and 100%+ of your namespace storage quota. -- GitLab sends an email to members with the Owner role to notify them when namespace storage usage is at 70%, 85%, 95%, and 100%. +- In the command-line interface, a notification displays after each `git push` +action when your namespace has reached between 95% and 100% of your namespace storage quota. +- In the GitLab UI, a notification displays when your namespace has reached between +75% and 100% of your namespace storage quota. +- GitLab sends an email to members with the Owner role to notify them when namespace +storage usage is at 70%, 85%, 95%, and 100%. -To prevent exceeding the namespace storage limit, you can: +## Manage storage usage -- [Manage your storage usage](#manage-storage-usage). -- If you meet the eligibility requirements, you can apply for: - - [GitLab for Education](https://about.gitlab.com/solutions/education/join/) - - [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/) - - [GitLab for Startups](https://about.gitlab.com/solutions/startups/) -- Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab, which does not have these limits on the Free tier. -- [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60 per year for 10 GiB of storage. -- [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), which include higher limits and features to enable growing teams to ship faster without sacrificing on quality. -- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. +To manage your storage, if you are a namespace Owner, you can [purchase more storage for the namespace](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). + +Depending on your role, you can also use the following methods to manage or reduce your storage: + +- [Reduce package registry storage](packages/package_registry/reduce_package_registry_storage.md). +- [Reduce dependency proxy storage](packages/dependency_proxy/reduce_dependency_proxy_storage.md). +- [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md). +- [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md). +- [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). +- [Manage artifact expiration period](../ci/yaml/index.md#artifactsexpire_in). +- [Reduce build artifact storage](../ci/jobs/job_artifacts.md#delete-job-log-and-artifacts). + +To automate storage usage analysis and management, see [storage management automation](storage_management_automation.md). ## Related Topics diff --git a/doc/user/version.md b/doc/user/version.md index b7846988e06..d39c0394610 100644 --- a/doc/user/version.md +++ b/doc/user/version.md @@ -1,7 +1,7 @@ --- stage: none group: none -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Find the GitLab version diff --git a/doc/user/workspace/configuration.md b/doc/user/workspace/configuration.md index 3684845c2c7..7c365611742 100644 --- a/doc/user/workspace/configuration.md +++ b/doc/user/workspace/configuration.md @@ -1,23 +1,14 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspace configuration **(PREMIUM ALL BETA)** +# Workspace configuration **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default this feature is available. -To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. -On GitLab.com, this feature is available. -The feature is not ready for production use. - -WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. -To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. You can use [workspaces](index.md) to create and manage isolated development environments for your GitLab projects. Each workspace includes its own set of dependencies, libraries, and tools, @@ -29,26 +20,19 @@ which you can customize to meet the specific needs of each project. ### Prerequisites -- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. +- Set up a Kubernetes cluster that the GitLab agent supports. See the [supported Kubernetes versions](../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features). - Ensure autoscaling for the Kubernetes cluster is enabled. -- In the Kubernetes cluster, verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) +- In the Kubernetes cluster: + - Verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) is defined so that volumes can be dynamically provisioned for each workspace. -- In the Kubernetes cluster, install an Ingress controller of your choice (for example, `ingress-nginx`) - and make that controller accessible over a domain. For example, point `*.workspaces.example.dev` and - `workspaces.example.dev` to the load balancer exposed by the Ingress controller. -- In the Kubernetes cluster, [install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). -- In the Kubernetes cluster, [install the GitLab agent for Kubernetes](../clusters/agent/install/index.md). -- Configure remote development settings for the GitLab agent with this snippet and update `dns_zone` as needed: - - ```yaml - remote_development: - enabled: true - dns_zone: "workspaces.example.dev" - ``` - - You can use any agent defined under the root group of your project, - provided that remote development is properly configured for that agent. + - Install an Ingress controller of your choice (for example, `ingress-nginx`) and make + that controller accessible over a domain. + - In development environments, add an entry to the `/etc/hosts` file or update your DNS records. + - In production environments, point `*.<workspaces.example.dev>` and `<workspaces.example.dev>` + to the load balancer exposed by the Ingress controller. + - [Install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). + - [Install](../clusters/agent/install/index.md) and [configure](gitlab_agent_configuration.md) the GitLab agent. - You must have at least the Developer role in the root group. - In each project you want to use this feature for, create a [devfile](index.md#devfile): 1. On the left sidebar, select **Search or go to** and find your project. @@ -101,7 +85,7 @@ When you connect to `gitlab-workspaces-proxy` through the TCP load balancer, ### Set up `gitlab-workspaces-proxy` for SSH connections -Prerequisite: +Prerequisites: - You must have an SSH host key for client verification. @@ -177,18 +161,6 @@ RUN chmod 775 /etc/shadow USER gitlab-workspaces ``` -## Disable remote development in the GitLab agent for Kubernetes - -You can stop the `remote_development` module of the GitLab agent for Kubernetes from communicating with GitLab. -To disable remote development in the GitLab agent configuration, set this property: - -```yaml -remote_development: - enabled: false -``` - -If you already have running workspaces, an administrator must manually delete these workspaces in Kubernetes. - ## Related topics - [Quickstart guide for GitLab remote development workspaces](https://go.gitlab.com/AVKFvy) diff --git a/doc/user/workspace/create_image.md b/doc/user/workspace/create_image.md index df70ff31194..6da12b2f70a 100644 --- a/doc/user/workspace/create_image.md +++ b/doc/user/workspace/create_image.md @@ -1,19 +1,14 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Create a custom workspace image that supports arbitrary user IDs **(PREMIUM ALL BETA)** +# Tutorial: Create a custom workspace image that supports arbitrary user IDs **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. - -WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. In this tutorial, you'll learn how to create a custom workspace image that supports arbitrary user IDs. You can then use this custom image with any [workspace](index.md) you create in GitLab. @@ -23,12 +18,12 @@ To create a custom workspace image that supports arbitrary user IDs, you'll: 1. [Create a base Dockerfile](#create-a-base-dockerfile). 1. [Add support for arbitrary user IDs](#add-support-for-arbitrary-user-ids). 1. [Build the custom workspace image](#build-the-custom-workspace-image). -1. [Push the custom workspace image to the GitLab Container Registry](#push-the-custom-workspace-image-to-the-gitlab-container-registry). +1. [Push the custom workspace image to the GitLab container registry](#push-the-custom-workspace-image-to-the-gitlab-container-registry). 1. [Use the custom workspace image in GitLab](#use-the-custom-workspace-image-in-gitlab). ## Prerequisites -- A GitLab account with permission to create and push container images to the GitLab Container Registry +- A GitLab account with permission to create and push container images to the GitLab container registry - Docker installation ## Create a base Dockerfile @@ -78,9 +73,9 @@ docker run -ti my-gitlab-workspace sh You should now be able to run commands as the `gitlab-workspaces` user. -## Push the custom workspace image to the GitLab Container Registry +## Push the custom workspace image to the GitLab container registry -To push the custom workspace image to the GitLab Container Registry: +To push the custom workspace image to the GitLab container registry: 1. Sign in to your GitLab account: @@ -88,19 +83,19 @@ To push the custom workspace image to the GitLab Container Registry: docker login registry.gitlab.com ``` -1. Tag the image with the GitLab Container Registry URL: +1. Tag the image with the GitLab container registry URL: ```shell docker tag my-gitlab-workspace registry.gitlab.com/your-namespace/my-gitlab-workspace:latest ``` -1. Push the image to the GitLab Container Registry: +1. Push the image to the GitLab container registry: ```shell docker push registry.gitlab.com/your-namespace/my-gitlab-workspace:latest ``` -Now that you've pushed the custom workspace image to the GitLab Container Registry, you can use the image in GitLab. +Now that you've pushed the custom workspace image to the GitLab container registry, you can use the image in GitLab. ## Use the custom workspace image in GitLab diff --git a/doc/user/workspace/gitlab_agent_configuration.md b/doc/user/workspace/gitlab_agent_configuration.md new file mode 100644 index 00000000000..0e35c72c5ef --- /dev/null +++ b/doc/user/workspace/gitlab_agent_configuration.md @@ -0,0 +1,154 @@ +--- +stage: Create +group: IDE +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab agent configuration **(PREMIUM ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. + +When you [set up a workspace](configuration.md#set-up-a-workspace), +you must configure the GitLab agent for remote development. +The remote development settings are available in the agent +configuration file under `remote_development`. + +You can use any agent defined under the root group of your project, +provided that the agent is properly configured for remote development. + +## Remote development settings + +| Setting | Description | +|-------------------------------------------------------|:---------------------------------------------------------------------| +| [`enabled`](#enabled) | Indicates whether remote development is enabled for the GitLab agent | +| [`dns_zone`](#dns_zone) | DNS zone where workspaces are available | +| [`gitlab_workspaces_proxy`](#gitlab_workspaces_proxy) | Namespace where [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed | +| [`network_policy`](#network_policy) | Firewall rules for workspaces | + +NOTE: +If a setting has an invalid value, it's not possible to update any setting until you fix that value. + +### `enabled` + +Use this setting to define whether: + +- The GitLab agent can communicate with the GitLab instance. +- You can [create a workspace](configuration.md#set-up-a-workspace) with the GitLab agent. + +The default value is `false`. + +To enable remote development in the agent configuration, set `enabled` to `true`: + +```yaml +remote_development: + enabled: true +``` + +If remote development is disabled, an administrator must manually delete any +running workspaces to remove those workspaces from the Kubernetes cluster. + +### `dns_zone` + +Use this setting to define the DNS zone of the URL where workspaces are available. +When you set `dns_zone`, you can no longer update the setting. + +**Example configuration:** + +```yaml +remote_development: + dns_zone: "<workspaces.example.dev>" +``` + +### `gitlab_workspaces_proxy` + +Use this setting to define the namespace where +[`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed. +The default value for `gitlab_workspaces_proxy.namespace` is `gitlab-workspaces`. + +**Example configuration:** + +```yaml +remote_development: + gitlab_workspaces_proxy: + namespace: "<custom-gitlab-workspaces-proxy-namespace>" +``` + +### `network_policy` + +Use this setting to define the network policy for each workspace. +This setting controls network traffic for workspaces. + +The default value is: + +```yaml +remote_development: + network_policy: + egress: + - allow: "0.0.0.0/0" + except: + - "10.0.0.0/8" + - "172.16.0.0/12" + - "192.168.0.0/16" +``` + +In this configuration: + +- The network policy is generated for each workspace because `enabled` is `true`. +- The egress rules allow all traffic to the internet (`0.0.0.0/0`) except to the + IP CIDR ranges `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16`. + +The behavior of the network policy depends on the Kubernetes network plugin. +For more information, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/). + +#### `network_policy.enabled` + +Use this setting to define whether the network policy is generated for each workspace. +The default value for `network_policy.enabled` is `true`. + +#### `network_policy.egress` + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11629) in GitLab 16.7. + +Use this setting to define a list of IP CIDR ranges to allow as egress destinations from a workspace. + +Define egress rules when: + +- The GitLab instance is on a private IP range. +- The workspace must access a cloud resource on a private IP range. + +Each element of the list defines an `allow` attribute with an optional `except` attribute. +`allow` defines an IP range to allow traffic from. +`except` lists IP ranges to exclude from the `allow` range. + +**Example configuration:** + +```yaml +remote_development: + network_policy: + egress: + - allow: "0.0.0.0/0" + except: + - "10.0.0.0/8" + - "172.16.0.0/12" + - "192.168.0.0/16" + - allow: "172.16.123.1/32" +``` + +In this example, traffic from the workspace is allowed if: + +- The destination IP is any range except `10.0.0.0/8`, `172.16.0.0/12`, or `192.168.0.0/16`. +- The destination IP is `172.16.123.1/32`. + +## Configuring user access with remote development + +You can configure the `user_access` module to access the connected Kubernetes cluster with your GitLab credentials. +This module is configured and runs independently of the `remote_development` module. + +Be careful when configuring both `user_access` and `remote_development` in the same GitLab agent. +The `remote_development` clusters manage user credentials (such as personal access tokens) as Kubernetes Secrets. +Any misconfiguration in `user_access` might cause this private data to be accessible over the Kubernetes API. + +For more information about configuring `user_access`, see +[Configure Kubernetes access](../../user/clusters/agent/user_access.md#configure-kubernetes-access). diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 21905381577..d24102afcf9 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -1,23 +1,14 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspaces **(PREMIUM ALL BETA)** +# Workspaces **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default this feature is available. -To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. -On GitLab.com, this feature is available. -The feature is not ready for production use. - -WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. -To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. A workspace is a virtual sandbox environment for your code in GitLab. You can use workspaces to create and manage isolated development environments for your GitLab projects. |
