diff options
Diffstat (limited to 'doc/user')
284 files changed, 4615 insertions, 3023 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md index 2d19c0a0058..31cc9825452 100644 --- a/doc/user/admin_area/analytics/dev_ops_reports.md +++ b/doc/user/admin_area/analytics/dev_ops_reports.md @@ -39,7 +39,7 @@ feature is available. ## DevOps Adoption **(ULTIMATE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/alpha-beta-support.md#beta-features). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/alpha-beta-support.md#beta). > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. > - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index b9850048e7d..a5311b083c3 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -2,7 +2,6 @@ stage: none group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- # GitLab Appearance **(FREE SELF)** diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 78819def5de..ea42596059e 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -41,6 +41,24 @@ To select the group to use as the source for the project templates: Projects in subgroups of the template group are **not** included in the template list. +## What is copied from the templates + +The entire custom instance-level project templates repository is copied, including: + +- Branches +- Commits +- Tags + +If the user: + +- Has the Owner role on the custom instance-level project templates project or is a GitLab administrator, all project settings are copied over to the new + project. +- Doesn't have the Owner role or is not a GitLab administrator, project [deploy keys](../project/deploy_keys/index.md#view-deploy-keys) and project + [webhooks](../project/integrations/webhooks.md) aren't copied over because they contain sensitive data. + +To learn more about what is migrated, see +[Items that are exported](../project/settings/import_export.md#items-that-are-exported). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/external_users.md b/doc/user/admin_area/external_users.md index 8b968a3da01..5127630d65e 100644 --- a/doc/user/admin_area/external_users.md +++ b/doc/user/admin_area/external_users.md @@ -48,6 +48,7 @@ Additionally, users can be set as external users using: - [SAML groups](../../integration/saml.md#external-groups). - [LDAP groups](../../administration/auth/ldap/ldap_synchronization.md#external-groups). +- the [External providers list](../../integration/omniauth.md#create-an-external-providers-list). ## Set a new user to external diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index 8e1ca979707..16721d144e5 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -10,6 +10,7 @@ type: reference To manage labels for the GitLab instance, select **Labels** (**{labels}**) from the Admin Area sidebar. For more details on how to manage labels, see [Labels](../project/labels.md). Labels created in the Admin Area are automatically added to new projects. +They are not available to new groups. Updating or adding labels in the Admin Area does not modify labels in existing projects.  diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index a273798c8eb..b0e24559e47 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -5,7 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Moderate users **(FREE SELF)** +# Moderate users (administration) **(FREE SELF)** + +This is the administration documentation. For information about moderating users at the group level, see the [group-level documentation](../group/moderate_users.md). GitLab administrators can moderate user access by approving, blocking, banning, or deactivating users. @@ -161,8 +163,8 @@ A user can be deactivated from the Admin Area. To do this: For the deactivation option to be visible to an administrator, the user: -- Must be currently active. -- Must not be [dormant](#automatically-deactivate-dormant-users). +- Must have a state of active. +- Must be [dormant](#automatically-deactivate-dormant-users). NOTE: Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 668d34af024..f3b09c61532 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -92,8 +92,6 @@ Example response: On failure, the endpoint returns a `503` HTTP status code. -This check does hit the database and Redis if authenticated via `token`. - This check is being exempt from Rack Attack. ## Liveness diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md index 1dd9497fed9..83b28404714 100644 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ b/doc/user/admin_area/reporting/git_abuse_rate_limit.md @@ -4,27 +4,17 @@ 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 --- -# Git abuse rate limit (administration) **(ULTIMATE)** +# Git abuse rate limit (administration) **(ULTIMATE SELF)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/394996) in GitLab 15.10. Feature flag `git_abuse_rate_limit_feature_flag` removed. This is the administration documentation. For information about Git abuse rate limiting at the group level, see the [group-level documentation](../../group/reporting/git_abuse_rate_limit.md). -Git abuse rate limiting is a feature to automatically [ban users](../moderate_users.md#ban-and-unban-users) who download or clone more than a specified number of repositories in any project in the instance in a given time frame. Banned users cannot sign in to the instance and cannot access any non-public group via HTTP or SSH. The rate limit also applies to users who authenticate with a [personal](../../../user/profile/personal_access_tokens.md) or [group access token](../../../user/group/settings/group_access_tokens.md). +Git abuse rate limiting is a feature to automatically [ban users](../moderate_users.md#ban-and-unban-users) who download, clone, or fork more than a specified number of repositories in any project in the instance in a given time frame. Banned users cannot sign in to the instance and cannot access any non-public group via HTTP or SSH. The rate limit also applies to users who authenticate with a [personal](../../../user/profile/personal_access_tokens.md) or [group access token](../../../user/group/settings/group_access_tokens.md). Git abuse rate limiting does not apply to instance administrators, [deploy tokens](../../../user/project/deploy_tokens/index.md), or [deploy keys](../../../user/project/deploy_keys/index.md). -## Automatic ban notifications - -If the `git_abuse_rate_limit_feature_flag` feature flag is enabled, selected users receive an email when a user is about to be banned. - -If automatic banning is disabled, a user is not banned automatically when they exceed the limit. However, notifications are still sent. You can use this setup to determine the correct values of the rate limit settings before enabling automatic banning. - -If automatic banning is enabled, an email notification is sent when a user is about to be banned, and the user is automatically banned from the GitLab instance. - ## Configure Git abuse rate limiting 1. On the top bar, select **Main menu > Admin**. @@ -38,6 +28,12 @@ If automatic banning is enabled, an email notification is sent when a user is ab 1. Optional. Turn on the **Automatically ban users from this namespace when they exceed the specified limits** toggle to enable automatic banning. 1. Select **Save changes**. +## Automatic ban notifications + +If automatic banning is disabled, a user is not banned automatically when they exceed the limit. However, notifications are still sent to the users listed under **Send notifications to**. You can use this setup to determine the correct values of the rate limit settings before enabling automatic banning. + +If automatic banning is enabled, an email notification is sent when a user is about to be banned, and the user is automatically banned from the GitLab instance. + ## Unban a user 1. On the top bar, select **Main menu > Admin**. diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index b8531fded18..314e0c77f36 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Authentication and Authorization +stage: Anti-Abuse +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 type: reference, howto --- diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 8f7081a909d..5d5cd15372a 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -148,7 +148,7 @@ are locked against deletion and kept regardless of the expiry time. When disabled, the latest artifacts for any **new** successful or fixed pipelines are allowed to expire. -This setting takes precedence over the [project level setting](../../../ci/pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). +This setting takes precedence over the [project level setting](../../../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). If disabled at the instance level, you cannot enable this per-project. To disable the setting: @@ -227,6 +227,7 @@ from the Admin Area: - **Maximum number of DAG dependencies that a job can have** - **Maximum number of runners registered per group** - **Maximum number of runners registered per project** + - **Maximum number of downstream pipelines in a pipeline's hierarchy tree** ## Enable or disable the pipeline suggestion banner @@ -345,8 +346,8 @@ To restrict all users in an instance from registering runners: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runners**. -1. Clear the checkbox if you don't want to display runner registration - information in the UI for group or project members. +1. In the **Runner registration** section, clear the **Members of the project can register runners** and + **Members of the group can register runners** checkboxes to remove runner registration from the UI. 1. Select **Save changes**. NOTE: @@ -370,6 +371,20 @@ To restrict runner registration by members in a specific group: 1. Clear the **New group runners can be registered** checkbox if you want to disable runner registration by all members in the group. If the setting is read-only, you must enable runner registration for the [instance](#restrict-runner-registration-by-all-users-in-an-instance). 1. Select **Save changes**. +## Disable runner version management + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114041) in GitLab 15.10. + +By default, GitLab instances periodically fetch official runner version data from GitLab.com to [determine whether the runners need upgrades](../../../ci/runners/configure_runners.md#determine-which-runners-need-to-be-upgraded). + +To disable your instance fetching this data: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runners**. +1. In the **Runner version management** section, clear the **Fetch GitLab Runner release version data from GitLab.com** checkbox. +1. Select **Save changes**. + ## Troubleshooting ### 413 Request Entity Too Large diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 484f51d8739..90852463e9d 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -86,12 +86,13 @@ To disable these notifications: ### Custom additional text in deactivation emails **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355964) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `deactivation_email_additional_text`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355964) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `deactivation_email_additional_text`. Disabled by default. +> - [Enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111882) in GitLab 15.9. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an -administrator to [enable the feature flag](../../../administration/feature_flags.md) named -`deactivation_email_additional_text`. On GitLab.com, this feature is unavailable. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the feature flag](../../../administration/feature_flags.md) named +`deactivation_email_additional_text`. You can add additional text at the bottom of the email that GitLab sends to users when their account is deactivated. This email text is separate from the [custom additional text](#custom-additional-text) diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 07d3ae83d74..5d9fc23aaff 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -71,14 +71,7 @@ You can specify a custom URL to which users are directed when they: > - [Feature flag `help_page_documentation_redirect`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71737) removed in GitLab 14.4. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71737) in GitLab 14.4. -The `/help` URL of a GitLab instance displays a basic version of the documentation sourced from the -[`doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) of GitLab. `/help` links -are often used for contextual help. - -You can redirect these `/help` links to either: - -- The more navigable and searchable version published at [`docs.gitlab.com`](https://docs.gitlab.com). -- A destination that meets [necessary requirements](#destination-requirements). +You can redirect all `/help` links to a destination that meets the [necessary requirements](#destination-requirements). 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. @@ -86,17 +79,19 @@ You can redirect these `/help` links to either: 1. In the **Documentation pages URL** field, enter the URL. 1. Select **Save changes**. +If the "Documentation pages URL" field is empty, the GitLab instance displays a basic version of the documentation sourced from the [`doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) of GitLab. + ### Destination requirements When redirecting `/help`, GitLab: - Redirects requests to the specified URL. -- Appends `ee` and the documentation path to the URL. +- Appends `ee` and the documentation path, which includes the version number, to the URL. - Appends `.html` to the URL, and removes `.md` if necessary. For example, if the URL is set to `https://docs.gitlab.com`, requests for `/help/user/admin_area/settings/help_page.md` redirect to: -`https://docs.gitlab.com/ee/user/admin_area/settings/help_page.html`. +`https://docs.gitlab.com/${VERSION}/ee/user/admin_area/settings/help_page.html`. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 5c4d7ee4be0..11c14102efb 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -66,6 +66,10 @@ The **CI/CD** settings contain: [risks are involved](../../packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries) in enabling some of these settings. +## Security and Compliance settings + +- [License compliance settings](security_and_compliance.md#choose-package-registry-metadata-to-sync): Enable or disable synchronization of package metadata by a registry type. + ### Geo **(PREMIUM SELF)** The **Geo** setting contains: @@ -136,6 +140,7 @@ The **Network** settings contain: number of inbound alerts that can be sent to a project. - [Notes creation limit](rate_limit_on_notes_creation.md) - Set a rate limit on the note creation requests. - [Get single user limit](rate_limit_on_users_api.md) - Set a rate limit on users API endpoint to get a user by ID. +- [Projects API rate limits for unauthenticated requests](rate_limit_on_projects_api.md) - Set a rate limit on Projects list API endpoint for unauthenticated requests. ### Preferences diff --git a/doc/user/admin_area/settings/security_and_compliance.md b/doc/user/admin_area/settings/security_and_compliance.md new file mode 100644 index 00000000000..13abf1027cd --- /dev/null +++ b/doc/user/admin_area/settings/security_and_compliance.md @@ -0,0 +1,20 @@ +--- +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 +type: howto +--- + +# Security and Compliance Admin Area settings **(ULTIMATE SELF)** + +The settings for package metadata synchronization are located in the [Admin Area](index.md). + +## Choose package registry metadata to sync + +To choose the packages you want to synchronize with the GitLab License Database for [License Compliance](../../compliance/license_scanning_of_cyclonedx_files/index.md): + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > Security and Compliance**. +1. Expand **License Compliance**. +1. Select or clear checkboxes for the package registries that you want to sync. +1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 82a54787101..a3558991e36 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -158,7 +158,7 @@ see [Email notification for unknown sign-ins](../../profile/notifications.md#not All users that are not logged in are redirected to the page represented by the configured **Home page URL** if value is not empty. -All users are redirected to the page represented by the configured **After sign-out path** +All users are redirected to the page represented by the configured **Sign-out page URL** after sign out if value is not empty. In the **Sign-in restrictions** section, scroll to the **Sign-in text** field. You can add a diff --git a/doc/user/admin_area/settings/terraform_limits.md b/doc/user/admin_area/settings/terraform_limits.md index 4e54c7a3459..05b1f2d8838 100644 --- a/doc/user/admin_area/settings/terraform_limits.md +++ b/doc/user/admin_area/settings/terraform_limits.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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: reference --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 212769ed89b..1db62bce056 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -1,6 +1,6 @@ --- stage: Analytics -group: Product Intelligence +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 --- @@ -119,6 +119,11 @@ To enable or disable Service Ping and version check: 1. Select or clear the **Enable version check** and **Enable Service Ping** checkboxes. 1. Select **Save changes**. +NOTE: +Service Ping settings only control whether the data is being shared with GitLab, or used only internally. +Even if you disable Service Ping, the `gitlab_service_ping_worker` background job still periodically generates a Service Ping payload for your instance. +The payload is available in the [Service Usage data](#manually-upload-service-ping-payload) admin section. + ## Disable usage statistics with the configuration file NOTE: @@ -194,6 +199,11 @@ To upload the payload manually: The uploaded file is encrypted and sent using secure HTTPS protocol. HTTPS creates a secure communication channel between web browser and the server, and protects transmitted data against man-in-the-middle attacks. +If there are problems with the manual upload: + +1. Open a confidential issue in the [security fork of version app project](https://gitlab.com/gitlab-org/security/version.gitlab.com). +1. Attach the JSON payload if possible. +1. Tag `@gitlab-org/analytics-section/product-intelligence` who will triage the issue. <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index cd0b461c26b..07067945ea6 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -54,6 +54,7 @@ By default both administrators and anyone with the **Owner** role can delete a p > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) from default delayed project deletion in GitLab 15.1. > - [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. +> - [Removed option to delete immediately](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `always_perform_delayed_deletion`. Disabled by default. Instance-level protection against accidental deletion of groups and projects. @@ -82,6 +83,7 @@ To configure delayed project deletion: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: + - (GitLab 15.11 and later with `always_perform_delayed_deletion` feature flag enabled) **Deletion protection** and set the retention period to a value between `1` and `90`. - (GitLab 15.1 and later) **Deletion protection** and select keep deleted groups and projects, and select a retention period. - (GitLab 15.0 and earlier) **Default delayed project protection** and select **Enable delayed project deletion by default for newly-created groups.** Then set a retention period in **Default deletion delay**. @@ -98,6 +100,10 @@ In GitLab 15.1, and later this setting is enforced on groups when disabled and i Groups remain restorable if the retention period is `1` or more days. In GitLab 15.1 and later, delayed group deletion can be enabled by setting **Deletion projection** to **Keep deleted**. +In GitLab 15.11 and later with the `always_perform_delayed_deletion` feature flag enabled: + +- The **Keep deleted** option is removed. +- Delayed group deletion is the default. ### Override defaults and delete immediately diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 4130ff6e036..bde7fdc6c2d 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -39,7 +39,7 @@ To view CI/CD analytics: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. -The deployment frequency charts show information about the deployment +The [deployment frequency](dora_metrics.md#deployment-frequency) charts show information about the deployment frequency to the `production` environment. The environment must be part of the [production deployment tier](../../ci/environments/index.md#deployment-tier-of-environments) for its deployment information to appear on the graphs. @@ -60,7 +60,7 @@ To view the deployment frequency chart: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250329) in GitLab 13.11. -The lead time for changes chart shows information about how long it takes for +The [lead time for changes](dora_metrics.md#lead-time-for-changes) chart shows information about how long it takes for merge requests to be deployed to a production environment. This chart is available for groups and projects. - Small lead times indicate fast, efficient deployment @@ -82,7 +82,7 @@ To view the lead time for changes chart: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356959) in GitLab 15.1 -The time to restore service chart shows information about the median time an incident was open in a production environment. This chart is available for groups and projects. +The [time to restore service](dora_metrics.md#time-to-restore-service) chart shows information about the median time an incident was open in a production environment. This chart is available for groups and projects. Time to restore service is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. @@ -98,7 +98,7 @@ To view the time to restore service chart: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357072) in GitLab 15.2 -The change failure rate chart shows information about the percentage of deployments that cause an incident in a production environment. This chart is available for groups and projects. +The [change failure rate](dora_metrics.md#change-failure-rate) chart shows information about the percentage of deployments that cause an incident in a production environment. This chart is available for groups and projects. Change failure rate is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index fae9545003f..2e76252f7d3 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -5,7 +5,6 @@ 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 --- - # Code review analytics **(PREMIUM)** > Moved to GitLab Premium in 13.9. @@ -24,6 +23,9 @@ and improve your code review process. - Opportunities to accelerate your development cycle. - 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). + ## View code review analytics Prerequisite: diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index b85ec60f00e..70ce005dfb9 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -15,19 +15,15 @@ Using these metrics helps improve DevOps efficiency and communicate performance DORA includes four key metrics, divided into two core areas of DevOps: -- [Deployment Frequency](#deployment-frequency) and [Lead Time for Change](#lead-time-for-changes) measure team velocity. -- [Change Failure Rate](#change-failure-rate) and [Time to Restore Service](#time-to-restore-service) measure stability. +- [Deployment frequency](#deployment-frequency) and [Lead time for changes](#lead-time-for-changes) measure team velocity. +- [Change failure rate](#change-failure-rate) and [Time to restore service](#time-to-restore-service) measure stability. For software leaders, tracking velocity alongside quality metrics ensures they're not sacrificing quality for speed. -<div class="video-fallback"> - For an overview, see <a href="https://www.youtube.com/watch?v=1BrcMV6rCDw">GitLab Speed Run: DORA metrics in GitLab One DevOps Platform</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/1BrcMV6rCDw" frameborder="0" allowfullscreen> </iframe> -</figure> +<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). -## DORA Metrics dashboard in Value Stream Analytics +## DORA metrics dashboard in Value Stream Analytics The four DORA metrics are available out-of-the-box in the [Value Stream Analytics (VSA) overview dashboard](../group/value_stream_analytics/index.md#view-value-stream-analytics). This helps you visualize the engineering work in the context of end-to-end value delivery. @@ -140,7 +136,7 @@ The DORA metrics are displayed on the following charts: The table below provides an overview of the DORA metrics' data aggregation in different charts. -| Metric name | Measured values | Data aggregation in the [Value Streams Dashboard](value_streams_dashboard.md) | Data aggregation in CI/CD analytics charts | Data aggregation in Value stream analytics | Data aggregation in Custom insights reporting | +| Metric name | Measured values | Data aggregation in the [Value Streams Dashboard](value_streams_dashboard.md) | Data aggregation in [CI/CD analytics charts](ci_cd_analytics.md) | Data aggregation in Value stream analytics | Data aggregation in [Custom insights reporting](../../user/project/insights/index.md#dora-query-parameters) | |---------------------------|-------------------|-----------------------------------------------------|------------------------|-----------------------|----------| | Deployment frequency | Number of successful deployments | daily average per month | daily average | daily average | `day` (default) or `month` | | Lead time for changes | Number of seconds to successfully deliver a commit into production | daily median per month | median time | median time | `day` (default) or `month` | @@ -158,6 +154,26 @@ These deployment records are not created for pull-based deployments, for example 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). +### 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). + +### 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. + +For others incident management tools, you can set up the +[HTTP integration](../../operations/incident_management/integrations.md#http-endpoints), +and use it to automatically: + +1. [Create an incident when an alert is triggered](../../operations/incident_management/manage_incidents.md#automatically-when-an-alert-is-triggered). +1. [Close incidents via recovery alerts](../../operations/incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts). + ### Supported DORA metrics in GitLab | Metric | Level | API | UI chart | Comments | diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 774063810f3..44af9dc9dea 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -59,7 +59,7 @@ You can use the following analytics features to analyze and visualize the perfor - [Value stream analytics for groups](../group/value_stream_analytics/index.md) - [Value streams dashboard](value_streams_dashboard.md) -## Definitions +## Glossary We use the following terms to describe GitLab analytics: diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index f22a6a483b8..292a6f430d9 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,246 +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 +remove_date: '2023-07-22' +redirect_to: '../group/value_stream_analytics/index.md' --- # Value stream analytics for projects **(FREE)** -> - Introduced as cycle analytics prior to GitLab 12.3 at the project level. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab Premium 12.3 at the group level. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from cycle analytics to value stream analytics in GitLab 12.8. +This document was moved to [another location](../group/value_stream_analytics/index.md). -Value stream analytics provides metrics about each stage of your software development process. - -A **value stream** is the entire work process that delivers value to customers. For example, -the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts -with the Manage stage and ends with the Protect stage. - -Use value stream analytics to identify: - -- The amount of time it takes to go from an idea to production. -- The velocity of a given project. -- Bottlenecks in the development process. -- Factors that cause your software development lifecycle to slow down. - -Value stream analytics is also available for [groups](../group/value_stream_analytics). - -## View value stream analytics - -> - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 -> - Sorting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. - -To view value stream analytics for your project: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Value stream**. -1. To view metrics for a particular stage, select a stage below the **Filter results** text box. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. -1. Optional. Sort results by ascending or descending: - - To sort by most recent or oldest workflow item, select the **Last event** header. - - To sort by most or least amount of time spent in each stage, select the **Duration** header. - -The table shows a list of related workflow items for the selected stage. Based on the stage you choose, this can be: - -- CI/CD jobs -- Issues -- Merge requests -- Pipelines - -A badge next to the workflow items table header shows the number of workflow items that completed the selected stage. - -## View time spent in each development stage - -Value stream analytics shows the median time spent by issues or merge requests in each development stage. - -To view the median time spent in each stage: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. -1. To view the median time for each stage, above the **Filter results** text box, point to a stage. - -## View the lead time and cycle time for issues - -Value stream analytics shows the lead time and cycle time for issues in your project: - -- Lead time: Median time from when the issue was created to when it was closed. -- Cycle time: Median time from first commit to issue closed. GitLab measures cycle time from the earliest commit of a [linked issue's merge request](../project/issues/crosslinking_issues.md) to when that issue is closed. The cycle time approach underestimates the lead time because merge request creation is always later than commit time. - -To view the lead time and cycle time for issues: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. - -The **Lead Time** and **Cycle Time** metrics display below the **Filter results** text box. - -## View lead time for changes for merge requests **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. - -Lead time for changes is the median duration between when a merge request is merged and when it's deployed to production. - -To view the lead time for changes for merge requests in your project: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. - -The **Lead Time for Changes** metrics display below the **Filter results** text box. - -## View number of successful deployments **(FREE)** - -Prerequisites: - -- To view deployment metrics, you must have a -[production environment configured](../../ci/environments/index.md#deployment-tier-of-environments). - -Value stream analytics shows the following deployment metrics for your project within the specified date range: - -- Deploys: The number of successful deployments in the date range. -- Deployment Frequency: The average number of successful deployments per day in the date range. - -If you have a GitLab Premium or Ultimate subscription: - -- The number of successful deployments is calculated with DORA data. -- The data is filtered based on environment and environment tier. - -To view deployment metrics for your project: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. - -The **Deploys** and **Deployment Frequency** metrics display below the **Filter results** text box. - -Deployment metrics are calculated based on data from the -[DORA API](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). - -NOTE: -In GitLab 13.9 and later, metrics are calculated based on when the deployment was finished. -In GitLab 13.8 and earlier, metrics are calculated based on when the deployment was created. - -## Access permissions for value stream analytics - -Access permissions for value stream analytics depend on the project type. - -| Project type | Permissions | -|--------------|----------------------------------------| -| Public | Anyone can access. | -| Internal | Any authenticated user can access. | -| Private | Any member Guest and above can access. | - -## How value stream analytics measures each stage - -Value stream analytics uses start and end events to measure the time that an issue or merge request -spends in each stage. - -For example, a stage might start when a user adds a label to an issue, and ends when they add another label. -Items aren't included in the stage time calculation if they have not reached the end event. - -| Stage | Measurement method | -|---------|----------------------| -| Issue | The median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone. The label is tracked only if it already includes an [issue board list](../project/issue_board.md) that has been created for the label. | -| Plan | The median time between the action you took for the previous stage, and when you push the first commit to the branch. The first branch commit triggers the transition from **Plan** to **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is not included in a commit, that data is not included in the measurement time of the stage. | -| Code | The median time between pushing a first commit (previous stage) and creating a merge request. The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, `xxx` is the issue number for the merge request. If there is no closing pattern, the start time is set to the create time of the first commit. | -| Test | The time from start to finish for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | -| Review | The median time taken to review merge requests with a closing issue pattern, from creation to merge. | -| Staging | The median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). Data is not collected without a production environment. | - -## Example workflow - -This example shows a workflow through all seven stages in one day. In this -example, milestones have been created and CI for testing and setting environments is configured. - -- 09:00: Create issue. **Issue** stage starts. -- 11:00: Add issue to a milestone, start work on the issue, and create a branch locally. -**Issue** stage stops and **Plan** stage starts. -- 12:00: Make the first commit. -- 12:30: Make the second commit to the branch that mentions the issue number. **Plan** stage stops and **Code** stage starts. -- 14:00: Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically). **Code** stage stops and **Test** and **Review** stages start. -- The CI takes 5 minutes to run scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/index.md). -**Test** stage stops. -- Review merge request. -- 19:00: Merge the merge request. **Review** stage stops and **Staging** stage starts. -- 19:30: Deployment to the `production` environment starts and finishes. **Staging** stops. - -Value stream analytics records the following times for each stage: - -- **Issue**: 09:00 to 11:00: 2 hrs -- **Plan**: 11:00 to 12:30: 1.5 hr -- **Code**: 12:30 to 14:00: 1.5 hrs -- **Test**: 5 minutes -- **Review**: 14:00 to 19:00: 5 hrs -- **Staging**: 19:00 to 19:30: 30 minutes - -Keep in mind the following observations related to this example: - -- Although this example specifies the issue number in a later commit, the process -still collects analytics data for the issue. -- The time required in the **Test** stage is included in the **Review** process, -as every merge request should be tested. -- This example illustrates only one cycle of multiple stages. The value -stream analytics dashboard shows the calculated median elapsed time for these issues. -- Value stream analytics identifies production environments based on the -[deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). - -## Troubleshooting - -### 100% CPU utilization by Sidekiq `cronjob:analytics_cycle_analytics` - -It is possible that Value stream analytics background jobs -strongly impact performance by monopolizing CPU resources. - -To recover from this situation: - -1. Disable the feature for all projects in [the Rails console](../../administration/operations/rails_console.md), - and remove existing jobs: - - ```ruby - Project.find_each do |p| - p.analytics_access_level='disabled'; - p.save! - end - - Analytics::CycleAnalytics::GroupStage.delete_all - Analytics::CycleAnalytics::Aggregation.delete_all - ``` - -1. Configure a [Sidekiq routing](../../administration/sidekiq/processing_specific_job_classes.md) - with for example a single `feature_category=value_stream_management` - and multiple `feature_category!=value_stream_management` entries. - Find other relevant queue metadata in the - [Enterprise Edition list](../../administration/sidekiq/processing_specific_job_classes.md#list-of-available-job-classes). -1. Enable value stream analytics for one project after another. - You might need to tweak the Sidekiq routing further according to your performance requirements. +<!-- This redirect file can be deleted after 2023-07-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/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index fd4cdd0d65f..a8c0ad0a7aa 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -4,13 +4,14 @@ 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 --- -# Value Streams Dashboard **(ULTIMATE)** +# Value Streams Dashboard (Beta) **(ULTIMATE)** -> Introduced in GitLab 15.8 as a Closed [Beta](../../policy/alpha-beta-support.md#beta-features) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Disabled by default. +> - Introduced in GitLab 15.8 as a Closed [Beta](../../policy/alpha-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Disabled by default. +> - Released in GitLab 15.11 as an Open [Beta](../../policy/alpha-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. -On GitLab.com, this feature is not available. This feature is not ready for production use. +On self-managed GitLab, this feature is available by default. To disable it, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. +On GitLab.com, this feature is available. This feature is not ready for production use. You can leave feedback on dashboard bugs or functionality in [issue 381787](https://gitlab.com/gitlab-org/gitlab/-/issues/381787). @@ -18,9 +19,6 @@ The Value Streams Dashboard is a customizable dashboard that enables decision-ma This page is a work in progress, and we're updating the information as we add more features. For more information, see the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). -After the feature flag is enabled, 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`). - ## Initial use case Our initial use case is focused on providing the ability to compare software delivery metrics. @@ -51,6 +49,22 @@ that are the largest value contributors, overperforming, or underperforming. You can also drill down the metrics for further analysis. When you hover over a metric, a tooltip displays an explanation of the metric and a link to the related documentation page. +## View the value streams dashboard + +Prerequisite: + +- To view the value streams dashboard for a group, you must have at least the Reporter role for the group. + +To view the value streams dashboard: + +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Below the **Filter results** text box, in the **Key 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`). + ## Customize the dashboard panels You can customize the Value Streams Dashboard and configure what subgroups and projects to include in the page. @@ -73,7 +87,7 @@ For example, the parameter `query=gitlab-org/gitlab-foss,gitlab-org/gitlab,gitla | Lead time for changes | The time to successfully deliver a commit into production. This metric reflects the efficiency of CI/CD pipelines. | [Lead time tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=lead-time) | [Lead time for changes](dora_metrics.md#lead-time-for-changes) | | Time to restore service | The time it takes an organization to recover from a failure in production. | [Time to restore service tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=time-to-restore-service) | [Time to restore service](dora_metrics.md#time-to-restore-service) | | Change failure rate | Percentage of deployments that cause an incident in production. | [Change failure rate tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=change-failure-rate) | [Change failure rate](dora_metrics.md#change-failure-rate) | -| VSA Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](value_stream_analytics.md#view-the-lead-time-and-cycle-time-for-issues) | -| VSA Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](value_stream_analytics.md#view-the-lead-time-and-cycle-time-for-issues) | +| Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | +| Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | | New issues | Number of new issues created. | [Issue Analytics](https://gitlab.com/groups/gitlab-org/-/issues_analytics) | Issue analytics [for projects](issue_analytics.md) and [for groups](../../user/group/issues_analytics/index.md) | | Number of deploys | Total number of deploys to production. | [Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Merge request analytics](merge_request_analytics.md) | 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 b77bed74c70..6a67dfc3f6a 100644 --- a/doc/user/application_security/api_security/api_discovery/index.md +++ b/doc/user/application_security/api_security/api_discovery/index.md @@ -82,7 +82,10 @@ When running in this method, you provide a container image that has the required image: openjdk:11-jre-slim ``` -1. Provide the Java classpath needed by your application. This includes your compatible build artifact from step 2, along with any additional dependencies. For this example, the build artifact is `build/libs/spring-boot-app-0.0.0.jar` and contains all needed dependencies. The variable `API_DISCOVERY_JAVA_CLASSPATH` is used to provide the classpath. +1. Provide the Java class path needed by your application. This includes your compatible build + artifact from step 2, along with any additional dependencies. For this example, the build artifact + is `build/libs/spring-boot-app-0.0.0.jar` and contains all needed dependencies. The variable + `API_DISCOVERY_JAVA_CLASSPATH` is used to provide the class path. ```yaml api_discovery: @@ -92,7 +95,10 @@ When running in this method, you provide a container image that has the required API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar ``` -1. [Optional] If the image provided is missing a dependency needed by API Discovery, it can be added using a `before_script`. In this example, the `openjdk:11-jre-slim` container doesn't include `curl` which is required by API Discovery. The dependency can be installed using the Debian package manager `apt` as shown below. +1. Optional. If the image provided is missing a dependency needed by API Discovery, it can be added + using a `before_script`. In this example, the `openjdk:11-jre-slim` container doesn't include + `curl` which is required by API Discovery. The dependency can be installed using the Debian + package manager `apt`: ```yaml api_discovery: @@ -104,7 +110,8 @@ When running in this method, you provide a container image that has the required - apt-get update && apt-get install -y curl ``` -1. [Optional] If the image provided doesn't automatically set the `JAVA_HOME` environment variable, or include `java` in the path, the `API_DISCOVERY_JAVA_HOME` variable can be used. +1. Optional. If the image provided doesn't automatically set the `JAVA_HOME` environment variable, + or include `java` in the path, the `API_DISCOVERY_JAVA_HOME` variable can be used. ```yaml api_discovery: @@ -115,7 +122,12 @@ When running in this method, you provide a container image that has the required API_DISCOVERY_JAVA_HOME: /opt/java ``` -1. [Optional] If the package registry at `API_DISCOVERY_PACKAGES` is not public, provide a token that has read access to the GitLab API and registry using the `API_DISCOVERY_PACKAGE_TOKEN` variable. This is not required if you are using `gitlab.com` and have not customized the `API_DISCOVERY_PACKAGES` variable. This example uses a [custom CI/CD variable](../../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) named `GITLAB_READ_TOKEN` to store the token. +1. Optional. If the package registry at `API_DISCOVERY_PACKAGES` is not public, provide a token that + has read access to the GitLab API and registry using the `API_DISCOVERY_PACKAGE_TOKEN` variable. + This is not required if you are using `gitlab.com` and have not customized the `API_DISCOVERY_PACKAGES` + variable. The following example uses a + [custom CI/CD variable](../../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) named + `GITLAB_READ_TOKEN` to store the token. ```yaml api_discovery: @@ -133,7 +145,7 @@ After the API Discovery job has successfully run, the OpenAPI document is availa - Linux container image. - Java versions 11 or 17 are officially supported, but other versions are likely compatible as well. - The `curl` command. -- A shell at `/bin/sh` (like busybox sh or bash). +- A shell at `/bin/sh` (like `busybox`, `sh`, or `bash`). ### Available CI/CD variables diff --git a/doc/user/application_security/breach_and_attack_simulation/index.md b/doc/user/application_security/breach_and_attack_simulation/index.md new file mode 100644 index 00000000000..0d662f7d469 --- /dev/null +++ b/doc/user/application_security/breach_and_attack_simulation/index.md @@ -0,0 +1,47 @@ +--- +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)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/402784) in GitLab 15.11. + +DISCLAIMER: +Breach and Attack Simulation is a set of experimental features being developed by the Incubation Engineering Department and is subject to significant changes over time. + +Breach and Attack Simulation (BAS) uses additional security testing techniques to assess the risk of detected vulnerabilities and prioritize the remediation of exploitable vulnerabilities. + +For feedback, bug reports, and feature requests, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/404809). + +WARNING: +Only run BAS scans against test servers. Testing attacker behavior can lead to modification or loss of data. + +## Extend Dynamic Application Security Testing (DAST) + +You can simulate attacks with [DAST](../dast/index.md) to detect vulnerabilities. +By default, DAST active checks match an expected response, or determine by response +time whether a vulnerability was exploited. + +Enable the BAS feature flag in DAST to: + +- Enable callback, match response, and timing attacks inside of active checks. +- Perform Out-of-Band Application Security Testing (OAST) through callback attacks in active checks. + +To enable BAS: + +1. Create a CI/CD job using the [DAST browser-based analyzer](../dast/browser_based.md#create-a-dast-cicd-job). +1. Set the `DAST_FF_ENABLE_BAS` [CI/CD variable](../dast/browser_based.md#available-cicd-variables) to `true`. + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_BROWSER_SCAN: "true" + DAST_FF_ENABLE_BAS: "true" + DAST_WEBSITE: "https://my.site.com" +``` diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 380624c91ce..d5a05477ddf 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -51,7 +51,7 @@ You can configure the following security controls: - [Static Application Security Testing](../sast/index.md) (SAST) - Select **Enable SAST** to configure SAST for the current project. - For more details, read [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). + For more details, read [Configure SAST in the UI](../sast/index.md#configure-sast-by-using-the-ui). - [Dynamic Application Security Testing](../dast/index.md) (DAST) - Select **Enable DAST** to configure DAST for the current project. - Select **Manage scans** to manage the saved DAST scans, site profiles, and scanner profiles. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index a38f7bcb77c..793c9a89ec0 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -22,6 +22,9 @@ vulnerabilities. By including an extra Container Scanning job in your pipeline t vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based apps. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Container Scanning](https://www.youtube.com/watch?v=C0jn2eN5MAs). + Container Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain aspects of inspecting the items your code uses. These items typically include application and system dependencies that are almost always imported from external sources, rather than sourced from items @@ -696,6 +699,14 @@ These reports must follow a format defined in the For more information, see [Security scanner integration](../../../development/integrations/secure.md). +### CycloneDX Software Bill of Materials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396381) in GitLab 15.11. + +In addition to the [JSON report file](#reports-json-format), the [Container Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) tool outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) for the scanned image. This CycloneDX SBOM is named `gl-sbom-report.cdx.json` and is saved in the same directory as the `JSON report file`. This feature is only supported when the `Trivy` analyzer is used. + +You can download CycloneDX SBOMs [the same way as other job artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts). + ## Security Dashboard The [Security Dashboard](../security_dashboard/index.md) shows you an overview of all @@ -774,7 +785,7 @@ To prevent the error, ensure the Docker version that the runner is using is ### Getting warning message `gl-container-scanning-report.json: no matching files` -For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). ## Changes diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 4731e09474c..09370a9a7f5 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -15,6 +15,9 @@ We recommend that you use fuzz testing in addition to the other security scanner and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run your coverage-guided fuzz testing as part your CI/CD workflow. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Coverage Fuzzing](https://www.youtube.com/watch?v=bbIenVVcjW0). + ## Coverage-guided fuzz testing process The fuzz testing process: @@ -145,7 +148,7 @@ Each fuzzing step outputs these artifacts: previous jobs. You can download the JSON report file from the CI/CD pipelines page. For more information, see -[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +[Downloading artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts). ## Corpus registry @@ -222,7 +225,7 @@ Prerequisites: ## Coverage-guided fuzz testing report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Alpha feature](../../../policy/alpha-beta-support.md#alpha-features). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Experiment](../../../policy/alpha-beta-support.md#experiment). For detailed information about the `gl-coverage-fuzzing-report.json` file's format, read the [schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index 03a273ffff9..27f56e5224c 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -47,7 +47,7 @@ To run a DAST authenticated scan: - You have the username and password of the user you would like to authenticate as during the scan. - You have checked the [known limitations](#known-limitations) to ensure DAST can authenticate to your application. -- You have satisfied the prerequisites depending on whether you're using [form authentication](#form-authentication) or [HTTP authentication]((#http-authentication). +- You have satisfied the prerequisites depending on whether you're using [form authentication](#form-authentication) or [HTTP authentication](#http-authentication). - You have thought about how you can [verify](#verifying-authentication-is-successful) whether or not authentication was successful. #### Form authentication @@ -80,6 +80,7 @@ To run a DAST authenticated scan: | `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when selected submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9894) in GitLab 12.4. | | `DAST_USERNAME` <sup>1</sup> | string | The username to authenticate to in the website. Example: `admin` | | `DAST_USERNAME_FIELD` <sup>1</sup> | string | The selector of username field at the sign-in HTML 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. | 1. Available to an on-demand proxy-based DAST scan. 1. Not available to proxy-based scans. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 88be88ad00e..7b263e5817d 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -173,7 +173,9 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. Headers set using `DAST_REQUEST_HEADERS` are added to every request made to these hostnames. | | `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | | `DAST_BROWSER_CRAWL_GRAPH` | boolean | `true` | Set to `true` to generate an SVG graph of navigation paths visited during crawl phase of the scan. You must also define `gl-dast-crawl-graph.svg` as a CI job artifact to be able to access the generated graph. | -| `DAST_BROWSER_DEVTOOLS_LOG` | string | `Default:messageAndBody,truncate:2000` | Set to log protocol messages between DAST and the Chromium browser. | | +| `DAST_BROWSER_CRAWL_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `5m` | The maximum amount of time to wait for the crawl phase of the scan to complete. Defaults to `24h`. | +| `DAST_BROWSER_DEVTOOLS_LOG` | string | `Default:messageAndBody,truncate:2000` | Set to log protocol messages between DAST and the Chromium browser. | +| `DAST_BROWSER_DOM_READY_AFTER_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `200ms` | Define how long to wait for updates to the DOM before checking a page is stable. Defaults to `500ms`. | | `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis. | | `DAST_BROWSER_EXCLUDED_ELEMENTS` | selector | `a[href='2.html'],css:.no-follow` | Comma-separated list of selectors that are ignored when scanning. | | `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | @@ -192,11 +194,13 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com, we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but are likely to produce little benefit after five to seven instances. | | `DAST_BROWSER_PAGE_LOADING_SELECTOR` | selector | `css:#page-is-loading` | Selector that when is no longer visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Cannot be used with `DAST_BROWSER_PAGE_READY_SELECTOR`. | | `DAST_BROWSER_PAGE_READY_SELECTOR` | selector | `css:#page-is-ready` | Selector that when detected as visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Cannot be used with `DAST_BROWSER_PAGE_LOADING_SELECTOR`. | +| `DAST_BROWSER_PASSIVE_CHECK_WORKERS` | int | `5` | Number of workers that passive scan in parallel. Recommend setting to the number of available CPUs. | | `DAST_BROWSER_SCAN` | boolean | `true` | Required to be `true` to run a browser-based scan. | | `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or user actions. | | `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. | | `DAST_EXCLUDE_RULES` | string | `10020,10026` | Set to a comma-separated list of ZAP Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). | | `DAST_EXCLUDE_URLS` | URLs | `https://example.com/.*/sign-out` | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. | +| `DAST_FF_ENABLE_BAS` | boolean | `true` | Set to `true` to [enable Breach and Attack Simulation](../breach_and_attack_simulation/index.md#extend-dynamic-application-security-testing-dast) during this DAST scan. | | `DAST_FULL_SCAN_ENABLED` | boolean | `true` | Set to `true` to run both passive and active checks. Default: `false` | | `DAST_PATHS` | string | `/page1.html,/category1/page3.html` | Set to a comma-separated list of URL paths relative to `DAST_WEBSITE` for DAST to scan. | | `DAST_PATHS_FILE` | string | `/builds/project/urls.txt` | Set to a file path containing a list of URL paths relative to `DAST_WEBSITE` for DAST to scan. The file must be plain text with one path per line. | @@ -232,9 +236,14 @@ This can come at a cost of increased scan time. You can manage the trade-off between coverage and scan time with the following measures: +- Vertically scale the runner and use a higher number of browsers with the [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. - Limit the number of actions executed by the browser with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. - Limit the page depth that the browser-based crawler checks coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. -- Vertically scale the runner and use a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. +- Limit the time taken to crawl the target application with the [variable](#available-cicd-variables) `DAST_BROWSER_CRAWL_TIMEOUT`. The default is `24h`. Scans continue with passive and active checks when the crawler times out. +- Build the crawl graph with the [variable](#available-cicd-variables) `DAST_BROWSER_CRAWL_GRAPH` to see what pages are being crawled. +- Prevent pages from being crawled using the [variable](#available-cicd-variables) `DAST_EXCLUDE_URLS`. +- Prevent elements being selected using the [variable](#available-cicd-variables) `DAST_BROWSER_EXCLUDED_ELEMENTS`. Use with caution, as defining this variable causes an extra lookup for each page crawled. +- If the target application has minimal or fast rendering, consider reducing the [variable](#available-cicd-variables) `DAST_BROWSER_DOM_READY_AFTER_TIMEOUT` to a smaller value. The default is `500ms`. ## Timeouts diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index da382920604..c2e7f153e02 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -70,7 +70,7 @@ tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/20 ## Getting warning message `gl-dast-report.json: no matching files` -For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). ## Getting error `dast job: chosen stage does not exist` when including DAST CI template diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 3cb8967afd2..1f4506a22e5 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -15,6 +15,9 @@ visible from the source code. Dynamic Application Security Testing (DAST) examines applications for vulnerabilities like these in deployed environments. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Dynamic Application Security Testing (DAST)](https://www.youtube.com/watch?v=nbeDUoLZJTo). + NOTE: To learn how four of the top six attacks were application-based and how to protect your organization, download our diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 49d5859be45..1ebb5c8af0d 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -998,6 +998,14 @@ repository's root as `.gitlab/gitlab-dast-api-config.yml`. The following profiles are pre-defined in the default configuration file. Profiles can be added, removed, and modified by creating a custom configuration. +#### Passive + +- Application Information Check +- Cleartext Authentication Check +- JSON Hijacking Check +- Sensitive Information Check +- Session Cookie Check + #### Quick - Application Information Check diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index f46c5e5e801..e02cc5929a6 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -13,6 +13,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the dependency list to review your project's dependencies and key details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Project Dependency](https://www.youtube.com/watch?v=ckqkn9Tnbw4). + To see the dependency list, go to your project and select **Security and Compliance > Dependency list**. This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 7641c39d6d6..86e6264fab4 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -35,6 +35,9 @@ vulnerability.  +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Dependency Scanning](https://www.youtube.com/watch?v=TBnfbGk4c4o). + ## Dependency Scanning compared to Container Scanning GitLab offers both Dependency Scanning and Container Scanning @@ -212,8 +215,8 @@ table.supported-languages ul { <td>N</td> </tr> <tr> - <td rowspan="2">JavaScript and TypeScript</td> - <td>All versions</td> + <td rowspan="3">JavaScript and TypeScript</td> + <td rowspan="3">All versions</td> <td><a href="https://www.npmjs.com/">npm</a></td> <td> <ul> @@ -224,12 +227,16 @@ table.supported-languages ul { <td>Y</td> </tr> <tr> - <td>All versions</td> <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> <td><code>yarn.lock</code></td> <td>Y</td> </tr> <tr> + <td><a href="https://pnpm.io/">pnpm</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> + <td><code>pnpm-lock.yaml</code></td> + <td>Y</td> + </tr> + <tr> <td>PHP</td> <td>All versions</td> <td><a href="https://getcomposer.org/">Composer</a></td> @@ -258,14 +265,14 @@ table.supported-languages ul { <td><a href="https://pipenv.pypa.io/en/latest/">Pipenv</a></td> <td> <ul> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></li> + <li><a href="https://pipenv.pypa.io/en/latest/pipfile/#example-pipfile"><code>Pipfile</code></a></li> + <li><a href="https://pipenv.pypa.io/en/latest/pipfile/#example-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></li> </ul> </td> <td>N</td> </tr> <tr> - <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></td> + <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> <td><code>poetry.lock</code></td> <td>N</td> </tr> @@ -284,7 +291,7 @@ table.supported-languages ul { <tr> <td>Scala</td> <td>All versions</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-7">7</a></b></sup></td> <td><code>build.sbt</code></td> <td>N</td> </tr> @@ -313,6 +320,12 @@ table.supported-languages ul { <li> <a id="notes-regarding-supported-languages-and-package-managers-4"></a> <p> + Support for <code>pnpm</code> lockfiles was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336809">introduced in GitLab 15.11</a>. <code>pnpm</code> lockfiles do not store bundled dependencies, so the reported dependencies may differ from <code>npm</code> or <code>yarn</code>. + </p> + </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-5"></a> + <p> The presence of a <code>Pipfile.lock</code> file alone will <i>not</i> trigger the analyzer; the presence of a <code>Pipfile</code> is still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it is used by <code>Gemnasium</code> to scan the exact package versions listed in this file. @@ -324,7 +337,7 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-5"></a> + <a id="notes-regarding-supported-languages-and-package-managers-6"></a> <p> Support for <a href="https://python-poetry.org/">Poetry</a> projects with a <code>poetry.lock</code> file was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/7006">added in GitLab 15.0</a>. Support for projects without a <code>poetry.lock</code> file is tracked in issue: @@ -332,7 +345,7 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-6"></a> + <a id="notes-regarding-supported-languages-and-package-managers-7"></a> <p> Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. </p> @@ -359,7 +372,8 @@ The following package managers use lockfiles that GitLab analyzers are capable o | 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 | [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-2">2</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) | -| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | +| pnpm | v5.3, v5.4, 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-3">3</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</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 --> @@ -377,6 +391,26 @@ The following package managers use lockfiles that GitLab analyzers are capable o Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. </p> </li> + <li> + <a id="notes-regarding-parsing-lockfiles-3"></a> + <p> + Support for Yarn <code>v2</code> and <code>v3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/263358">introduced in GitLab 15.11</a>. However, this feature is also available to versions of GitLab 15.0 and later. + </p> + <p> + The following features are not supported for Yarn <code>v2</code> or <code>v3</code>: + </p> + <ul> + <li> + <a href="https://yarnpkg.com/features/workspaces">workspaces</a> + </li> + <li> + <a href="https://yarnpkg.com/cli/patch">yarn patch</a> + </li> + </ul> + <p> + Yarn files that contain a patch, a workspace, or both, are still processed, but these features are ignored. + </p> + </li> </ol> <!-- markdownlint-enable MD044 --> @@ -402,7 +436,7 @@ To support the following package managers, the GitLab analyzers proceed in two s <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/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3">`.tool-versions`</a> file. </p> </li> <li> @@ -872,7 +906,7 @@ Here's an example dependency scanning report: ### CycloneDX Software Bill of Materials -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/alpha-beta-support.md#beta-features). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/alpha-beta-support.md#beta). > - Generally available in GitLab 15.7. In addition to the [JSON report file](#reports-json-format), the [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) @@ -913,7 +947,7 @@ Then the Gemnasium scanner generates the following CycloneDX SBOMs: └── gl-sbom-go-go.cdx.json ``` -The CycloneDX SBOMs can be downloaded [the same way as other job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +You can download CycloneDX SBOMs [the same way as other job artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts). ### Merging multiple CycloneDX SBOMs @@ -1213,7 +1247,7 @@ affected. Read more in ### Getting warning message `gl-dependency-scanning-report.json: no matching files` -For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +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 diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 937aaf76280..f74a1a1f0da 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -261,7 +261,7 @@ The IaC tool emits a JSON report file in the existing SAST report format. For mo [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). The JSON report file can be downloaded from the CI pipelines page, or the -pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). +pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/jobs/job_artifacts.md). ## Troubleshooting diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 492b200d22b..32a4b0f4318 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -101,7 +101,7 @@ The following vulnerability scanners and their databases are regularly updated: | Secure scanning tool | Vulnerabilities database updates | |:----------------------------------------------------------------|:---------------------------------| -| [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. For more details, see [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database). | +| [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. GitLab monitors this job through an internal alert that tells the engineering team when the database becomes more than 48 hours old. For more information, see the [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database). | | [Dependency Scanning](dependency_scanning/index.md) | Relies on the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). It is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | The source of scan rules depends on which [analyzer](sast/analyzers.md) is used for each [supported programming language](sast/index.md#supported-languages-and-frameworks). GitLab maintains a ruleset for the Semgrep-based analyzer and updates it regularly based on internal research and user feedback. For other analyzers, the ruleset is sourced from the upstream open-source scanner. Each analyzer is updated at least once per month if a relevant update is available. | @@ -577,7 +577,7 @@ Debug logging can be a serious security risk. The output may contain the content environment variables and other secrets available to the job. The output is uploaded to the GitLab server and visible in job logs. -This message is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), +This message is often followed by the [error `No files to upload`](../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload), and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Check the entire job log for such messages. If you don't find these messages, retry the failed job after setting `SECURE_LOG_LEVEL: "debug"` as a [custom CI/CD variable](../../ci/variables/index.md#for-a-project). diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 5a075bf731b..1ee4d9b2a19 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -121,7 +121,7 @@ include: ``` The pipeline downloads the Docker images needed for the Security Scanners and saves them as -[job artifacts](../../../ci/pipelines/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/scan_execution_policy_rule_mode_v15_11.png b/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_11.png Binary files differnew file mode 100644 index 00000000000..76b9a971172 --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_11.png diff --git a/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_9.png b/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_9.png Binary files differdeleted file mode 100644 index 57e729158da..00000000000 --- a/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_9.png +++ /dev/null diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 1f53b671ed1..05996a70d3d 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -24,8 +24,12 @@ GitLab supports the following security policies: 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. Linked projects are not required to be in -the same group as the development projects to which they are linked. +policy project to apply to multiple development projects, groups, or sub-groups: + +- 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.  @@ -34,10 +38,6 @@ project and the security policy project, this is not recommended. Keeping the se project separate from the development project allows for complete separation of duties between security/compliance teams and development teams. -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. - 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: diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index 96048bb2308..55a4994e168 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -44,7 +44,7 @@ Most policy changes take effect as soon as the merge request is merged. Any chan 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. - + ## Scan execution policies schema diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 104462529c1..f54b77bd45d 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -87,11 +87,8 @@ This rule enforces the defined actions based on security scan findings. ## `license_finding` rule type -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`. Enabled by default in GitLab 15.10. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `license_scanning_policies`. -On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed. This rule enforces the defined actions based on license findings. @@ -116,6 +113,7 @@ the defined policy. | `user_approvers_ids` | `array` of `integer` | ID of one of more users | The IDs of users to consider as approvers. Users must have access to the project to be eligible to approve. | | `group_approvers` | `array` of `string` | Path of one of more groups | The groups to consider as approvers. Users with [direct membership in the group](../../project/merge_requests/approvals/rules.md#group-approvers) are eligible to approve. | | `group_approvers_ids` | `array` of `integer` | ID of one of more groups | The IDs of groups to consider as approvers. Users with [direct membership in the group](../../project/merge_requests/approvals/rules.md#group-approvers) are eligible to approve. | +| `role_approvers` | `array` of `string` | One or more [roles](../../../user/permissions.md#roles) (for example: `owner`, `maintainer`) | The roles to consider as approvers. | Requirements and limitations: @@ -171,6 +169,8 @@ scan_result_policy: approvals_required: 1 user_approvers: - sam.white + role_approvers: + - owner ``` In this example: diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index d070883df9a..b45b25db69f 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -323,7 +323,7 @@ With the following custom ruleset configuration, vulnerabilities found with [semgrep] [[semgrep.ruleset]] [semgrep.ruleset.identifier] - type = "CWE" + type = "cwe" value = "322" [semgrep.ruleset.override] severity = "Critical" diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index a0c5adc89f5..13f05a63181 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -79,20 +79,20 @@ For more information about our plans for language support in SAST, see the [cate |------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| | .NET Core | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 11.0 | | .NET Framework<sup>1</sup> | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 13.0 | -| .NET (all versions, C# only) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 15.4 | +| .NET (all versions, C# only) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 15.4 | | Apex (Salesforce) | [PMD](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | 12.1 | -| C | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 14.2 | +| C | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.2 | | C/C++ | [Flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | 11.1 | | Go<sup>3</sup> | [Gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | 10.7 | -| Go | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 14.4 | +| Go | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.4 | | Groovy<sup>2</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.3 (Gradle) & 11.9 (Maven, SBT) | | Helm Charts | [Kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | 13.1 | -| Java (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 14.10 | +| Java (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.10 | | Java<sup>2, 3</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (SBT) | | Java (Android) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | JavaScript<sup>3</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.8 | -| JavaScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 13.10 | +| JavaScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | | Kotlin (Android) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | Kotlin (General)<sup>2</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 13.11 | | Kubernetes manifests | [Kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | 12.6 | @@ -100,15 +100,15 @@ For more information about our plans for language support in SAST, see the [cate | Objective-C (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | PHP | [phpcs-security-audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | 10.8 | | Python<sup>3</sup> | [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | 10.3 | -| Python | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 13.9 | +| Python | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.9 | | React<sup>3</sup> | [ESLint react plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 12.5 | -| React | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 13.10 | +| React | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | | Ruby | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 13.9 | | Ruby on Rails | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 10.3 | | Scala<sup>2</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.0 (SBT) & 11.9 (Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | TypeScript<sup>3</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | -| TypeScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 13.10 | +| TypeScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | 1. .NET 4 support is limited. The analyzer runs in a Linux container and does not have access to Windows-specific libraries or features. Use the Semgrep-based scanner if you need .NET 4 support. 1. The SpotBugs-based analyzer supports [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/). It can also be used with variants like the @@ -238,7 +238,7 @@ as shown in the following table: | See new findings in merge request widget | **{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 in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST by using the UI](#configure-sast-by-using-the-ui) | **{dotted-circle}** | **{check-circle}** | | [Customize SAST rulesets](customize_rulesets.md) | **{dotted-circle}** | **{check-circle}** | | [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | | [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** | @@ -257,7 +257,7 @@ To configure SAST for a project you can: - Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast), provided by [Auto DevOps](../../../topics/autodevops/index.md). - [Configure SAST in your CI/CD YAML](#configure-sast-in-your-cicd-yaml). -- [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). +- [Configure SAST by using the UI](#configure-sast-by-using-the-ui). You can enable SAST across many projects by [enforcing scan execution](../index.md#enforce-scan-execution). @@ -282,15 +282,12 @@ The results are saved as a that you can later download and analyze. When downloading, you always receive the most recent SAST artifact available. -### Configure SAST in the UI +### Configure SAST by using the UI -You can enable and configure SAST in the UI, either with default settings, or with customizations. +You can enable and configure SAST by using the UI, either with the default settings or with customizations. The method you can use depends on your GitLab license tier. -- [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations). **(ULTIMATE)** -- [Configure SAST in the UI with default settings only](#configure-sast-in-the-ui-with-default-settings-only). - -### Configure SAST in the UI with customizations **(ULTIMATE)** +#### Configure SAST with customizations **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab 13.3. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab 13.4. @@ -319,7 +316,7 @@ To enable and configure SAST with customizations: Pipelines now include a SAST job. -### Configure SAST in the UI with default settings only +#### Configure SAST with default settings only > [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 @@ -665,7 +662,7 @@ To download the report file, you can either: - Download the file from the CI/CD pipelines page. - In the pipelines tab on merge requests, set [`artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. -For information, see [Download job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +For information, see [Download job artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts). For details of the report file's schema, see [SAST report file schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). @@ -820,7 +817,7 @@ affected. Read more in ### Getting warning message `gl-sast-report.json: no matching files` -For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). ### Error: `sast is used for configuration only, and its script should not be executed` diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 6dd20ea094e..49bab0b3b29 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -59,6 +59,7 @@ Different features are available in different [GitLab tiers](https://about.gitla | [Configure Secret Detection scanner](#enable-secret-detection) | **{check-circle}** Yes | **{check-circle}** Yes | | [Customize Secret Detection settings](#configure-scan-settings) | **{check-circle}** Yes | **{check-circle}** Yes | | Download [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** Yes | **{check-circle}** Yes | +| [Check text for potential secrets](#warnings-for-potential-leaks-in-text-content) before it's posted | **{check-circle}** Yes | **{check-circle}** Yes | | See new findings in the merge request widget | **{dotted-circle}** No | **{check-circle}** Yes | | View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** No | **{check-circle}** Yes | | [Manage vulnerabilities](../vulnerability_report/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | @@ -535,6 +536,26 @@ variable, or as a CI/CD variable. - If using a variable, set the value of `ADDITIONAL_CA_CERT_BUNDLE` to the text representation of the certificate. +## Warnings for potential leaks in text content + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368434) in GitLab 15.11. + +When you create an issue, propose a merge request, or write a comment, you might accidentally post a sensitive value. +For example, you might paste in the details of an API request or an environment variable that contains an authentication token. + +GitLab checks if the text of your issue description, merge request description, comment, or reply contains a sensitive token. +If a token is found, a warning message is displayed. You can then edit your message before posting it. +This check happens in your browser before the message is sent to the server. +The check is always on; you don't have to set it up. + +Your text is checked for the following secret types: + +- GitLab [personal access tokens](../../../security/token_overview.md#personal-access-tokens) +- GitLab [feed tokens](../../../security/token_overview.md#feed-token) + +This feature is separate from Secret Detection scanning, which checks your Git repository for leaked secrets. +[Issue 405147](https://gitlab.com/gitlab-org/gitlab/-/issues/405147) tracks efforts to align these two types of protection. + ## Troubleshooting ### Set the logging level @@ -555,7 +576,7 @@ visible in job logs. ### Warning: `gl-secret-detection-report.json: no matching files` -For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). ### Error: `Couldn't run the gitleaks command: exit status 2` diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index 22d7a8ba5af..b05b272b0b4 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -4,7 +4,7 @@ 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 --- -# Secret Detection post-processing and revocation **(ULTIMATE SAAS)** +# Secret Detection post-processing and revocation **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. > - [Disabled by default for GitLab personal access tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `gitlab_pat_auto_revocation`. Available to GitLab.com only. @@ -32,53 +32,25 @@ GitLab supports post-processing for the following vendors and secrets: ## Feature availability +> [Enabled for non-default branches](https://gitlab.com/gitlab-org/gitlab/-/issues/299212) in GitLab 15.11. + Credentials are only post-processed when Secret Detection finds them: - In public projects, because publicly exposed credentials pose an increased threat. Expansion to private projects is considered in [issue 391379](https://gitlab.com/gitlab-org/gitlab/-/issues/391379). -- On the project [default branch](../../project/repository/branches/default.md), for technical reasons. Expansion to all branches is tracked in [issue 299212](https://gitlab.com/gitlab-org/gitlab/-/issues/299212). - In projects with GitLab Ultimate, for technical reasons. Expansion to all tiers is tracked in [issue 391763](https://gitlab.com/gitlab-org/gitlab/-/issues/391763). -## High-level architecture - -This diagram describes how a post-processing hook revokes a secret within the GitLab application: - -```mermaid -sequenceDiagram - autonumber - GitLab Rails->>+Sidekiq: gl-secret-detection-report.json - Sidekiq-->+Sidekiq: StoreSecurityReportsWorker - Sidekiq-->+Token Revocation API: GET revocable keys types - Token Revocation API-->>-Sidekiq: OK - Sidekiq->>+Token Revocation API: POST revoke revocable keys - Token Revocation API-->>-Sidekiq: ACCEPTED - Token Revocation API-->>+Receiver Service: revoke revocable keys - Receiver Service-->>+Token Revocation API: ACCEPTED -``` - -1. A pipeline with a Secret Detection job completes on the project's default branch, producing a scan - report (**1**). -1. The report is processed (**2**) by an asynchronous worker, which communicates with an externally - deployed HTTP service (**3** and **4**) to determine which kinds of secrets can be automatically - revoked. -1. The worker sends (**5** and **6**) the list of detected secrets which the Token Revocation API is able to - revoke. -1. The Token Revocation API sends (**7** and **8**) each revocable token to their respective vendor's [receiver service](#integrate-your-cloud-provider-service-with-gitlabcom). - -See the [Token Revocation API](../../../development/sec/token_revocation_api.md) documentation for more -information. - -## Integrate your cloud provider service with GitLab.com +## Partner program for leaked-credential notifications -Third-party cloud and SaaS vendors interested in automated token revocation can -[express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). -Vendors must [implement a revocation receiver service](#implement-a-revocation-receiver-service) -which will be called by the Token Revocation API. +GitLab notifies partners when credentials they issue are leaked in public repositories on GitLab.com. +If you operate a cloud or SaaS product and you're interested in receiving these notifications, learn more in [epic 4944](https://gitlab.com/groups/gitlab-org/-/epics/4944). +Partners must [implement a revocation receiver service](#implement-a-revocation-receiver-service), +which is called by the Token Revocation API. ### Implement a revocation receiver service A revocation receiver service integrates with a GitLab instance's Token Revocation API to receive and respond to leaked token revocation requests. The service should be a publicly accessible HTTP API that is -idempotent and rate-limited. Requests to your service from the Token Revocation API will follow the example +idempotent and rate-limited. Requests to your service from the Token Revocation API look similar to the example below: ```plaintext @@ -95,3 +67,32 @@ X-Gitlab-Token: MYSECRETTOKEN In this example, Secret Detection has determined that an instance of `my_api_token` has been leaked. The value of the token is provided to you, in addition to a publicly accessible URL to the raw content of the file containing the leaked token. + +## High-level architecture + +This diagram describes how a post-processing hook revokes a secret in the GitLab application: + +```mermaid +sequenceDiagram + autonumber + GitLab Rails-->+GitLab Rails: gl-secret-detection-report.json + GitLab Rails->>+Sidekiq: StoreScansService + Sidekiq-->+Sidekiq: ScanSecurityReportSecretsWorker + Sidekiq-->+Token Revocation API: GET revocable keys types + Token Revocation API-->>-Sidekiq: OK + Sidekiq->>+Token Revocation API: POST revoke revocable keys + Token Revocation API-->>-Sidekiq: ACCEPTED + Token Revocation API-->>+Receiver Service: revoke revocable keys + Receiver Service-->>+Token Revocation API: ACCEPTED +``` + +1. A pipeline with a Secret Detection job completes, producing a scan report (**1**). +1. The report is processed (**2**) by a service class, which schedules an asynchronous worker if token revocation is possible. +1. The asynchronous worker (**3**) communicates with an externally deployed HTTP service + (**4** and **5**) to determine which kinds of secrets can be automatically revoked. +1. The worker sends (**6** and **7**) the list of detected secrets which the Token Revocation API is able to + revoke. +1. The Token Revocation API sends (**8** and **9**) each revocable token to their respective vendor's [receiver service](#implement-a-revocation-receiver-service). + +See the [Token Revocation API](../../../development/sec/token_revocation_api.md) documentation for more +information. diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 772a7d17e1e..df103976901 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Secure and Govern terminology **(FREE)** +# Secure and Govern glossary **(FREE)** The glossary of terms aims to achieve the following: @@ -17,9 +17,7 @@ The glossary of terms aims to achieve the following: The definitions of the terms outlined in this document are in the context of the GitLab products. Therefore, a term may have a different meaning to users outside of GitLab. -## Terms - -### Analyzer +## Analyzer Software that performs a scan. The scan analyzes an attack surface for vulnerabilities and produces a report containing findings. Reports adhere to the [Secure report format](#secure-report-format). @@ -31,35 +29,35 @@ manage found vulnerabilities. For more information, see [Security Scanner Integr Many GitLab analyzers follow a standard approach using Docker to run a wrapped scanner. For example, the image `semgrep` is an analyzer that wraps the scanner `Semgrep`. -### Attack surface +## Attack surface The different places in an application that are vulnerable to attack. Secure products discover and search the attack surface during scans. Each product defines the attack surface differently. For example, SAST uses files and line numbers, and DAST uses URLs. -### Corpus +## Corpus The set of meaningful test cases that are generated while the fuzzer is running. Each meaningful test case produces new coverage in the tested program. It's advised to re-use the corpus and pass it to subsequent runs. -### CNA +## CNA [CVE](#cve) Numbering Authorities (CNAs) are organizations from around the world that are authorized by the [Mitre Corporation](https://cve.mitre.org/) to assign [CVE](#cve)s to vulnerabilities in products or services within their respective scope. [GitLab is a CNA](https://about.gitlab.com/security/cve/). -### CVE +## CVE Common Vulnerabilities and Exposures (CVE®) is a list of common identifiers for publicly known cybersecurity vulnerabilities. The list is managed by the [Mitre Corporation](https://cve.mitre.org/). -### CVSS +## CVSS The Common Vulnerability Scoring System (CVSS) is a free and open industry standard for assessing the severity of computer system security vulnerabilities. -### CWE +## CWE Common Weakness Enumeration (CWE™) is a community-developed list of common software and hardware weakness types that have security ramifications. Weaknesses are flaws, faults, bugs, @@ -68,22 +66,22 @@ architecture. If left unaddressed, weaknesses could result in systems, networks, vulnerable to attack. The CWE List and associated classification taxonomy serve as a language that you can use to identify and describe these weaknesses in terms of CWEs. -### Deduplication +## Deduplication When a category's process deems findings to be the same, or if they are similar enough that a noise reduction is required, only one finding is kept and the others are eliminated. Read more about the [deduplication process](../vulnerability_report/pipeline.md#deduplication-process). -### Duplicate finding +## Duplicate finding A legitimate finding that is reported multiple times. This can occur when different scanners discover the same finding, or when a single scan inadvertently reports the same finding more than once. -### False positive +## False positive A finding that doesn't exist but is incorrectly reported as existing. -### Finding +## Finding An asset that has the potential to be vulnerable, identified in a project by an analyzer. Assets include but are not restricted to source code, binary packages, containers, dependencies, networks, @@ -96,32 +94,32 @@ You can interact with vulnerability findings in two ways. 1. You can open an issue or merge request for the vulnerability finding. 1. You can dismiss the vulnerability finding. Dismissing the finding hides it from the default views. -### Grouping +## Grouping A flexible and non-destructive way to visually organize vulnerabilities in groups when there are multiple findings that are likely related but do not qualify for deduplication. For example, you can include findings that should be evaluated together, would be fixed by the same action, or come from the same source. Grouping behavior for vulnerabilities is under development and tracked in issue [267588](https://gitlab.com/gitlab-org/gitlab/-/issues/267588). -### Insignificant finding +## Insignificant finding A legitimate finding that a particular customer doesn't care about. -### Location fingerprint +## Location fingerprint A finding's location fingerprint is a text value that's unique for each location on the attack surface. Each security product defines this according to its type of attack surface. For example, SAST incorporates file path and line number. -### Package managers and package types +## Package managers and package types -#### Package managers +### Package managers A package manager is a system that manages your project dependencies. The package manager provides a method to install new dependencies (also referred to as "packages"), manage where packages are stored on your file system, and offer capabilities for you to publish your own packages. -#### Package types +### Package types Each package manager, platform, type, or ecosystem has its own conventions and protocols to identify, locate, and provision software packages. @@ -215,11 +213,11 @@ table.package-managers-and-types ul { </tbody> </table> -### Pipeline Security tab +## Pipeline Security tab A page that displays findings discovered in the associated CI pipeline. -### Post-filter +## Post-filter Post-filters help reduce noise in the scanner results and automate manual tasks. You can specify criteria that updates or modifies vulnerability data based on scanner results. For example, you can flag findings as likely False Positives @@ -228,7 +226,7 @@ and automatically resolve vulnerabilities that are no longer detected. These are Support for automatically resolving findings is tracked in epic [7478](https://gitlab.com/groups/gitlab-org/-/epics/7478) and support for cheap scan is proposed in issue [349926](https://gitlab.com/gitlab-org/gitlab/-/issues/349926). -### Pre-filter +## Pre-filter An irreversible action that is done to filter out targets before analysis occurs. This is usually provided to allow the user to reduce scope and noise as well as speed up the analysis. This should not be done if a record is needed as @@ -236,7 +234,7 @@ we currently do not store anything related to the skipped/excluded code or asset Examples: `DS_EXCLUDED_PATHS` should `Exclude files and directories from the scan based on the paths provided.` -### Primary identifier +## Primary identifier A finding's primary identifier is a value that is unique to each finding. The external type and external ID of the finding's [first identifier](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/v2.4.0-rc1/dist/sast-report-format.json#L228) @@ -246,13 +244,13 @@ Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (Z Trivy. The identifier must be stable. Subsequent scans must return the same value for the same finding, even if the location has slightly changed. -### Report finding +## Report finding A [finding](#finding) that only exists in a report produced by an analyzer, and is yet to be persisted to the database. The report finding becomes a [vulnerability finding](#vulnerability-finding) once it's imported into the database. -### Scan type (report type) +## Scan type (report type) Describes the type of scan. This must be one of the following: @@ -266,12 +264,12 @@ Describes the type of scan. This must be one of the following: This list is subject to change as scanners are added. -### Scanner +## Scanner Software that can scan for vulnerabilities. The resulting scan report is typically not in the [Secure report format](#secure-report-format). Examples include ESLint, Trivy, and ZAP. -### Secure product +## Secure product A group of features related to a specific area of application security with first-class support by GitLab. @@ -281,23 +279,23 @@ Testing (DAST), Secret Detection, Static Application Security Testing (SAST), an Each of these products typically include one or more analyzers. -### Secure report format +## Secure report format A standard report format that Secure products comply with when creating JSON reports. The format is described by a [JSON schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas). -### Security Dashboard +## Security Dashboard Provides an overview of all the vulnerabilities for a project, group, or GitLab instance. Vulnerabilities are only created from findings discovered on the project's default branch. -### Seed corpus +## Seed corpus The set of test cases given as initial input to the fuzz target. This usually speeds up the fuzz target substantially. This can be either manually created test cases or auto-generated with the fuzz target itself from previous runs. -### Vendor +## Vendor The party maintaining an analyzer. As such, a vendor is responsible for integrating a scanner into GitLab and keeping it compatible as they evolve. A vendor isn't necessarily the author or maintainer @@ -305,7 +303,7 @@ of the scanner, as in the case of using an open core or OSS project as a base so offering. For scanners included as part of a GitLab distribution or GitLab subscription, the vendor is listed as GitLab. -### Vulnerability +## Vulnerability A flaw that has a negative impact on the security of its environment. Vulnerabilities describe the error or weakness, and don't describe where the error is located (see [finding](#finding)). @@ -314,12 +312,12 @@ Each vulnerability maps to a unique finding. Vulnerabilities exist in the default branch. Findings (see [finding](#finding)) are all potential vulnerability items scanners identify in MRs/feature branches. Only after merging to default does a finding become a vulnerability. -### Vulnerability finding +## Vulnerability finding When a [report finding](#report-finding) is stored to the database, it becomes a vulnerability [finding](#finding). -### Vulnerability tracking +## Vulnerability tracking Deals with the responsibility of matching findings across scans so that a finding's life cycle can be understood. Engineers and security teams use this information to decide whether to merge code @@ -327,6 +325,6 @@ changes, and to see unresolved findings and when they were introduced. Vulnerabilities are tracked by comparing the location fingerprint, primary identifier, and report type. -### Vulnerability occurrence +## Vulnerability occurrence Deprecated, see [finding](#finding). diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 8107b9d8484..0cfeafe1fed 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -8,10 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in GitLab 13.0. -Each vulnerability in a project has a Vulnerability Page, containing details of the -vulnerability. The details included vary according to the type of vulnerability. - -Details of each vulnerability include: +Each vulnerability in a project has a vulnerability page containing details of the vulnerability, +including: - Description - When it was detected @@ -20,17 +18,13 @@ Details of each vulnerability include: - Linked issues - Actions log -In GitLab 14.3 and later, if the scanner determined the vulnerability to be a false positive, an -alert message is included at the top of the vulnerability's page. - -On the vulnerability's page, you can: +If the scanner determined the vulnerability to be a false positive, an alert message is included at +the top of the vulnerability's page. -- [Change the vulnerability's status](#change-status-of-a-vulnerability). -- [Create an issue](#creating-an-issue-for-a-vulnerability). -- [Link issues to the vulnerability](#linking-a-vulnerability-to-issues). -- [Resolve the vulnerability](#resolve-a-vulnerability) if a solution is - available. -- [View security training specific to the detected vulnerability](#view-security-training-for-a-vulnerability). +When a vulnerability is no longer detected in a project's default branch, you should +change its status to **Resolved**. This ensures that if it is accidentally reintroduced in a future +merge, it is reported again as a new record. To change the status of multiple vulnerabilities, use +the Vulnerability Report's [Activity filter](../vulnerability_report/index.md#activity-filter). ## Vulnerability status values @@ -38,16 +32,24 @@ A vulnerability's status can be: - **Detected**: The default state for a newly discovered vulnerability. Appears as "Needs triage" in the UI. - **Confirmed**: A user has seen this vulnerability and confirmed it to be accurate. -- **Dismissed**: A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. -- **Resolved**: The vulnerability has been fixed or is no longer present. +- **Dismissed**: A user has seen this vulnerability and dismissed it because it is not accurate or + otherwise not to be resolved. Dismissed vulnerabilities are ignored if detected in subsequent + scans. +- **Resolved**: The vulnerability has been fixed or is no longer present. Resolved vulnerabilities + that are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. + +## Vulnerability dismissal reasons + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4942) in GitLab 15.11 with a feature flag named `dismissal_reason`. +> - Enabled on GitLab.com in GitLab 15.11. For self-managed customers, [contact Support](https://about.gitlab.com/support/) if you would like to use this feature in GitLab 15.11. -Dismissed vulnerabilities are ignored if detected in subsequent scans. Resolved vulnerabilities that -are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. When an -existing vulnerability is no longer detected in a project's `default` branch, you should change its -status to **Resolved**. This ensures that if it is accidentally reintroduced in a future merge, it -is reported again as a new record. You can use the Vulnerability Report's -[Activity filter](../vulnerability_report/index.md#activity-filter) to select all vulnerabilities that are -no longer detected, and change their status. +When dismissing a vulnerability, one of the following reasons must be chosen to clarify why it is being dismissed: + +- **Acceptable risk**: The vulnerability is known, and has not been remediated or mitigated, but is considered to be an acceptable business risk. +- **False positive**: An error in reporting in which a test result incorrectly indicates the presence of a vulnerability in a system when the vulnerability is not present. +- **Mitigating control**: A management, operational, or technical control (that is, safeguard or countermeasure) employed by an organization that provides equivalent or comparable protection for an information system. +- **Used in tests**: The finding is not a vulnerability because it is part of a test or is test data. +- **Not applicable**: The vulnerability is known, and has not been remediated or mitigated, but is considered to be in a part of the application that will not be updated. ## Change status of a vulnerability @@ -57,9 +59,13 @@ To change a vulnerability's status from its Vulnerability Page: 1. On the left sidebar, select **Security and Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Status** dropdown list select a status, then select **Change status**. + + In GitLab 15.11 and later, you must select a [dismissal reason](#vulnerability-dismissal-reasons) when you change a vulnerability's status to **Dismissed**. + 1. Optionally, at the bottom of the page, add a comment to the log entry. -The Actions log records each status change along with which user changed the status and the time of the change. +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 diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index e75d0a45f7d..ab90ac18b8e 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -56,7 +56,7 @@ the following tables: |------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------| | [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating <sup>1</sup> | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | -1. The CVSS v3.1 rating is used to calculate the severity level. If it's not available, the CVSS v2.0 rating is used instead. +The CVSS v3.1 rating is used to calculate the severity level. If it's not available, the CVSS v2.0 rating is used instead. ## Container Scanning @@ -64,6 +64,8 @@ the following tables: |------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------| | [`container-scanning`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| **{check-circle}** Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` | +When available, the vendor severity level takes precedence and is used by the analyzer. If that is not available then it falls back on the CVSS v3.1 rating. If that is also not available, then the CVSS v2.0 rating is used instead. Details on this implementation are available on the respective issues for [trivy](https://github.com/aquasecurity/trivy/issues/310) and [grype](https://github.com/anchore/grype/issues/287). + ## Fuzz Testing All fuzz testing results are reported as Unknown. They should be reviewed and triaged manually to find exploitable faults to prioritize for fixing. diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 3d7565f97bc..a4c4737f767 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -19,6 +19,9 @@ At all levels, the Vulnerability Report contains: - Filters for common vulnerability attributes. - Details of each vulnerability, presented in tabular layout. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Vulnerability Management](https://www.youtube.com/watch?v=8SJHz6BCgXM). + The **Activity** column contains icons to indicate the activity, if any, taken on the vulnerability in that row: diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 982411d35f9..1ca558adbc2 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -1,13 +1,13 @@ --- -stage: Configure -group: Configure +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 --- # Using GitLab CI/CD with a Kubernetes cluster **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. -> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The pre-configured variable `$KUBECONFIG` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3. > - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. @@ -78,7 +78,8 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma - You can install additional agents into the same cluster to accommodate additional hierarchies. - You can authorize up to 100 projects. -All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. +All CI/CD jobs now include a `kubeconfig` file with contexts for every shared agent connection. +The `kubeconfig` path is available in the environment variable `$KUBECONFIG`. Choose the context to run `kubectl` commands from your CI/CD scripts. ### Authorize the agent to access projects in your groups @@ -104,7 +105,8 @@ To authorize the agent to access all of the GitLab projects in a group or subgro - You can authorize up to 100 groups. All the projects that belong to the group and its subgroups are now authorized to access the agent. -All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. +All CI/CD jobs now include a `kubeconfig` file with contexts for every shared agent connection. +The `kubeconfig` path is available in an environment variable `$KUBECONFIG`. Choose the context to run `kubectl` commands from your CI/CD scripts. ## Update your `.gitlab-ci.yml` file to run `kubectl` commands @@ -159,10 +161,10 @@ 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 the - `KUBECONFIG`. You can select them by using `kubectl config use-context path/to/agent/repository:agent-name`. +- 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`. - In GitLab 14.8 and earlier, you can still use agent connections, but for environments that - already have a certificate-based cluster, the agent connections are not included in the `KUBECONFIG`. + already have a certificate-based cluster, the agent connections are not included in `$KUBECONFIG`. To use an agent connection when certificate-based connections are present, you can manually configure a new `kubectl` configuration context. For example: @@ -183,6 +185,17 @@ deploy: # ... rest of your job configuration ``` +### Environments with KAS that use self-signed certificates + +If you use an environment with KAS and a self-signed certificate, you must configure your Kubernetes client to trust the certificate authority (CA) that signed your certificate. + +To configure your client, do one of the following: + +- Set a CI/CD variable `SSL_CERT_FILE` with the KAS certificate in PEM format. +- Configure the Kubernetes client with `--certificate-authority=$KAS_CERTIFICATE`, where `KAS_CERTIFICATE` is a CI/CD variable with the CA certificate of KAS. +- Place the certificates in an appropriate location in the job container by updating the container image or mounting via the runner. +- Not recommended. Configure the Kubernetes client with `--insecure-skip-tls-verify=true`. + ## Restrict project and group access by using impersonation **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. @@ -340,3 +353,16 @@ If you attempt to use `kubectl` without TLS, you might get an error like: $ kubectl get pods error: You must be logged in to the server (the server has asked for the client to provide credentials) ``` + +### Unable to connect to the server: certificate signed by unknown authority + +If you use an environment with KAS and a self-signed certificate, your `kubectl` call might return this error: + +```plaintext +kubectl get pods +Unable to connect to the server: x509: certificate signed by unknown authority +``` + +The error occurs because the job does not trust the certificate authority (CA) that signed the KAS certificate. + +To resolve the issue, [configure `kubectl` to trust the CA](#environments-with-kas-that-use-self-signed-certificates). diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 1d71f6ac511..106f751555a 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md index 9a3537aacbf..98840080716 100644 --- a/doc/user/clusters/agent/gitops/flux.md +++ b/doc/user/clusters/agent/gitops/flux.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -15,7 +15,7 @@ You can use Flux to: To get started, see the [Flux installation documentation](https://fluxcd.io/flux/installation). -Support for Flux is in [Open Beta](../../../../policy/alpha-beta-support.md#beta-features). +Support for Flux is in [Beta](../../../../policy/alpha-beta-support.md#beta). ## Bootstrap installation diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index 5f902002f83..88cc824b6b2 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -1,19 +1,21 @@ --- -stage: Configure -group: Configure -info: A tutorial using Flux with Project Access Tokens +stage: Deploy +group: Environments +info: A tutorial using Flux --- # Tutorial: Set up Flux for GitOps **(FREE)** This tutorial teaches you how to set up Flux for GitOps. You'll set up a sample project, complete a bootstrap Flux installation, and authenticate your installation with a -[project access token](../../../project/settings/project_access_tokens.md). +[project deploy token](../../../project/deploy_tokens/index.md). -You can find the fully configured tutorial project [in this GitLab repository](https://gitlab.com/gitlab-org/configure/examples/flux/flux-config). It works in conjunction with [this repository](https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests/-/tree/main), which contains the example Kubernetes manifests. +You can find the fully configured tutorial project [in this GitLab repository](https://gitlab.com/gitlab-org/configure/examples/flux/flux-config). +It works in conjunction with [this repository](https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests/-/tree/main), which contains the example Kubernetes manifests. -To set up Flux with a project access token: +To set up Flux for GitOps: +1. [Create a personal access token](#create-a-personal-access-token) 1. [Create the Flux repository](#create-the-flux-repository) 1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) 1. [Configure Flux to sync your manifests](#configure-flux-to-sync-your-manifests) @@ -21,27 +23,31 @@ To set up Flux with a project access token: Prerequisites: -- On GitLab SaaS, you must have the Premium or Ultimate tier to use a project access token. - On self-managed instances, you can have any tier. -- Not recommended. You can authenticate with a [personal or group access token](flux.md#bootstrap-installation) in all tiers. - You must have a Kubernetes cluster running. -## Create the Flux repository +## Create a personal access token -To start, create a Git repository, install Flux, and authenticate Flux with your repo: +To authenticate with the Flux CLI, you must create a personal access token +with the `api` scope: -1. Make sure your `kubectl` is configured to access your cluster. -1. [Install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). -1. In GitLab, create a new empty project called `flux-config`. -1. In the `flux-config` project, create a [project access token](../../../project/settings/project_access_tokens.md#create-a-project-access-token) with the following settings: +1. In the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Access Tokens**. +1. Enter a name and optional expiry date for the token. +1. Select the `api` scope. +1. Select **Create personal access token**. - - From the **Select a role** dropdown list, select **Maintainer**. - - Under **Select scopes**, select the **API** and **write_repository** checkboxes. +You can also use a [project](../../../project/settings/project_access_tokens.md) or [group access token](../../../group/settings/group_access_tokens.md) with the `api` scope. - Name the project token `flux-project-access-token`. +## Create the Flux repository -1. From your shell, export a `GITLAB_TOKEN` environment variable with the value of your project access token. - For example, `export GITLAB_TOKEN=<flux-project-access-token>`. +Create a Git repository, install Flux, and authenticate Flux with your repo: + +1. Make sure your `kubectl` is configured to access your cluster. +1. [Install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). You must install Flux v2 or higher. +1. In GitLab, create a new empty project called `flux-config`. +1. From your shell, export a `GITLAB_TOKEN` environment variable with the value of your personal access token. + For example, `export GITLAB_TOKEN=<personal-access-token>`. 1. Run the `bootstrap` command. The exact command depends on whether you are creating the Flux repository under a GitLab user, group, or subgroup. For more information, see the [Flux bootstrap documentation](https://fluxcd.io/flux/installation/#gitlab-and-gitlab-enterprise). @@ -54,11 +60,13 @@ To start, create a Git repository, install Flux, and authenticate Flux with your --repository=flux-config \ --branch=main \ --path=clusters/my-cluster + --deploy-token-auth ``` This command installs Flux on the Kubernetes cluster and configures it to manage itself from the repository `flux-config`. + The command also automatically creates the project deploy token required to access the `flux-config` repository. -Great work! You now have a repository, a project access token, and a Flux bootstrap installation authenticated to your repo. Any updates to your repo are automatically synced to the cluster. +Great work! You now have a repository bootstrapped with a Flux configuration. Any updates to your repository are automatically synced to the cluster. ## Create the Kubernetes manifest repository @@ -93,7 +101,7 @@ Next, create a repository for your Kubernetes manifests: - containerPort: 80 ``` -1. In the new repository, [create a deploy token](../../../project/deploy_tokens/index.md#create-a-deploy-token) with only the **read_repository** scope. +1. In the new repository, [create a deploy token](../../../project/deploy_tokens/index.md#create-a-deploy-token) with only the `read_repository` scope. 1. Store your deploy token username and password somewhere safe. 1. In Flux CLI, create a secret with your deploy token and point the secret to the new repository. For example: diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md index b9a59d37f5d..182fd87e6f9 100644 --- a/doc/user/clusters/agent/gitops/helm.md +++ b/doc/user/clusters/agent/gitops/helm.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +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 --- -# Using Helm charts to update a Kubernetes cluster (Alpha) **(FREE)** +# Using Helm charts to update a Kubernetes cluster (Experiment) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371019) in GitLab 15.4. > - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7. @@ -13,11 +13,11 @@ You can deploy Helm charts to your Kubernetes cluster and keep the resources in with your charts and values. To do this, you use the pull-based GitOps features of the agent for Kubernetes. -This feature is in Alpha and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938) +This feature is an Experiment and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938) to track future work. Tell us about your use cases by leaving comments in the epic. NOTE: -This feature is Alpha. In future releases, to accommodate new features, the configuration format might change without notice. +This feature is an Experiment. In future releases, to accommodate new features, the configuration format might change without notice. ## GitOps workflow steps diff --git a/doc/user/clusters/agent/gitops/secrets_management.md b/doc/user/clusters/agent/gitops/secrets_management.md index 8a47dcfaf72..6e1b7da9c6c 100644 --- a/doc/user/clusters/agent/gitops/secrets_management.md +++ b/doc/user/clusters/agent/gitops/secrets_management.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 0d84a617808..07149ccd8fc 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -57,9 +57,9 @@ This workflow has a weaker security model and is not recommended for production GitLab supports the following Kubernetes versions. You can upgrade your Kubernetes version to a supported version at any time: +- 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported) - 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported) - 1.24 (support ends on July 22, 2023 or when 1.27 becomes supported) -- 1.23 (support ends on February 22, 2023 or when 1.26 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. diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 297210ab8ef..1bcbb42fc8e 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -138,6 +138,23 @@ By default, the Helm installation command generated by GitLab: To see the full list of customizations available, see the Helm chart's [default values file](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/blob/main/values.yaml). +##### Use the agent when KAS is behind a self-signed certificate + +When [KAS](../../../../administration/clusters/kas.md) is behind a self-signed certificate, +you can set the value of `config.caCert` to the certificate. For example: + +```shell +helm update --install gitlab-agent gitlab/gitlab-agent \ + --set-file config.caCert=my-custom-ca.pem +``` + +In this example, `my-custom-ca.pem` is the path to a local file that contains +the CA certificate used by KAS. The certificate is automatically stored in a +config map and mounted in the `agentk` pod. + +If KAS is installed with the GitLab chart, and the chart is configured to provide +an [auto-generated self-signed wildcard certificate](https://docs.gitlab.com/charts/installation/tls.html#option-4-use-auto-generated-self-signed-wildcard-certificate), you can extract the CA certificate from the `RELEASE-wildcard-tls-ca` secret. + ##### Use the agent behind an HTTP proxy > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351867) in GitLab 15.0, the GitLab agent Helm chart supports setting environment variables. @@ -155,6 +172,10 @@ helm upgrade --install gitlab-agent gitlab/gitlab-agent \ ... ``` +NOTE: +DNS rebind protection is disabled when either the `HTTP_PROXY` or the `HTTPS_PROXY` environment variable is set, +and the domain DNS can't be resolved. + #### Advanced installation method GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 84cdbbcc096..d058a583b19 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 0b0e1365604..2d54f67724e 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 910092eb4e0..6f00466bc7e 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md index 0721cea965a..57526394301 100644 --- a/doc/user/clusters/create/index.md +++ b/doc/user/clusters/create/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index dc6898bd3d3..c6a61f58974 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index b5600096856..2c67afefd98 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f2eb0cfbc39..0ad3fdbef2e 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 9edb012ba92..4b6c8dcac4c 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- 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 42510a93495..fde8e455421 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index d5af7edf515..1962dfefdf5 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -85,10 +85,10 @@ The following are unavailable compliance violations that are tracked in [epic 52 |:-------------------------------------|:---------------|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------| | Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | Merge requests pipeline failed and was merged. | | Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | Merge request pipeline passed with warnings and was merged. | -| Code coverage down more than 10% | High | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | -| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | -| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | -| Code coverage down less than 1% | Info | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | +| Code coverage down more than 10% | High | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | +| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | +| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | +| Code coverage down less than 1% | Info | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | <!-- vale gitlab.SubstitutionWarning = YES --> @@ -170,7 +170,8 @@ passing in an optional value to the `commit_sha` query parameter. ## Compliance frameworks report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10. +> - Support for applying/removing compliance framework [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11 With compliance frameworks report, you can see the compliance frameworks that are applied to projects in a group. Each row of the report shows: @@ -191,3 +192,51 @@ To view the compliance frameworks report: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Compliance report**. 1. On the page, select the **Frameworks** tab. + +### Apply a compliance framework to projects in a group + +Prerequisites: + +- You must have the Owner role for the group. + +To apply a compliance framework to projects in a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Security and Compliance > Compliance report**. +1. On the page, select the **Frameworks** tab. +1. Select one or more projects. +1. From the **Choose one bulk action** dropdown list, select **Apply framework to selected projects**. +1. Select framework to apply. +1. Select **Apply**. + +### Remove a compliance framework from projects in a group + +Prerequisites: + +- You must have the Owner role for the group. + +To remove a compliance framework from projects in a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Security and Compliance > Compliance report**. +1. On the page, select the **Frameworks** tab. +1. Select one or more projects. +1. From the **Choose one bulk action** dropdown list, select **Remove framework from selected projects**. +1. Select **Remove**. + +#### Filter the compliance frameworks report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387911) in GitLab 15.11. + +To filter the list of compliance frameworks: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance report**. +1. On the page, select the **Frameworks** 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}**). + +Repeat this process to filter by multiple attributes. diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md index 2769732c49a..4e10d01b18e 100644 --- a/doc/user/compliance/license_approval_policies.md +++ b/doc/user/compliance/license_approval_policies.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # License Approval Policies **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `license_scanning_policies`. Disabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `license_scanning_policies`. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed. License Approval Policies allow you to specify multiple types of criteria that define when approval is required before a merge request can be merged in. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 55aa5b2b653..8c6d5ee893f 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -5,13 +5,13 @@ 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 --- -# License compliance (deprecated) **(ULTIMATE)** +# License Compliance (deprecated) **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. Users should migrate over to use the [new method of license scanning](../license_scanning_of_cyclonedx_files/index.md) prior to GitLab 16.0. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. You should instead migrate to use [License approval policies](../license_approval_policies.md) and the [new method of license scanning](../license_scanning_of_cyclonedx_files/index.md) prior to GitLab 16.0. If you're using [GitLab CI/CD](../../../ci/index.md), you can use License Compliance to search your project's dependencies for their licenses. You can then decide whether to allow or deny the use of @@ -49,6 +49,38 @@ that you can later download and analyze. WARNING: License Compliance Scanning does not support run-time installation of compilers and interpreters. +## Enable License Compliance + +To enable License Compliance in your project's pipeline, either: + +- Enable [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) + (provided by [Auto DevOps](../../../topics/autodevops/index.md)). +- Include the [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) in your `.gitlab-ci.yml` file. + +License Compliance is not supported when GitLab is run with FIPS mode enabled. + +### Include the License Scanning template + +Prerequisites: + +- [GitLab Runner](../../../ci/runners/index.md) available, with the + [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). If you're using the + shared runners on GitLab.com, this is enabled by default. +- License Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the + `.gitlab-ci.yml` file, the `test` stage is required. +- [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) must be disabled. + +To [include](../../../ci/yaml/index.md#includetemplate) the +[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml), add it to your `.gitlab-ci.yml` file: + +```yaml +include: + - template: Security/License-Scanning.gitlab-ci.yml +``` + +The included template creates a `license_scanning` job in your CI/CD pipeline and scans your +dependencies to find their licenses. + ## License expressions GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). @@ -89,39 +121,7 @@ The reported licenses might be incomplete or inaccurate. | Rust | [Cargo](https://crates.io/) | | PHP | [Composer](https://getcomposer.org/) | -## Enable License Compliance - -To enable License Compliance in your project's pipeline, either: - -- Enable [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) - (provided by [Auto DevOps](../../../topics/autodevops/index.md)). -- Include the [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) in your `.gitlab-ci.yml` file. - -License Compliance is not supported when GitLab is run with FIPS mode enabled. - -### Include the License Scanning template - -Prerequisites: - -- [GitLab Runner](../../../ci/runners/index.md) available, with the - [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). If you're using the - shared runners on GitLab.com, this is enabled by default. -- License Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the - `.gitlab-ci.yml` file, the `test` stage is required. -- [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) must be disabled. - -To [include](../../../ci/yaml/index.md#includetemplate) the -[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml), add it to your `.gitlab-ci.yml` file: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml -``` - -The included template creates a `license_scanning` job in your CI/CD pipeline and scans your -dependencies to find their licenses. - -### Available CI/CD variables +## Available CI/CD variables License Compliance can be configured using CI/CD variables. @@ -141,7 +141,7 @@ License Compliance can be configured using CI/CD variables. | `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | | `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | -### Installing custom dependencies +## Installing custom dependencies > Introduced in GitLab 11.4. @@ -169,7 +169,7 @@ variables: In this example, `my-custom-install-script.sh` is a shell script at the root directory of your project. -### Working with Monorepos +## Working with Monorepos Depending on your language, you may need to specify the path to the individual projects of a monorepo using the `LICENSE_FINDER_CLI_OPTS` variable. Passing in @@ -184,7 +184,7 @@ variables: LICENSE_FINDER_CLI_OPTS: "--aggregate_paths=relative-path/to/sub-project/one relative-path/to/sub-project/two" ``` -### Overriding the template +## Overriding the template WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) @@ -203,7 +203,7 @@ license_scanning: CI_DEBUG_TRACE: "true" ``` -### Configuring Maven projects +## Configuring Maven projects The License Compliance tool provides a `MAVEN_CLI_OPTS` CI/CD variable which can hold the command line arguments to pass to the `mvn install` command which is executed under the hood. @@ -227,7 +227,7 @@ to explicitly add `-DskipTests` to your options. If you still need to run tests during `mvn install`, add `-DskipTests=false` to `MAVEN_CLI_OPTS`. -#### Using private Maven repositories +### Using private Maven repositories If you have a private Maven repository which requires login credentials, you can use the `MAVEN_CLI_OPTS` CI/CD variable. @@ -250,13 +250,13 @@ Alternatively, you can use a Java key store to verify the TLS connection. For in generate a key store file, see the [Maven Guide to Remote repository access through authenticated HTTPS](https://maven.apache.org/guides/mini/guide-repository-ssl.html). -### Selecting the version of Java +## Selecting the version of Java License Compliance uses Java 8 by default. You can specify a different Java version using `LM_JAVA_VERSION`. `LM_JAVA_VERSION` only accepts versions: 8, 11, 14, 15. -### Selecting the version of Python +## Selecting the version of Python > - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in GitLab 12.0. > - In [GitLab 12.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12032), Python 3.5 became the default. @@ -277,22 +277,22 @@ license_scanning: `LM_PYTHON_VERSION` or `ASDF_PYTHON_VERSION` can be used to specify the desired version of Python. When both variables are specified `LM_PYTHON_VERSION` takes precedence. -### Custom root certificates for Python +## Custom root certificates for Python You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). -#### Using private Python repositories +### Using private Python repositories If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-cicd-variables) to specify its location. -### Configuring npm projects +## Configuring npm projects You can configure npm projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) file. -#### Using private npm registries +### Using private npm registries If you have a private npm registry you can use the [`registry`](https://docs.npmjs.com/using-npm/config/#registry) @@ -304,7 +304,7 @@ For example: registry = https://npm.example.com ``` -#### Custom root certificates for npm +### Custom root certificates for npm You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). @@ -318,12 +318,12 @@ For example: strict-ssl = false ``` -### Configuring Yarn projects +## Configuring Yarn projects You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc/) file. -#### Using private Yarn registries +### Using private Yarn registries If you have a private Yarn registry you can use the [`npmRegistryServer`](https://yarnpkg.com/configuration/yarnrc/#npmRegistryServer) @@ -335,17 +335,17 @@ For example: npmRegistryServer: "https://npm.example.com" ``` -#### Custom root certificates for Yarn +### Custom root certificates for Yarn You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). -### Configuring Bower projects +## Configuring Bower projects You can configure Bower projects by using a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) file. -#### Using private Bower registries +### Using private Bower registries If you have a private Bower registry you can use the [`registry`](https://bower.io/docs/config/#bowerrc-specification) @@ -359,16 +359,16 @@ For example: } ``` -#### Custom root certificates for Bower +### Custom root certificates for Bower You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) file. -### Configuring Bundler projects +## Configuring Bundler projects -#### Using private Bundler registries +### Using private Bundler registries If you have a private Bundler registry you can use the [`source`](https://bundler.io/man/gemfile.5.html#GLOBAL-SOURCES) @@ -380,7 +380,7 @@ For example: source "https://gems.example.com" ``` -#### Custom root certificates for Bundler +### Custom root certificates for Bundler You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by @@ -388,9 +388,9 @@ specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1. [variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. -### Configuring Cargo projects +## Configuring Cargo projects -#### Using private Cargo registries +### Using private Cargo registries If you have a private Cargo registry you can use the [`registries`](https://doc.rust-lang.org/cargo/reference/registries.html) @@ -403,7 +403,7 @@ For example: my-registry = { index = "https://my-intranet:8080/git/index" } ``` -#### Custom root certificates for Cargo +### Custom root certificates for Cargo To supply a custom root certificate to complete TLS verification, do one of the following: @@ -412,9 +412,9 @@ To supply a custom root certificate to complete TLS verification, do one of the [variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. -### Configuring Composer projects +## Configuring Composer projects -#### Using private Composer registries +### Using private Composer registries If you have a private Composer registry you can use the [`repositories`](https://getcomposer.org/doc/05-repositories.md) @@ -437,7 +437,7 @@ For example: } ``` -#### Custom root certificates for Composer +### Custom root certificates for Composer You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by @@ -445,7 +445,7 @@ specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer- [variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. -### Configuring Conan projects +## Configuring Conan projects You can configure [Conan](https://conan.io/) projects by adding a `.conan` directory to your project root. The project root serves as the [`CONAN_USER_HOME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-user-home). @@ -474,7 +474,7 @@ NOTE: `license_scanning` image ships with [Mono](https://www.mono-project.com/) and [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild). Additional setup may be required to build packages for this project configuration. -#### Using private Conan registries +### Using private Conan registries By default, [Conan](https://conan.io/) uses the `conan-center` remote. For example: @@ -508,7 +508,7 @@ example: If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/index.md#protect-a-cicd-variable) following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). -#### Custom root certificates for Conan +### Custom root certificates for Conan You can provide custom certificates by adding a `.conan/cacert.pem` file to the project root and setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) @@ -518,7 +518,7 @@ If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd- variable's X.509 certificates are installed in the Docker image's default trust store and Conan is configured to use this as the default `CA_CERT_PATH`. -### Configuring Go projects +## Configuring Go projects To configure [Go modules](https://github.com/golang/go/wiki/Modules) based projects, specify [CI/CD variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables) @@ -528,14 +528,14 @@ If a project has [vendored](https://pkg.go.dev/cmd/go#hdr-Vendor_Directories) it then the combination of the `vendor` directory and `mod.sum` file are used to detect the software licenses associated with the Go module dependencies. -#### Using private Go registries +### Using private Go registries You can use the [`GOPRIVATE`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) and [`GOPROXY`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) environment variables to control where modules are sourced from. Alternatively, you can use [`go mod vendor`](https://go.dev/ref/mod#tmp_28) to vendor a project's modules. -#### Custom root certificates for Go +### Custom root certificates for Go You can specify the [`-insecure`](https://pkg.go.dev/cmd/go/internal/get) flag by exporting the [`GOFLAGS`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) @@ -550,7 +550,7 @@ license_scanning: GOFLAGS: '-insecure' ``` -#### Using private NuGet registries +### Using private NuGet registries If you have a private NuGet registry you can add it as a source by adding it to the [`packageSources`](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) @@ -568,7 +568,7 @@ For example: </configuration> ``` -#### Custom root certificates for NuGet +### Custom root certificates for NuGet You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). 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 0ad73f9939d..ce0c6451688 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -7,10 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # License scanning of CycloneDX files **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags are disabled by default and both flags must be enabled for this feature to work. - -FLAG: -On self-managed GitLab, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 for GitLab SaaS [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags are disabled by default and both flags must be enabled for this feature to work. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.10 for GitLab SaaS. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.10 for self-managed GitLab [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`, both of which must be enabled for this feature to work. The flags are disabled by default due to the initial performance load when the license database is first imported. Work to improve performance is being tracked in [issue 397670](https://gitlab.com/gitlab-org/gitlab/-/issues/397670). +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.11 for self-managed GitLab. To detect the licenses in use, License Compliance relies on running the [Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), @@ -19,13 +19,15 @@ Other 3rd party scanners may also be used as long as they produce a CycloneDX fi 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. -To enable license detection using Dependency Scanning in a project, -include the `Jobs/Dependency-Scanning.gitlab-ci.yml` template in its CI configuration, -but do not include the `Jobs/License-Scanning.gitlab-ci.yml` template. +## Enable license scanning + +Prerequisites: -## Requirements +- Enable [Synchronization with the GitLab License Database](../../admin_area/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in Admin Area for the GitLab instance. +- Enable [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration). -The license scanning requirements are the same as those for [Dependency Scanning](../../application_security/dependency_scanning/index.md#requirements). +From the `.gitlab-ci.yml` file, remove the deprecated line `Jobs/License-Scanning.gitlab-ci.yml`, if +it's present. ## Supported languages and package managers @@ -66,10 +68,13 @@ License scanning is supported for the following languages and package managers: <td><a href="https://maven.apache.org/">Maven</a></td> </tr> <tr> - <td rowspan="2">JavaScript and TypeScript</td> + <td rowspan="3">JavaScript and TypeScript</td> <td><a href="https://www.npmjs.com/">npm</a></td> </tr> <tr> + <td><a href="https://pnpm.io/">pnpm</a></td> + </tr> + <tr> <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> </tr> <tr> @@ -104,11 +109,6 @@ License scanning is supported for the following languages and package managers: The supported files and versions are the ones supported by [Dependency Scanning](../../application_security/dependency_scanning/index.md#supported-languages-and-package-managers). -## Configuration - -To enable license scanning of CycloneDX files, -you must configure [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration). - ## License expressions GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index c71ea6576ef..096b4dc2cc5 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -316,7 +316,7 @@ At the top of the page, the number of unresolved threads is updated: If you have multiple unresolved threads in a merge request, you can create an issue to resolve them separately. In the merge request, at the top of the page, -select the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Create issue to resolve all threads**: +select the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Resolve all with new issue**:  diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index b6a823c656f..901731ad6f9 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -22,7 +22,7 @@ A user account is considered an enterprise account when: - [SCIM](../group/saml_sso/scim_setup.md) creates the user account on behalf of the group. -A user can also [manually connect an identity provider (IdP) to a GitLab account whose email address matches the subscribing organization's domain](../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). +A user can also [manually connect an identity provider (IdP) to a GitLab account whose email address matches the subscribing organization's domain](../group/saml_sso/index.md#link-saml-to-your-existing-gitlabcom-account). By selecting **Authorize** when connecting these two accounts, the user account with the matching email address is classified as an enterprise user. However, this user account does not have an **Enterprise** badge in GitLab. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 4fb16d6ea27..68d1b51ec08 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -65,7 +65,7 @@ The IP addresses for `mg.gitlab.com` are subject to change at any time. On GitLab.com, there's a mailbox configured for Service Desk with the email address: `contact-project+%{key}@incoming.gitlab.com`. To use this mailbox, configure the -[custom suffix](../project/service_desk.md#configuring-a-custom-email-address-suffix) in project +[custom suffix](../project/service_desk.md#configure-a-custom-email-address-suffix) in project settings. ## Backups @@ -128,13 +128,14 @@ Host gitlab.com Some settings for [GitLab Pages](../project/pages/index.md) differ from the [defaults for self-managed instances](../../administration/pages/index.md): -| Setting | GitLab.com | -|------------------------------|------------------------| -| Domain name | `gitlab.io` | -| IP address | `35.185.44.232` | -| Support for custom domains | **{check-circle}** Yes | -| Support for TLS certificates | **{check-circle}** Yes | -| Maximum site size | 1 GB | +| Setting | GitLab.com | +|---------------------------------------------------|------------------------| +| Domain name | `gitlab.io` | +| IP address | `35.185.44.232` | +| Support for custom domains | **{check-circle}** Yes | +| Support for TLS certificates | **{check-circle}** Yes | +| Maximum site size | 1 GB | +| Number of custom domains per GitLab Pages website | 150 | The maximum size of your Pages site depends on the maximum artifact size, which is part of [GitLab CI/CD](#gitlab-cicd). @@ -152,7 +153,7 @@ the related documentation. | Artifacts maximum size (compressed) | 1 GB | See [Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size). | | Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | See [Default artifacts expiration](../admin_area/settings/continuous_integration.md#default-artifacts-expiration). | | Scheduled Pipeline Cron | `*/5 * * * *` | See [Pipeline schedules advanced configuration](../../administration/cicd.md#change-maximum-scheduled-pipeline-frequency). | -| Maximum jobs in active pipelines | `500` for Free tier, `1000` for all trial tiers, and unlimited otherwise. | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines). | +| Maximum jobs in active pipelines | `500` for Free tier, `1000` for all trial tiers, `20000` for Premium, and `100000` for Ultimate. | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines). | | Maximum CI/CD subscriptions to a project | `2` | See [Number of CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project). | | Maximum number of pipeline triggers in a project | `25000` for Free tier, Unlimited for all paid tiers | See [Limit the number of pipeline triggers](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers). | | Maximum pipeline schedules in projects | `10` for Free tier, `50` for all paid tiers | See [Number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules). | @@ -189,7 +190,7 @@ the default value [is the same as for self-managed instances](../admin_area/sett | Setting | GitLab.com default | |-------------------------------|--------------------| | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | -| [Maximum import size](../project/settings/import_export.md#maximum-import-file-size) | 5 GB | +| [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GB | | Maximum attachment size | 100 MB | If you are near or over the repository size limit, you can either diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 0299f5c1a74..ad27255f42e 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -102,8 +102,9 @@ Keep in mind that restricting group access by IP address has the following impli restricted IP address, the IP restriction prevents code from being cloned. - Users might still see some events from the IP-restricted groups and projects on their dashboard. Activity might include push, merge, issue, or comment events. -- IP access restrictions for Git operations via SSH are supported only on GitLab SaaS. - IP access restrictions applied to self-managed instances block SSH completely. +- IP access restrictions for Git operations via SSH are supported on GitLab SaaS. + IP access restrictions applied to self-managed instances are possible with [`gitlab-sshd`](../../administration/operations/gitlab_sshd.md) + with [PROXY protocol](../../administration/operations/gitlab_sshd.md#proxy-protocol-support) enabled. ## Restrict group access by domain **(PREMIUM)** diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index a6dba3afacd..4c448d8e5c2 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -1,7 +1,7 @@ --- type: reference -stage: Configure -group: Configure +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 --- diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 4ea474069cd..69642833d8a 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -34,10 +34,6 @@ default framework cannot be deleted. A compliance framework that is set to default has a **default** label. -NOTE: -Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/394630), only group owners can apply the default compliance framework when creating -new projects or importing projects. - ### Set and remove as default > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375038) in GitLab 15.7. @@ -108,8 +104,11 @@ However, the compliance pipeline configuration can reference the `.gitlab-ci.yml - Jobs and variables defined in the compliance pipeline can't be changed by variables in the labeled project's `.gitlab-ci.yml` file. -See [example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from -labeled project pipeline configuration. +For more information, see: + +- [Example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from + labeled project pipeline configuration. +- The [Create a compliance pipeline](../../tutorials/create_compliance_pipeline.md) tutorial. ### Effect on labeled projects @@ -348,3 +347,53 @@ mutation { } } ``` + +### Compliance jobs are overwritten by target repository + +If you use the `extends` statement in a compliance pipeline configuration, compliance jobs are overwritten by the target repository job. For example, +you could have the following `.compliance-gitlab-ci.yml` configuration: + +```yaml +"compliance job": + extends: + - .compliance_template + stage: build + +.compliance_template: + script: + - echo "take compliance action" +``` + +You could also have the following `.gitlab-ci.yml` configuration: + +```yaml +"compliance job": + stage: test + script: + - echo "overwriting compliance action" +``` + +This configuration results in the target repository pipeline overwriting the compliance pipeline, and you get the following message: +`overwriting compliance action`. + +To avoid overwriting a compliance job, don't use the `extends` keyword in compliance pipeline configuration. For example, +you could have the following `.compliance-gitlab-ci.yml` configuration: + +```yaml +"compliance job": + stage: build + script: + - echo "take compliance action" +``` + +You could also have the following `.gitlab-ci.yml` configuration: + +```yaml +"compliance job": + stage: test + script: + - echo "overwriting compliance action" +``` + +This configuration doesn't overwrite the compliance pipeline and you get the following message: +`take compliance action`. diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index a81b61c50ce..7105318e5df 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Group DevOps Adoption **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](../../../policy/alpha-beta-support.md#beta-features). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](../../../policy/alpha-beta-support.md#beta). > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333556) in GitLab 14.1. > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 6ec56d0d510..897504942f7 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -8,11 +8,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. +> - Displaying total weight on the top of lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364503) in GitLab 15.11. Epic boards build on the existing [epic tracking functionality](index.md) and [labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned labels. +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>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/I1bFIAQBHB8" frameborder="0" allowfullscreen> </iframe> +</figure> + To view an epic board: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -100,7 +110,7 @@ To remove a list from an epic board: 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. -## Create an epic from an epic board +### Create an epic from an epic board > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233568) in GitLab 14.0. @@ -216,15 +226,3 @@ To edit the scope of an epic board: - Show or hide the Open and Closed columns. - Select other labels as the board's scope. 1. Select **Save changes**. - -#### Display total weight on board lists - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364503) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `fe_epic_board_total_weight`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364503) in GitLab 15.9. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364503) in GitLab 15.10. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `fe_epic_board_total_weight`. -On GitLab.com, this feature is available. - -When enabled, this feature displays total weight of all epics at the top of each list. diff --git a/doc/user/group/epics/img/epic_board_v15_10.png b/doc/user/group/epics/img/epic_board_v15_10.png Binary files differindex d836abdbb59..03bc96d9623 100644 --- a/doc/user/group/epics/img/epic_board_v15_10.png +++ b/doc/user/group/epics/img/epic_board_v15_10.png diff --git a/doc/user/group/epics/img/issue_list_v13_1.png b/doc/user/group/epics/img/issue_list_v13_1.png Binary files differdeleted file mode 100644 index ed0b4842bfe..00000000000 --- a/doc/user/group/epics/img/issue_list_v13_1.png +++ /dev/null diff --git a/doc/user/group/epics/img/issue_list_v15_11.png b/doc/user/group/epics/img/issue_list_v15_11.png Binary files differnew file mode 100644 index 00000000000..601406a8a33 --- /dev/null +++ b/doc/user/group/epics/img/issue_list_v15_11.png diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 3a0fc86e803..0dc87b7e4e4 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -421,7 +421,7 @@ To remove an issue from an epic: The **Remove issue** warning appears. 1. Select **Remove**. - + ### Reorder issues assigned to an epic diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index b0297076a43..c5a12d3fc8e 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -40,7 +40,7 @@ Migrating groups by direct transfer copies the groups from one place to another. - The subgroup of any existing top-level group. - Another GitLab instance, including GitLab.com. - In the [API](../../../api/bulk_imports.md), copy top-level groups and subgroups to these locations. -- Copy groups with projects (in [beta](../../../policy/alpha-beta-support.md#beta-features) and not ready for production +- Copy groups with projects (in [Beta](../../../policy/alpha-beta-support.md#beta) and not ready for production use) or without projects. Copying projects with groups is available: - On GitLab.com by default. @@ -50,7 +50,7 @@ Not all group and project resources are copied. See list of copied resources bel - [Migrated project items](#migrated-project-items-beta). WARNING: -Importing groups with projects is in [beta](../../../policy/alpha-beta-support.md#beta-features). This feature is not +Importing groups with projects is in [Beta](../../../policy/alpha-beta-support.md#beta). This feature is not ready for production use. We invite you to leave your feedback about migrating by direct transfer in @@ -122,7 +122,7 @@ To ensure GitLab maps users and their contributions correctly: 1. Ensure that users have a public email on the source GitLab instance that matches any confirmed email address on the destination GitLab instance. Most users receive an email asking them to confirm their email address. 1. If users already exist on the destination instance and you use [SAML SSO for GitLab.com groups](../../group/saml_sso/index.md), all users must - [link their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). + [link their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#link-saml-to-your-existing-gitlabcom-account). ### Connect the source GitLab instance @@ -137,7 +137,7 @@ Create the group you want to import to and connect the source GitLab instance: 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. -### Select the groups to import +### Select the groups and projects to import > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects. @@ -153,7 +153,7 @@ role. 1. After a group has been imported, select its GitLab path to open its GitLab URL. WARNING: -Importing groups with projects is in [beta](../../../policy/alpha-beta-support.md#beta-features). This feature is not +Importing groups with projects is in [Beta](../../../policy/alpha-beta-support.md#beta). This feature is not ready for production use. ### Group import history @@ -220,11 +220,15 @@ Group items that are migrated to the destination GitLab instance include: - Already exists in the destination GitLab instance. - Has a public email in the source GitLab instance that matches a confirmed email in the destination GitLab instance. -### Migrated project items (beta) +### Migrated project items (Beta) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. > - `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10. +> - Project-only migrations using API [added](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11. + +If you choose to migrate projects when you [select groups to migrate](#select-the-groups-and-projects-to-import), +project items are migrated with the projects. The project items that are migrated depends on the version of GitLab you use on the destination. To determine if a specific project item is migrated: @@ -243,8 +247,11 @@ specific project item is migrated: Any other project items are **not** migrated. +If you choose not to migrate projects along with groups or if you want to retry a project migration, you can +initiate project-only migrations using the [API](../../../api/bulk_imports.md). + WARNING: -Migrating projects when migrating groups by direct transfer is in [beta](../../../policy/alpha-beta-support.md#beta-features) +Migrating projects when migrating groups by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta) and is not ready for production use. Project items that are migrated to the destination GitLab instance include: @@ -256,6 +263,7 @@ Project items that are migrated to the destination GitLab instance include: | Badges | [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75029) | | Branches (including protected branches) | [GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/339414) | | CI Pipelines | [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/339407) | +| Commit comments | [GitLab 15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/391601) | | Designs | [GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/339421) | | Issues | [GitLab 14.4](https://gitlab.com/gitlab-org/gitlab/-/issues/267946) | | Issue boards | [GitLab 14.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71661) | @@ -344,7 +352,7 @@ entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :s ``` You can also see all migrated entities with any failures related to them using an -[API endpoint](../../../api/bulk_imports.md#list-all-group-migrations-entities). +[API endpoint](../../../api/bulk_imports.md#list-all-group-or-project-migrations-entities). #### Stale imports @@ -429,13 +437,11 @@ Note the following: ### Compatibility -Group file exports are in NDJSON format. GitLab previously produced group file exports in JSON format, however: +> Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/383682) in GitLab 15.8. -- From GitLab 15.8, GitLab no longer supports importing a JSON-formatted group file export. -- Between GitLab 14.0 and GitLab 14.7, GitLab no longer produces group file exports in JSON format but, to support - transitions, can still import JSON-formatted group file exports. +Group file exports are in NDJSON format. -From GitLab 13.0, GitLab can import group file exports that were exported from a version of GitLab up to two +You can import group file exports that were exported from a version of GitLab up to two [minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for [security releases](../../../policy/maintenance.md#security-releases). diff --git a/doc/user/group/index.md b/doc/user/group/index.md index d35a0920cf2..7e093ccb01b 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -20,6 +20,16 @@ For larger organizations, you can also create [subgroups](subgroups/index.md). For more information about creating and managing your groups, see [Manage groups](manage.md). +NOTE: +Self-managed customers should create a top-level group so you can see an overview of +your organization. For more information about efforts to create an +organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitlab-org/-/epics/9266). +A top-level group can also have one complete +[Security Dashboard and Center](../application_security/security_dashboard/index.md), +[Vulnerability](../application_security/vulnerability_report/index.md#vulnerability-report) and +[Compliance Report](../compliance/compliance_report/index.md), and +[Value stream analytics](../group/value_stream_analytics/index.md). + ## Group visibility Like projects, a group can be configured to limit the visibility of it to: diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 622112d9735..8d20c764bef 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -8,6 +8,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use groups to manage one or more related projects at the same time. +NOTE: +Self-managed customers should create a top-level group so you can see an overview of +your organization. For more information about efforts to create an +organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitlab-org/-/epics/9266). +A top-level group can also have one complete +[Security Dashboard and Center](../application_security/security_dashboard/index.md), +[Vulnerability](../application_security/vulnerability_report/index.md#vulnerability-report) and +[Compliance Report](../compliance/compliance_report/index.md), and +[Value stream analytics](../group/value_stream_analytics/index.md). + ## View groups To view groups, on the top bar, select **Main menu > Groups > View all groups**. @@ -237,6 +247,23 @@ To change this setting for a specific group: To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). +## Add Group README + +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: + +- To create the README from the group settings, you must have the Owner role for the group. + +To add a group README: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. In the **Group README** section, select **Add README**. This action creates a new project `gitlab-profile` that contains the `README.md` file. +1. On the prompt for creating a README, select **Create and add README**. You're redirected to the Web IDE, where a README file is created. +1. In the Web IDE, edit and commit the `README.md` file. + ## Change the owner of a group You can change the owner of a group. Each group must always have at least one @@ -371,6 +398,7 @@ To transfer a group: > - [Instance setting to enable by default added](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. > - [Instance setting is inherited and enforced when disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. > - [User interface changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352961) in GitLab 15.1. +> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `always_perform_delayed_deletion`. Disabled by default. [Delayed project deletion](../project/settings/index.md#delayed-project-deletion) is locked and disabled unless the instance-level settings for [deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) are enabled for either groups only or groups and projects. @@ -398,8 +426,10 @@ To enable delayed deletion of projects in a group: - (GitLab 15.0 and earlier), **Enforce for all subgroups**. 1. Select **Save changes**. -NOTE: -In GitLab 13.11 and above the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. +In GitLab 13.11 and later, the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md), inheritance can be overridden unless enforced by an ancestor. + +In GitLab 15.11 with the `always_perform_delayed_deletion` feature flag enabled, this setting is removed +and all projects are deleted after the [retention period defined by the admin](../admin_area/settings/visibility_and_access_controls.md#retention-period). ## Disable email notifications @@ -447,6 +477,10 @@ You can export a list of members in a group or subgroup as a CSV. 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. +The output lists direct members and members inherited from the ancestor groups. +For members with `Minimal Access` in the selected group, their `Max Role` and `Source` are derived from their membership in subgroups. +[Issue 390358](https://gitlab.com/gitlab-org/gitlab/-/issues/390358) tracks the discussion about the group members CSV export list not matching the UI members list. + ## User cap for groups > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. @@ -465,7 +499,7 @@ disabled for the group and its subgroups. Prerequisite: -- You must be assigned the Owner role) for the group. +- You must be assigned the Owner role for the group. To specify a user cap: @@ -640,9 +674,28 @@ To view the merge request approval settings for a group: Support for group-level settings for merge request approval rules is tracked in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). +## Group Code Suggestions **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405126) in GitLab 15.11. + +WARNING: +This feature is in [Beta](/ee/policy/alpha-beta-support.md#beta). Code Suggestions use generative AI to suggest code while you're developing. Due to high demand, this feature will have unscheduled downtime and code suggestions in VS Code may be delayed. Code Suggestions may produce [low-quality or incomplete suggestions](../project/repository/code_suggestions.md#model-accuracy-and-quality). Beta users should read about the [known limitations](../project/repository/code_suggestions.md#known-limitations). We look forward to hearing your feedback. + +This setting enables users in the group to access [Code Suggestions](../project/repository/code_suggestions.md). +This setting [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) +that belong to the group. + +To enable Code Suggestions for a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Find the **Code Suggestions** settings. +1. Select **Save changes**. + ## Group activity analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/alpha-beta-support.md#beta-features). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/alpha-beta-support.md#beta). For a group, you can view how many merge requests, issues, and members were created in the last 90 days. diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md new file mode 100644 index 00000000000..4ec86893524 --- /dev/null +++ b/doc/user/group/moderate_users.md @@ -0,0 +1,48 @@ +--- +stage: Anti-Abuse +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 +--- + +# Moderate users **(FREE)** + +> [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](../admin_area/moderate_users.md). + +A group Owner can moderate user access by banning and unbanning users. + +## Unban a user + +To unban a user with the GraphQL API, see [`Mutation.namespaceBanDestroy`](../../api/graphql/reference/index.md#mutationnamespacebandestroy). + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo on unbanning a user at the group level, see [Namespace level ban - Unbanning a user](https://www.youtube.com/watch?v=mTQVbP3MQrs). + +Prerequisites: + +- In the top-level group, you must have the Owner role. + +To unban a user: + +1. Go to the top-level group. +1. On the left sidebar, select **Group information > Members**. +1. Select the **Banned** tab. +1. For the account you want to unban, select **Unban**. + +## Ban a user + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo on banning a user at the group level, see [Namespace level ban - Banning a user](https://youtu.be/1rbi1uEJmOI). + +Prerequisites: + +- In the top-level group, you must have the Owner role. +- In the top-level group, if the user you want to ban has the Owner role, you must [demote the user](manage.md#change-the-owner-of-a-group). + +To manually ban a user: + +1. Go to the top-level group. +1. On the left sidebar, select **Group information > Members**. +1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**). +1. From the dropdown list, select **Ban member**. diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index d96f950edcd..d5c44f4e245 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -13,7 +13,7 @@ On self-managed GitLab, by default this feature is not available. To make it ava This is the group-level documentation. For self-managed instances, see the [administration documentation](../../admin_area/reporting/git_abuse_rate_limit.md). -Git abuse rate limiting is a feature to automatically [ban users](#unban-a-user) who download or clone 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 a [personal](../../../user/profile/personal_access_tokens.md) or [group access token](../../../user/group/settings/group_access_tokens.md). Access to unrelated groups is unaffected. +Git abuse rate limiting is a feature to automatically ban users who download, clone, 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 a [personal](../../../user/profile/personal_access_tokens.md) or [group access token](../../../user/group/settings/group_access_tokens.md). Access to unrelated groups is unaffected. Git abuse rate limiting does not apply to top-level group owners, [deploy tokens](../../../user/project/deploy_tokens/index.md), or [deploy keys](../../../user/project/deploy_keys/index.md). @@ -36,26 +36,6 @@ If automatic banning is enabled, an email notification is sent when a user is ab 1. Optional. Turn on the **Automatically ban users from this namespace when they exceed the specified limits** toggle to enable automatic banning. 1. Select **Save changes**. -## Unban a user +## Related topics -Prerequisites: - -- You must have the Owner role. - -1. On the left sidebar, select **Group information > Members**. -1. Select the **Banned** tab. -1. For the account you want to unban, select **Unban**. - -## Ban a user - -> [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. - -Prerequisites: - -- You must have the Owner role. - -To manually ban a user: - -1. On the left sidebar, select **Group information > Members**. -1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**). -1. From the dropdown list, select **Ban member**. +- [Ban and unban users](../moderate_users.md). diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index edb3e1b5079..c2a4d8175b3 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -42,7 +42,7 @@ To see the latest code coverage for each project in your group: 1. In the **Latest test coverage results** section, from the **Select projects** dropdown list, choose the projects you want to check. You can download code coverage data for specific projects using -[code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). +[code coverage history](../../../ci/testing/code_coverage.md#view-history-of-project-code-coverage). ## Download historic test coverage data diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index 7778648e985..0121df4fdb3 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -58,6 +58,8 @@ Attribute mapping: NOTE: Using the **Group ID** source attribute requires users to enter the group ID or object ID when configuring SAML group links. If available, use the **sAMAccountName** source attribute for the friendly group name instead. +[Azure AD limits the number of groups that can be sent in a SAML response to 150](https://support.esri.com/en/technical-article/000022190). If a user is a member of more than 150 groups, Azure does not include that user's group claim in the SAML response. + ## Google Workspace Basic SAML app configuration: diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 7c9b6effc43..ee59eeb98db 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -134,7 +134,7 @@ To enable global group memberships lock: After a group sync, users who are not members of a mapped SAML group are removed from the group. On GitLab.com, users in the top-level group are assigned the -[default membership role](index.md#role) instead of being removed. +default membership role instead of being removed. For example, in the following diagram: diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 04dfdbc6892..a54b3fea53e 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -18,41 +18,25 @@ Users can sign in to GitLab through their SAML identity provider. You can configure SAML SSO for the top-level group only. -## Configure your identity provider - -1. Find the information in GitLab required for configuration: - 1. On the top bar, select **Main menu > Groups** and find your group. - 1. On the left sidebar, select **Settings > SAML SSO**. - 1. Note the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. -1. Configure your SAML identity provider app using the noted details. - Alternatively, GitLab provides a [metadata XML configuration](#set-up-identity-provider-using-metadata). - See [specific identity provider documentation](#set-up-identity-provider) for more details. -1. Configure the SAML response to include a [NameID](#nameid) that uniquely identifies each user. -1. Configure the required [user attributes](#user-attributes), ensuring you include the user's email address. -1. While the default is enabled for most SAML providers, ensure the app is set to have service provider - initiated calls to link existing GitLab accounts. -1. Once the identity provider is set up, move on to [configuring GitLab](#configure-gitlab). - - - -If your account is the only owner in the group after SAML is set up, you can't unlink the account. To [unlink the account](#unlinking-accounts), -set up another user as a group owner. - -## Set up identity provider +## Set up your identity provider The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab. -When [configuring your identity provider](#configure-your-identity-provider), consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. +When setting up your identity provider, use the following provider-specific documentation +to help avoid common issues and as a guide for terminology used. -For providers not listed below, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#configure-saml-on-your-idp) -for additional guidance on information your identity provider may require. +For identity providers not listed, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#configure-saml-on-your-idp) +for additional guidance on information your provider may require. GitLab provides the following information for guidance only. If you have any questions on configuring the SAML app, contact your provider's support. -### Set up Azure +If you are having issues setting up your identity provider, see the +[troubleshooting documentation](#troubleshooting). -To set up SSO with Azure as your identification provider: +### Azure + +To set up SSO with Azure as your identity provider: 1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. @@ -69,28 +53,35 @@ To set up SSO with Azure as your identification provider: 1. You should set the following attributes: - **Unique User Identifier (Name identifier)** to `user.objectID`. - - **nameid-format** to `persistent`. + - **nameid-format** to `persistent`. For more information, see how to [manage user SAML identity](#manage-user-saml-identity). - **Additional claims** to [supported attributes](#user-attributes). -1. Optional. If you use [Group Sync](#group-sync), customize the name of the +1. Make sure the identity provider is set to have provider-initiated calls + to link existing GitLab accounts. + +1. Optional. If you use [Group Sync](group_sync.md), customize the name of the group claim to match the required attribute. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> View a demo of [SCIM provisioning on Azure using SAML SSO for groups](https://youtu.be/24-ZxmTeEBU). The `objectID` mapping is outdated in this video. Follow the [SCIM documentation](scim_setup.md#configure-azure-active-directory) instead. -View an [example configuration page](example_saml_config.md#azure-active-directory). +For more information, see an [example configuration page](example_saml_config.md#azure-active-directory). + +### Google Workspace -### Set up Google Workspace +To set up Google Workspace as your identity provider: -1. [Set up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en). - The following GitLab settings correspond to the Google Workspace fields. +1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > SAML SSO**. +1. Note the information on this page. +1. Follow the instructions for [setting up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en). The following GitLab settings correspond to the Google Workspace fields. - | GitLab setting | Google Workspace field | - |:-------------------------------------|:-----------------------| - | Identifier | **Entity ID** | - | Assertion consumer service URL | **ACS URL** | - | GitLab single sign-on URL | **Start URL** | - | Identity provider single sign-on URL | **SSO URL** | + | GitLab setting | Google Workspace field | + |:-----------------------------------------|:-----------------------| + | **Identifier** | **Entity ID** | + | **Assertion consumer service URL** | **ACS URL** | + | **GitLab single sign-on URL** | **Start URL** | + | **Identity provider single sign-on URL** | **SSO URL** | 1. Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab to [configure SAML](#configure-gitlab): @@ -102,62 +93,88 @@ View an [example configuration page](example_saml_config.md#azure-active-directo ``` 1. Set these values: - - For **Primary email**: `email` - - For **First name**: `first_name` - - For **Last name**: `last_name` - - For **Name ID format**: `EMAIL` - - For **NameID**: `Basic Information > Primary email` + - For **Primary email**: `email`. + - For **First name**: `first_name`. + - For **Last name**: `last_name`. + - For **Name ID format**: `EMAIL`. + - For **NameID**: `Basic Information > Primary email`. + For more information, see [manage user SAML identity](#manage-user-saml-identity). + +1. Make sure the identity provider is set to have provider-initiated calls + to link existing GitLab accounts. On the GitLab SAML SSO page, when you select **Verify SAML Configuration**, disregard the warning that recommends setting the **NameID** format to `persistent`. -For details, see the [example configuration page](example_saml_config.md#google-workspace). - -### Set up Okta +For more information, see an [example configuration page](example_saml_config.md#google-workspace). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ). +View a demo of [how to configure SAML with Google Workspaces and set up Group Sync](https://youtu.be/NKs0FSQVfCY). + +### Okta + +To set up SSO with Okta as your identity provider: + +1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > SAML SSO**. +1. Note the information on this page. +1. Follow the instructions for [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/). -1. [Set up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/). The following GitLab settings correspond to the Okta fields. - | GitLab setting | Okta field | - | ------------------------------------ | ---------------------------------------------------------- | - | Identifier | **Audience URI** | - | Assertion consumer service URL | **Single sign-on URL** | - | GitLab single sign-on URL | **Login page URL** (under **Application Login Page** settings) | - | Identity provider single sign-on URL | **Identity Provider Single Sign-On URL** | + | GitLab setting | Okta field | + | ---------------------------------------- | -------------------------------------------------------------- | + | **Identifier** | **Audience URI** | + | **Assertion consumer service URL** | **Single sign-on URL** | + | **GitLab single sign-on URL** | **Login page URL** (under **Application Login Page** settings) | + | **Identity provider single sign-on URL** | **Identity Provider Single Sign-On URL** | 1. Under the Okta **Single sign-on URL** field, select the **Use this for Recipient URL and Destination URL** checkbox. 1. Set these values: - - For **Application username (NameID)**: **Custom** `user.getInternalProperty("id")` - - For **Name ID Format**: `Persistent` + - For **Application username (NameID)**: **Custom** `user.getInternalProperty("id")`. + - For **Name ID Format**: `Persistent`. For more information, see [manage user SAML identity](#manage-user-saml-identity). + +1. Make sure the identity provider is set to have provider-initiated calls + to link existing GitLab accounts. The Okta GitLab application available in the App Catalog only supports [SCIM](scim_setup.md). Support for SAML is proposed in [issue 216173](https://gitlab.com/gitlab-org/gitlab/-/issues/216173). -### Set up OneLogin +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ). + +For more information, see an [example configuration page](example_saml_config.md#okta) + +### OneLogin OneLogin supports its own [GitLab (SaaS) application](https://onelogin.service-now.com/support?id=kb_article&sys_id=92e4160adbf16cd0ca1c400e0b961923&kb_category=50984e84db738300d5505eea4b961913). +To set up OneLogin as your identity provider: + +1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > SAML SSO**. +1. Note the information on this page. 1. If you use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), you should [use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f). The following GitLab settings correspond to the OneLogin fields: - | GitLab setting | OneLogin field | - | ------------------------------------------------ | -------------------------------- | - | Identifier | **Audience** | - | Assertion consumer service URL | **Recipient** | - | Assertion consumer service URL | **ACS (Consumer) URL** | - | Assertion consumer service URL (escaped version) | **ACS (Consumer) URL Validator** | - | GitLab single sign-on URL | **Login URL** | - | Identity provider single sign-on URL | **SAML 2.0 Endpoint** | + | GitLab setting | OneLogin field | + | ---------------------------------------------------- | -------------------------------- | + | **Identifier** | **Audience** | + | **Assertion consumer service URL** | **Recipient** | + | **Assertion consumer service URL** | **ACS (Consumer) URL** | + | **Assertion consumer service URL (escaped version)** | **ACS (Consumer) URL Validator** | + | **GitLab single sign-on URL** | **Login URL** | + | **Identity provider single sign-on URL** | **SAML 2.0 Endpoint** | -1. For **NameID**, use `OneLogin ID`. +1. For **NameID**, use `OneLogin ID`. For more information, see [manage user SAML identity](#manage-user-saml-identity). -### Set up identity provider using metadata +1. Make sure the identity provider is set to have provider-initiated calls + to link existing GitLab accounts. + +### Use metadata To configure some identity providers, you need a GitLab metadata URL. To find this URL: @@ -169,38 +186,32 @@ To find this URL: Check your identity provider's documentation to see if it supports the GitLab metadata URL. -### NameID +### Manage the identity provider -GitLab.com uses the SAML NameID to identify users. The NameID element: +After you have set up your identity provider, you can: -- Is a required field in the SAML response. -- Must be unique to each user. -- Must be a persistent value that never changes, such as a randomly generated unique user ID. -- Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. -- Should not be an email address or username. We strongly recommend against these as it's hard to - guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are - also case-insensitive, which can result in users being unable to sign in. +- Change the identity provider. +- Change email domains. -The relevant field name and recommended value for supported providers are in the [provider specific notes](#set-up-identity-provider). +#### Change the identity provider -WARNING: -Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` breaks the configuration and potentially locks users out of the GitLab group. +You can change to a different identity provider. During the change process, +users cannot access any of the SAML groups. To mitigate this, you can disable +[SSO enforcement](#sso-enforcement). -#### NameID Format +To change identity providers: -We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format. -Most NameID formats can be used, except `Transient` due to the temporary nature of this format. +1. [Configure](#set-up-your-identity-provider) the group with the new identity provider. +1. Optional. If the **NameID** is not identical, [change the **NameID** for users](#manage-user-saml-identity). -### User attributes +#### Change email domains -To create users with the correct information for improved [user access and management](#user-access-and-management), -the user's details must be passed to GitLab as attributes in the SAML assertion. At a minimum, the user's email address -must be specified as an attribute named `email` or `mail`. +To migrate users to a new email domain, tell users to: -You can configure the following attributes with GitLab.com Group SAML: +1. Add their new email as the primary email to their accounts and verify it. +1. Optional. Remove their old email from the account. -- `username` or `nickname`. We recommend you configure only one of these. -- The [attributes available](../../../integration/saml.md#configure-assertions) to self-managed GitLab instances. +If the **NameID** is configured with the email address, [change the **NameID** for users](#manage-user-saml-identity). ## Configure GitLab @@ -208,139 +219,25 @@ After you set up your identity provider to work with GitLab, you must configure 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. -1. Find the SSO URL from your identity provider and enter it the **Identity provider single sign-on URL** field. -1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. -1. Select the access level to be applied to newly added users in the **Default membership role** field. The default access level is 'Guest'. +1. Complete the fields: + - 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**. + To do so, [configure the SAML SSO for the group](#configure-gitlab). That role + becomes the starting role of all users added to the group. 1. Select the **Enable SAML authentication for this group** checkbox. -1. Select the **Save changes** button. - - +1. Optional. Select: + - **Enforce SSO-only authentication for web activity for this group**. + - **Enforce SSO-only authentication for Git activity for this group**. + For more information, see the [SSO enforcement documentation](#sso-enforcement). +1. Select **Save changes**. NOTE: -The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#set-up-google-workspace)), use a secure signature algorithm. - -### Additional configuration information - -Many SAML terms can vary between providers. It is possible that the information you are looking for is listed under another name. - -For more information, start with your identity provider's documentation. Look for their options and examples to see how they configure SAML. This can provide hints on what you need to configure GitLab to work with these providers. - -It can also help to look at our [more detailed docs for self-managed GitLab](../../../integration/saml.md). -SAML configuration for GitLab.com is mostly the same as for self-managed instances. -However, self-managed GitLab instances use a configuration file that supports more options as described in the external [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml/). -Internally that uses the [`ruby-saml` library](https://github.com/onelogin/ruby-saml), so we sometimes check there to verify low level details of less commonly used options. +The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace)), use a secure signature algorithm. -It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/fixtures/saml/response.xml). - -### SSO enforcement - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) in GitLab 15.8 by enabling transparent SSO by default on GitLab.com. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389562) in GitLab 15.10. Feature flag `transparent_sso_enforcement` removed. - -On GitLab.com, SSO is enforced: - -- When SAML SSO is enabled. -- For users with an existing SAML identity when accessing groups and projects in the organization's - group hierarchy. Users can view other groups and projects as well as their user settings without SSO sign in by using their GitLab.com credentials. - -A user has a SAML identity if one or both of the following are true: - -- They have signed in to GitLab by using their GitLab group's single sign-on URL. -- They were provisioned by SCIM. - -Users are not prompted to sign in through SSO on each visit. GitLab checks -whether a user has authenticated through SSO. If the user last signed in more -than 24 hours ago, GitLab prompts the user to sign in again through SSO. - -SSO is enforced as follows: - -| Project/Group visibility | Enforce SSO setting | Member with identity | Member without identity | Non-member or not signed in | -|--------------------------|---------------------|--------------------| ------ |------------------------------| -| Private | Off | Enforced | Not enforced | No access | -| Private | On | Enforced | Enforced | No access | -| Public | Off | Enforced | Not enforced | Not enforced | -| Public | On | Enforced | Enforced | Not enforced | - -An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. - -#### SSO-only for web activity enforcement - -When the **Enforce SSO-only authentication for web activity for this group** option is enabled: - -- All users must access GitLab by using their GitLab group's single sign-on URL - to access group resources, regardless of whether they have an existing SAML - identity. -- SSO is enforced when users access groups and projects in the organization's - group hierarchy. Users can view other groups and projects without SSO sign in. -- Users cannot be added as new members manually. -- Users with the Owner role can use the standard sign in process to make - necessary changes to top-level group settings. - -SSO enforcement for web activity has the following effects when enabled: - -- For groups, users cannot share a project in the group outside the top-level - group, even if the project is forked. -- Git activity originating from CI/CD jobs do not have the SSO check enforced. -- Credentials that are not tied to regular users (for example, project and group - access tokens, and deploy keys) do not have the SSO check enforced. -- Users must be signed-in through SSO before they can pull images using the - [Dependency Proxy](../../packages/dependency_proxy/index.md). -- When the **Enforce SSO-only authentication for Git and Dependency Proxy - activity for this group** option is enabled, any API endpoint that involves - Git activity is under SSO enforcement. For example, creating or deleting a - branch, commit, or tag. For Git activity over SSH and HTTPS, users must - have at least one active session signed-in through SSO before they can push to or - pull from a GitLab repository. - -When SSO for web activity is enforced, non-SSO group members do not lose access -immediately. If the user: - -- Has an active session, they can continue accessing the group for up to 24 - hours until the identity provider session times out. -- Is signed out, they cannot access the group after being removed from the - identity provider. - -### Change the SAML app - -After you have configured your identity provider, you can: - -- Change the identity provider users sign in with. -- Migrate to a different identity provider. -- Change email domains. - -### Change the identity provider - -To change the identity provider: - -- If the `NameID` is not identical in the existing and new identity providers, [change the NameID for users](#change-nameid-for-one-or-more-users). -- If the `NameID` is identical, users do not have to make any changes. - -### Migrate to a different identity provider - -You can migrate to a different identity provider. During the migration process, -users cannot access any of the SAML groups. To mitigate this, you can disable -[SSO enforcement](#sso-enforcement). - -To migrate identity providers: - -1. [Configure](#configure-your-identity-provider) the group with the new identity provider. -1. [Change the NameID for users](#change-nameid-for-one-or-more-users). - -### Change email domains - -To migrate users to a new email domain, tell users to: - -1. Add their new email as the primary email to their accounts and verify it. -1. Optional. Remove their old email from the account. - -If the NameID is configured with the email address, [change the NameID for users](#change-nameid-for-one-or-more-users). +If you are having issues configuring GitLab, see the [troubleshooting documentation](#troubleshooting). ## User access and management @@ -358,54 +255,108 @@ When a user tries to sign in with Group SSO, GitLab attempts to find or create a - Create a new account with another email address. - Sign-in to their existing account to link the SAML identity. -### Linking SAML to your existing GitLab.com account +### User attributes + +You can pass user information to GitLab as attributes in the SAML assertion. + +- The user's email address can be an **email** or **mail** attribute. +- The username can be either a **username** or **nickname** attribute. You should specify only + one of these. + +For more information, see the [attributes available for self-managed GitLab instances](../../../integration/saml.md#configure-assertions). + +### Link SAML to your existing GitLab.com account > **Remember me** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121569) in GitLab 15.7. To link SAML to your existing GitLab.com account: -1. Sign in to your GitLab.com account. [Reset your password](https://gitlab.com/users/password/new) if necessary. -1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the identity provider. -1. Optional. Select the **Remember me** checkbox to stay signed in to GitLab for 2 weeks. You may still be asked to re-authenticate with your SAML provider - more frequently. +1. Sign in to your GitLab.com account. [Reset your password](https://gitlab.com/users/password/new) + if necessary. +1. Locate and visit the **GitLab single sign-on URL** for the group you're signing + in to. A group owner can find this on the group's **Settings > SAML SSO** page. + If the sign-in URL is configured, users can connect to the GitLab app from the identity provider. +1. Optional. Select the **Remember me** checkbox to stay signed in to GitLab for 2 weeks. + You may still be asked to re-authenticate with your SAML provider more frequently. 1. Select **Authorize**. 1. Enter your credentials on the identity provider if prompted. -1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. +1. You are then redirected back to GitLab.com and should now have access to the group. + In the future, you can use SAML to sign in to GitLab.com. + +If a user is already a member of the group, linking the SAML identity does not +change their role. -On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider. +On subsequent visits, you should be able to [sign in to GitLab.com with SAML](#sign-in-to-gitlabcom-with-saml) +or by visiting links directly. If the **enforce SSO** option is turned on, you +are then redirected to sign in through the identity provider. -### Signing in to GitLab.com with SAML +### Sign in to GitLab.com with SAML 1. Sign in to your identity provider. 1. From the list of apps, select the "GitLab.com" app. (The name is set by the administrator of the identity provider.) 1. You are then signed in to GitLab.com and redirected to the group. -### Change NameID for one or more users +### Manage user SAML identity > Update of SAML identities using the SAML API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5. -Group owners can update the SAML identities for their group members using the [SAML API](../../../api/saml.md#update-extern_uid-field-for-a-saml-identity). +GitLab.com uses the SAML **NameID** to identify users. The **NameID** is: + +- A required field in the SAML response. +- Case sensitive. + +The **NameID** must: + +- Be unique to each user. +- Be a persistent value that never changes, such as a randomly generated unique user ID. +- Match exactly on subsequent sign-in attempts, so it should not rely on user input + that could change between upper and lower case. + +The **NameID** should not be an email address or username because: + +- Email addresses and usernames are more likely to change over time. For example, + when a person's name changes. +- Email addresses are case-insensitive, which can result in users being unable to + sign in. + +The **NameID** format must be `Persistent`, unless you are using a field, like email, that +requires a different format. You can use any format except `Transient`. + +#### Change user **NameID** + +Group owners can use the [SAML API](../../../api/saml.md#update-extern_uid-field-for-a-saml-identity) to change their group members' **NameID** and update their SAML identities . + If [SCIM](scim_setup.md) is configured, group owners can update the SCIM identities using the [SCIM API](../../../api/scim.md#update-extern_uid-field-for-a-scim-identity). Alternatively, ask the users to reconnect their SAML account. -1. Ask relevant users to [unlink their account from the group](#unlinking-accounts). -1. Ask relevant users to [link their account to the new SAML app](#linking-saml-to-your-existing-gitlabcom-account). +1. Ask relevant users to [unlink their account from the group](#unlink-accounts). +1. Ask relevant users to [link their account to the new SAML app](#link-saml-to-your-existing-gitlabcom-account). + +WARNING: +After users have signed into GitLab using SSO SAML, changing the **NameID** value +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 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. GitLab allows setting certain user attributes based on values from the SAML response. -Existing users will have these attributes updated if the user was originally -provisioned by the group. Users are provisioned by the group when the account was -created via [SCIM](scim_setup.md) or by first sign-in with SAML SSO for GitLab.com groups. +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. #### 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 the user can create new groups. Default is `true`. -- `projects_limit` - The total number of personal projects a user can create. +- **projects_limit** - The total number of personal projects a user can create. A value of `0` means the user cannot create new projects in their personal namespace. Default is `10000`. @@ -451,35 +402,25 @@ bypassed for users: - That are provisioned with SAML or SCIM. - That have an email address that belongs to the verified domain. -### Role - -Starting from [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523), group owners can set a -"Default membership role" other than Guest. To do so, [configure the SAML SSO for the group](#configure-gitlab). -That role becomes the starting access level of all users added to the group. - -Existing members with appropriate privileges can promote or demote users, as needed. - -If a user is already a member of the group, linking the SAML identity does not change their role. - -Users given a "minimal access" role have [specific restrictions](../../permissions.md#users-with-minimal-access). - -### Blocking access +### Block user access To rescind a user's access to the group when only SAML SSO is configured, either: - Remove (in order) the user from: 1. The user data store on the identity provider or the list of users on the specific app. 1. The GitLab.com group. -- Use [Group Sync](group_sync.md#automatic-member-removal) at the top-level of your group with the [default role](#role) set to [minimal access](../../permissions.md#users-with-minimal-access) to automatically block access to all resources within the group. Users may continue to [use a seat](../../permissions.md#minimal-access-users-take-license-seats). +- Use [Group Sync](group_sync.md#automatic-member-removal) at the top-level of + your group with the default role set to [minimal access](../../permissions.md#users-with-minimal-access) + to automatically block access to all resources in the group. To rescind a user's access to the group when also using SCIM, refer to [Remove access](scim_setup.md#remove-access). -### Unlinking accounts +### Unlink accounts Users can unlink SAML for a group from their profile page. This can be helpful if: - You no longer want a group to be able to sign you in to GitLab.com. -- Your SAML NameID has changed and so GitLab can no longer find your user. +- Your SAML **NameID** has changed and so GitLab can no longer find your user. WARNING: Unlinking an account removes all roles assigned to that user in the group. @@ -496,25 +437,106 @@ For example, to unlink the `MyOrg` account: 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Disconnect** next to the connected account. -## Group Sync +## SSO enforcement + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) in GitLab 15.8 by enabling transparent SSO by default on GitLab.com. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389562) in GitLab 15.10. Feature flag `transparent_sso_enforcement` removed. + +On GitLab.com, SSO is enforced: -For information on automatically managing GitLab group membership, see [SAML Group Sync](group_sync.md). +- When SAML SSO is enabled. +- For users with an existing SAML identity when accessing groups and projects in the organization's + group hierarchy. Users can view other groups and projects as well as their user settings without SSO sign in by using their GitLab.com credentials. + +A user has a SAML identity if one or both of the following are true: -## Passwords for users created via SAML SSO for Groups +- They have signed in to GitLab by using their GitLab group's single sign-on URL. +- They were provisioned by SCIM. -The [Generated passwords for users created through integrated authentication](../../../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via SAML SSO for Groups. +Users are not prompted to sign in through SSO on each visit. GitLab checks +whether a user has authenticated through SSO. If the user last signed in more +than 24 hours ago, GitLab prompts the user to sign in again through SSO. -## Related topics +SSO is enforced as follows: + +| Project/Group visibility | Enforce SSO setting | Member with identity | Member without identity | Non-member or not signed in | +|--------------------------|---------------------|----------------------|-------------------------|-----------------------------| +| Private | Off | Enforced | Not enforced | Not enforced | +| Private | On | Enforced | Enforced | Enforced | +| Public | Off | Enforced | Not enforced | Not enforced | +| Public | On | Enforced | Enforced | Not enforced | + +An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. + +### SSO-only for web activity enforcement + +When the **Enforce SSO-only authentication for web activity for this group** option is enabled: + +- All members must access GitLab by using their GitLab group's single sign-on URL + to access group resources, regardless of whether they have an existing SAML + identity. +- SSO is enforced when users access groups and projects in the organization's + group hierarchy. Users can view other groups and projects without SSO sign in. +- Users cannot be added as new members manually. +- Users with the Owner role can use the standard sign in process to make + necessary changes to top-level group settings. +- For non-members or users who are not signed in: + - SSO is not enforced when they access public group resources. + - SSO is enforced when they access private group resources. + +SSO enforcement for web activity has the following effects when enabled: -For more information on: +- For groups, users cannot share a project in the group outside the top-level + group, even if the project is forked. +- Git activity originating from CI/CD jobs do not have the SSO check enforced. +- Credentials that are not tied to regular users (for example, project and group + access tokens, and deploy keys) do not have the SSO check enforced. +- Users must be signed-in through SSO before they can pull images using the + [Dependency Proxy](../../packages/dependency_proxy/index.md). +- When the **Enforce SSO-only authentication for Git and Dependency Proxy + activity for this group** option is enabled, any API endpoint that involves + Git activity is under SSO enforcement. For example, creating or deleting a + branch, commit, or tag. For Git activity over SSH and HTTPS, users must + have at least one active session signed-in through SSO before they can push to or + pull from a GitLab repository. + +When SSO for web activity is enforced, non-SSO group members do not lose access +immediately. If the user: + +- Has an active session, they can continue accessing the group for up to 24 + hours until the identity provider session times out. +- Is signed out, they cannot access the group after being removed from the + identity provider. + +## Related topics -- Setting up SAML on self-managed GitLab instances, see - [SAML SSO for self-managed GitLab instances](../../../integration/saml.md). -- Commonly-used terms, see the - [glossary of common terms](../../../integration/saml.md#glossary-of-common-terms). -- The differences between SaaS and self-managed authentication and authorization, - see the [SaaS vs. Self-Managed comparison](../../../administration/auth/index.md#saas-vs-self-managed-comparison). +- [SAML SSO for self-managed GitLab instances](../../../integration/saml.md) +- [Glossary](../../../integration/saml.md#glossary) +- [Authentication comparison between SaaS and self-managed](../../../administration/auth/index.md#saas-vs-self-managed-comparison) +- [Passwords for users created through integrated authentication](../../../security/passwords_for_integrated_authentication_methods.md) +- [SAML Group Sync](group_sync.md) ## Troubleshooting -See our [troubleshooting SAML guide](troubleshooting.md). +If you find it difficult to match the different SAML terms between GitLab and the +identity provider: + +1. Check your identity provider's documentation. Look at their example SAML + configurations for information on the terms they use. +1. Check the [SAML SSO for self-managed GitLab instances documentation](../../../integration/saml.md). + The self-managed GitLab instance SAML configuration file supports more options + than the GitLab.com file. You can find information on the self-managed instance + file in the: + - External [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml/). + - [`ruby-saml` library](https://github.com/onelogin/ruby-saml). +1. Compare the XML response from your provider with our + [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/fixtures/saml/response.xml). + +For other troubleshooting information, see the [troubleshooting SAML guide](troubleshooting.md). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index a61615104c1..38a1c4125aa 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -116,7 +116,7 @@ For each attribute: 1. Select the required settings. 1. Select **Ok**. -If your SAML configuration differs from [the recommended SAML settings](index.md#set-up-azure), select the mapping +If your SAML configuration differs from [the recommended SAML settings](index.md#azure), select the mapping attributes and modify them accordingly. In particular, the `objectId` source attribute must map to the `externalId` target attribute. @@ -133,7 +133,7 @@ Prerequisites: product tier is required to use SCIM on Okta. - [GitLab is configured](#configure-gitlab). - SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) set up as - described in the [Okta setup notes](index.md#set-up-okta). + described in the [Okta setup notes](index.md#okta). - Your Okta SAML setup matches the [configuration steps exactly](index.md), especially the NameID configuration. To configure Okta for SCIM: @@ -214,7 +214,7 @@ To link your SCIM and SAML identities: 1. Update the [primary email](../../profile/index.md#change-your-primary-email) address in your GitLab.com user account to match the user profile email address in your identity provider. -1. [Link your SAML identity](index.md#linking-saml-to-your-existing-gitlabcom-account). +1. [Link your SAML identity](index.md#link-saml-to-your-existing-gitlabcom-account). ### Remove access diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index eadf385feb3..62c13e8909b 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -167,7 +167,7 @@ you must set `attribute_statements` in the SAML configuration to This error suggests you are signed in as a GitLab user but have already linked your SAML identity to a different GitLab user. Sign out and then try to sign in again using SAML, which should log you into GitLab with the linked user account. -If you do not wish to use that GitLab user with the SAML login, you can [unlink the GitLab account from the SAML app](index.md#unlinking-accounts). +If you do not wish to use that GitLab user with the SAML login, you can [unlink the GitLab account from the SAML app](index.md#unlink-accounts). ### Message: "SAML authentication failed: User has already been taken" @@ -176,7 +176,7 @@ Here are possible causes and solutions: | Cause | Solution | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](index.md#unlinking-accounts) from this GitLab account before attempting to sign in again. | +| You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](index.md#unlink-accounts) from this GitLab account before attempting to sign in again. | | The `NameID` changes every time the user requests SSO identification | [Check the `NameID`](#verify-nameid) is not set with `Transient` format, or the `NameID` is not changing on subsequent requests.| ### Message: "SAML authentication failed: Email has already been taken" @@ -196,7 +196,7 @@ User accounts are created in one of the following ways: Getting both of these errors at the same time suggests the `NameID` capitalization provided by the identity provider didn't exactly match the previous value for that user. -This can be prevented by configuring the `NameID` to return a consistent value. Fixing this for an individual user involves changing the identifier for the user. For GitLab.com, the user needs to [unlink their SAML from the GitLab account](index.md#unlinking-accounts). +This can be prevented by configuring the `NameID` to return a consistent value. Fixing this for an individual user involves changing the identifier for the user. For GitLab.com, the user needs to [unlink their SAML from the GitLab account](index.md#unlink-accounts). ### Message: "Request to link SAML account must be authorized" @@ -209,7 +209,7 @@ initiated by the service provider and not only the identity provider. ### Message: "There is already a GitLab account associated with this email address. Sign in with your existing credentials to connect your organization's account" **(PREMIUM SAAS)** -A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account). +A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account). To resolve this problem, the user should check they are using the correct GitLab password to sign in. The user first needs to [reset their password](https://gitlab.com/users/password/new) if both: @@ -233,7 +233,7 @@ This can then be compared to the `NameID` being sent by the identity provider by Ensure that the **GitLab single sign-on URL** (for GitLab.com) or the instance URL (for self-managed) has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app. -For GitLab.com, alternatively, when users need to [link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account), provide the **GitLab single sign-on URL** and instruct users not to use the SAML app on first sign in. +For GitLab.com, alternatively, when users need to [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account), provide the **GitLab single sign-on URL** and instruct users not to use the SAML app on first sign in. ### Users receive a 404 **(PREMIUM SAAS)** @@ -244,8 +244,8 @@ If all users are receiving a `404` when attempting to sign in using SAML, confir If you receive a `404` during setup when using "verify configuration", make sure you have used the correct [SHA-1 generated fingerprint](../../../integration/saml.md#configure-saml-on-your-idp). -If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](index.md#configure-your-identity-provider), they may see a 404. -As outlined in the [user access section](index.md#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. +If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](index.md#set-up-your-identity-provider), they may see a 404. +As outlined in the [user access section](index.md#link-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. If all users are receiving a `404` after signing in to the identity provider (IdP): @@ -317,4 +317,4 @@ This error appears when you try to invite a user to a GitLab.com group (or subgr If you see this message after trying to invite a user to a group: 1. Ensure the user has been [added to the SAML identity provider](index.md#user-access-and-management). -1. Ask the user to [link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account), if they have one. Otherwise, ask the user to create a GitLab.com account by [accessing GitLab.com through the identity provider's dashboard](index.md#user-access-and-management), or by [signing up manually](https://gitlab.com/users/sign_up) and linking SAML to their new account. +1. Ask the user to [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account), if they have one. Otherwise, ask the user to create a GitLab.com account by [accessing GitLab.com through the identity provider's dashboard](index.md#user-access-and-management), or by [signing up manually](https://gitlab.com/users/sign_up) and linking SAML to their new account. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 57d4fd513ff..a1eead1563f 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -5,13 +5,9 @@ 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 --- -# Value stream analytics for groups **(PREMIUM)** +# Value stream analytics **(FREE)** -Value stream analytics measures the time it takes to go from an idea to production. It also helps businesses: - -- Visualize their end-to-end DevSecOps workstreams. -- Identify and solve inefficiencies. -- Optimize their workstreams to deliver more value, faster. +Value stream analytics measures the time it takes to go from an idea to production. A **value stream** is the entire work process that delivers value to customers. For example, the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts @@ -25,11 +21,81 @@ Use value stream analytics to identify: - Long-running issues or merge requests. - Factors that cause your software development lifecycle to slow down. -Value stream analytics is also available for [projects](../../analytics/value_stream_analytics.md). +Value stream analytics helps businesses: + +- Visualize their end-to-end DevSecOps workstreams. +- Identify and solve inefficiencies. +- Optimize their workstreams to deliver more value, faster. + +Value stream analytics is available for projects and groups. + +## Feature availability + +Value stream analytics offers different features at the project and group level for FOSS and licensed versions. + +- On GitLab Free, value stream analytics does not aggregate data. It queries the database directly where the date range filter is applied to the creation date of issues and merge request. You can view value stream analytics with pre-defined default stages. +- On GitLab Premium, value stream analytics aggregates data and applies the date range filter on the end event. You can also create, edit, and delete value streams. + +|Feature|Group level (licensed)|Project level (licensed)|Project level (FOSS)| +|-|-|-|-| +|Create custom value streams|Yes|Yes|no, only one value stream (default) is present with the default stages| +|Create custom stages|Yes|Yes|No| +|Filtering (for example, by author, label, milestone)|Yes|Yes|Yes| +|Stage time chart|Yes|Yes|No| +|Total time chart|Yes|Yes|No| +|Task by type chart|Yes|No|No| +|DORA Metrics|Yes|Yes|No| +|Cycle time and lead time summary (Key metrics)|Yes|Yes|No| +|New issues, commits, and deploys (Key metrics)|Yes, excluding commits|Yes|Yes| +|Uses aggregated backend|Yes|Yes|No| +|Date filter behavior|Filters items [finished within the date range](https://gitlab.com/groups/gitlab-org/-/epics/6046)|Filters items by creation date.|Filters items by creation date.| +|Authorization|At least reporter|At least reporter|Can be public| ## How value stream analytics works -### How value stream analytics aggregates data +Value stream analytics calculates the duration of every stage of your software development process. + +Value stream analytics is made of three core objects: + +- A **value stream** contains a value stream stage list. +- Each value stream stage list contains one or more **stages**. +- Each stage has two **events**: start and stop. + +### Value stream stages + +A stage represents an event pair (start and end events) with additional metadata, such as the name of the stage. You can configure the stages in the pairing rules defined in the backend. + +### Value streams + +Value streams are container objects for the stages. You can have multiple value streams per group, to focus on different aspects of the DevOps lifecycle. + +### Value stream stage events + +Events are the smallest building blocks of the value stream analytics feature. A stage consists of a start event and an end event. + +The following stage events are available: + +- Issue closed +- Issue created +- Issue first added to board +- Issue first associated with milestone +- Issue first mentioned +- Issue label added +- Issue label removed +- MR closed +- MR merged +- MR created +- MR first commit time +- MR first deployed +- MR label added +- MR label removed +- MR last pipeline duration + +These events play a key role in the duration calculation, which is calculated by the formula: duration = end event time - start event time. + +To learn what start and end events can be paired, see [Validating start and end events](../../../development/value_stream_analytics.md#validating-start-and-end-events). + +### How value stream analytics aggregates data **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335391) in GitLab 14.5. > - Filter by stop date toggle [added](https://gitlab.com/gitlab-org/gitlab/-/issues/352428) in GitLab 14.9 @@ -133,12 +199,14 @@ You can change the name of a project environment in your GitLab CI/CD configurat Prerequisites: -- You must have at least the Reporter role to view value stream analytics for groups. -- You must create a [custom value stream](#create-a-value-stream-with-gitlab-default-stages). Value stream analytics only shows custom value streams created for your group. +- You must have at least the Reporter role. +- You must create a [custom value stream](#create-a-value-stream-with-gitlab-default-stages). Value stream analytics only shows custom value streams created for your group or project. -To view value stream analytics for your group: +To view value stream analytics for your group or project: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. 1. To view metrics for a particular stage, select a stage below the **Filter results** text box. 1. Optional. Filter the results: @@ -166,30 +234,11 @@ The table shows a list of related workflow items for the selected stage. Based o > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in GitLab 13.12. -The **Overview** page in value stream analytics shows key metrics and DORA metrics of group performance. Based on the filter you select, -the dashboard automatically aggregates DORA metrics and displays the current status of the value stream. Select a DORA metric to view its chart. - -Prerequisite: - -- To view deployment metrics, you must have a -[production environment configured](#how-value-stream-analytics-identifies-the-production-environment). - -To view the DORA metrics and key metrics: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. -Key metrics and DORA metrics display below the **Filter results** text box. +The **Overview** page in value stream analytics displays key metrics and DORA metrics of group performance. ### Key metrics -The **Overview** page shows the following key metrics that measure team performance: +Value stream analytics includes the following key metrics: - **Lead time**: Median time from when the issue was created to when it was closed. - **Cycle time**: Median time from first commit to issue closed. GitLab measures cycle time from the earliest commit of a @@ -205,20 +254,49 @@ The **Overview** page shows the following key metrics that measure team performa > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355304) time to restore service tile in GitLab 15.0. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357071) change failure rate tile in GitLab 15.0. -The value stream analytics **Overview** dashboard displays the following [DORA](../../../user/analytics/dora_metrics.md) metrics: +Value stream analytics includes the following [DORA](../../../user/analytics/dora_metrics.md) metrics: -- Deployment Frequency. -- Lead time for changes. -- Time to restore service. -- Change failure rate. +- Deployment frequency +- Lead time for changes +- Time to restore service +- Change failure rate DORA metrics are calculated based on data from the [DORA API](../../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). +If you have a GitLab Premium or Ultimate subscription: + +- The number of successful deployments is calculated with DORA data. +- The data is filtered based on environment and environment tier. + NOTE: In GitLab 13.9 and later, deployment frequency metrics are calculated based on when the deployment was finished. In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on when the deployment was created. +## View key and DORA metrics + +Prerequisite: + +- To view deployment metrics, you must have a +[production environment configured](#how-value-stream-analytics-identifies-the-production-environment). + +To view the DORA metrics and key metrics: + +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. + Key metrics and DORA metrics display below the **Filter results** text box. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + Based on the filter you select, the dashboard automatically aggregates DORA metrics and displays the status of the value stream. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. +1. Select a DORA metric to view its chart. + ## View metrics for each development stage > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. @@ -228,7 +306,9 @@ Value stream analytics shows the median time spent by issues or merge requests i To view the median time spent in each stage by a group: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -243,7 +323,24 @@ NOTE: The date range selector filters items by the event time. The event time is when the selected stage finished for the given item. -## Create a value stream +## View tasks by type **(PREMIUM)** + +The **Tasks by type** chart displays the cumulative number of issues and merge requests per day for your group. + +The chart uses the global page filters to display data based on the selected +group and time frame. + +To view tasks by type: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Below the **Filter results** text box, select **Overview**. The **Tasks by type** chart displays below the **Total time** chart. +1. To switch between the task type, select the **Settings** (**{settings}**) dropdown list + and select **Issues** or **Merge Requests**. +1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list + and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels. + +## Create a value stream **(PREMIUM)** ### Create a value stream with GitLab default stages @@ -252,7 +349,9 @@ selected stage finished for the given item. When you create a value stream, you can use GitLab default stages and hide or re-order them. You can also create custom stages in addition to those provided in the default template. -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. Select **Create new Value Stream**. 1. Enter a name for the value stream. @@ -276,7 +375,9 @@ If you have recently upgraded to GitLab Premium, it can take up to 30 minutes fo When you create a value stream, you can create and add custom stages that align with your own development workflows. -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. Select **Create value stream**. 1. For each stage: @@ -304,13 +405,15 @@ In the example above, two independent value streams are set up for two teams tha The first value stream uses standard timestamp-based events for defining the stages. The second value stream uses label events. -## Edit a value stream +## Edit a value stream **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267537) in GitLab 13.10. After you create a value stream, you can customize it to suit your purposes. To edit a value stream: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. In the upper-right corner, select the dropdown list, then select a value stream. 1. Next to the value stream dropdown list, select **Edit**. @@ -323,21 +426,22 @@ After you create a value stream, you can customize it to suit your purposes. To 1. Optional. To undo any modifications, select **Restore value stream defaults**. 1. Select **Save Value Stream**. -## Delete a value stream +## Delete a value stream **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. To delete a custom value stream: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Value Stream**. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. 1. In the upper-right corner, select the dropdown list, then select the value stream you would like to delete. 1. Select **Delete (name of value stream)**. 1. To confirm, select **Delete**.  -## View number of days for a cycle to complete +## View number of days for a cycle to complete **(PREMIUM)** > - Chart median line [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. > - Totals [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) with averages in GitLab 13.12. @@ -345,7 +449,9 @@ To delete a custom value stream: The **Total time chart** shows the average number of days it takes for development cycles to complete. The chart shows data for the last 500 workflow items. -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. 1. Above the **Filter results** box, select a stage: - To view a summary of the cycle time for all stages, select **Overview**. @@ -358,23 +464,42 @@ The chart shows data for the last 500 workflow items. - In the **From** field, select a start date. - In the **To** field, select an end date. -## View tasks by type +## Access permissions for value stream analytics -The **Tasks by type** chart displays the cumulative number of issues and merge requests per day for your group. +Access permissions for value stream analytics depend on the project type. -The chart uses the global page filters to display data based on the selected -group, projects, and time frame. +| Project type | Permissions | +|--------------|----------------------------------------| +| Public | Anyone can access. | +| Internal | Any authenticated user can access. | +| Private | Any member Guest and above can access. | -To view tasks by type: +## Troubleshooting -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. -1. Below the **Filter results** text box, select **Overview**. The **Tasks by type** chart displays below the **Total time** chart. -1. To switch between the task type, select the **Settings** (**{settings}**) dropdown list - and select **Issues** or **Merge Requests**. -1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list - and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels. +### 100% CPU utilization by Sidekiq `cronjob:analytics_cycle_analytics` -## Troubleshooting +It is possible that value stream analytics background jobs +strongly impact performance by monopolizing CPU resources. + +To recover from this situation: + +1. Disable the feature for all projects in [the Rails console](../../../administration/operations/rails_console.md), + and remove existing jobs: + + ```ruby + Project.find_each do |p| + p.analytics_access_level='disabled'; + p.save! + end + + Analytics::CycleAnalytics::GroupStage.delete_all + Analytics::CycleAnalytics::Aggregation.delete_all + ``` -See [Value stream analytics for projects](../../analytics/value_stream_analytics.md#troubleshooting). +1. Configure a [Sidekiq routing](../../../administration/sidekiq/processing_specific_job_classes.md) + with for example a single `feature_category=value_stream_management` + and multiple `feature_category!=value_stream_management` entries. + Find other relevant queue metadata in the + [Enterprise Edition list](../../../administration/sidekiq/processing_specific_job_classes.md#list-of-available-job-classes). +1. Enable value stream analytics for one project after another. + You might need to tweak the Sidekiq routing further according to your performance requirements. diff --git a/doc/user/img/observability_copy_shortened_link.png b/doc/user/img/observability_copy_shortened_link.png Binary files differdeleted file mode 100644 index 217e56972cc..00000000000 --- a/doc/user/img/observability_copy_shortened_link.png +++ /dev/null diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 655bc774477..b571a65b50a 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index 569f876f36c..45445c0a0f5 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index befd793c949..4516ea538a9 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index ecfd086d254..c8d2fb674b2 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index 6bd44c7a0f7..50185966267 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index 9f56b92dabc..d0419e08f95 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md index f522cb5bff6..620430a449a 100644 --- a/doc/user/infrastructure/clusters/manage/clusters_health.md +++ b/doc/user/infrastructure/clusters/manage/clusters_health.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- 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 8b75d54d352..f07b70dd8e0 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- 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 14d3a7996e0..1d56e7c1ba1 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- 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 c2190ad7cfa..bbf8391e8a0 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index b2b5da61a81..a21c7271e7a 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md index 8be949c40cd..d5376bfbcb1 100644 --- a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md +++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index f9891934067..d4fc345f494 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -100,7 +100,7 @@ For GitLab-curated template recipes, see [Terraform template recipes](terraform_ ## Related topics - View [the images that contain the `gitlab-terraform` shell script](https://gitlab.com/gitlab-org/terraform-images). -- Use GitLab as a [Terraform module registry](../../packages/terraform_module_registry/index.md). +- Use GitLab as a [Terraform Module Registry](../../packages/terraform_module_registry/index.md). - To store state files in local storage or in a remote store, use the [GitLab-managed Terraform state](terraform_state.md). - To collaborate on Terraform code changes and Infrastructure-as-Code workflows, use the [Terraform integration in merge requests](mr_integration.md). diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 7b4a7cd6b95..b2e02cd7375 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 62772c5b379..7b95a7267af 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -1,16 +1,14 @@ --- -stage: Configure -group: Configure +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 --- # GitLab-managed Terraform state **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. -> - Support for state names that contain periods introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. Disabled by default. [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106861) in GitLab 15.7. - -FLAG: -On self-managed GitLab, by default support for state names that contain periods is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. On GitLab.com, support for state names that contain periods is available. Requests for state files might generate HTTP 404 errors after enabling this feature. For more information, see [Troubleshooting the Terraform integration with GitLab](troubleshooting.md#state-not-found-if-the-state-name-contains-a-period). +> - Support for state names that contain periods introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. Disabled by default. +> - Support for state names that contain periods [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385597) in GitLab 16.0. Feature flag `allow_dots_on_tf_state_names` removed. Terraform uses state files to store details about your infrastructure configuration. With Terraform remote [backends](https://www.terraform.io/language/settings/backends/configuration), @@ -338,6 +336,5 @@ You can also use [the GraphQL API](../../../api/graphql/reference/index.md#mutat ## Related topics -- [Troubleshooting GitLab-managed Terraform state](troubleshooting.md). -- To use GitLab and Terraform to deploy an AWS EC2 instance in a custom VPC, - see [this sample project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws). +- [Troubleshooting GitLab-managed Terraform state](troubleshooting.md) +- [Sample project: Terraform deployment of AWS EC2 instance in a custom VPC](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index a79f2758441..0011e7c9242 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index 2aa1e5d3284..d770c0111d0 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -160,12 +160,3 @@ If your `TF_HTTP_ADDRESS`, `TF_HTTP_LOCK_ADDRESS` and `TF_HTTP_UNLOCK_ADDRESS` a to update the state names there. Alternatively, you can [migrate your terraform state](terraform_state.md#migrate-to-a-gitlab-managed-terraform-state). - -#### Self-managed GitLab instances - -By default, support for state names with periods is not enabled on self-managed GitLab. -You can enable it from the Rails console: - -```ruby -Feature.enable(:allow_dots_on_tf_state_names) -``` diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 87633932e0d..d60f20a3713 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 30432b8b492..fd48e7244d6 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -211,27 +211,44 @@ For more information, see the [Kroki integration](../administration/integration/ [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emojis). -```markdown -Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +::Tabs -:zap: You can use emoji anywhere GitLab Flavored Markdown is supported. :v: +:::TabTitle Rendered Markdown -You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People :heart: you for that. +<!-- vale gitlab.Markdown_emoji = NO --> -If you're new to this, don't be :fearful:. You can join the emoji :family:. Just look up one of the supported codes. +Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":monkey:" alt=":monkey:"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/star2.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":star2:" alt=":star2:"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":speech_balloon:" alt=":speech_balloon:">. Well we have a gift for you: -Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. :thumbsup: -``` +<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/zap.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":zap:" alt=":zap:">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/v.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":v:" alt=":v:"> + +You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/bug.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":bug:" alt=":bug:"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":speak_no_evil:" alt=":speak_no_evil:"> patches. If someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/snail.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":snail:" alt=":snail:"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/birthday.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":birthday:" alt=":birthday:">. People <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/heart.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":heart:" alt=":heart:"> you for that. + +If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/fearful.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":fearful:" alt=":fearful:">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/family.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":family:" alt=":family:">. Just look up one of the supported codes. + +Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":thumbsup:" alt=":thumbsup:"> + +<!-- vale gitlab.Markdown_emoji = YES --> -Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/star2.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you: +:::TabTitle Code -<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> +```markdown +Sometimes you want to :monkey: around a bit and add some :star2: to your +:speech_balloon:. Well we have a gift for you: + +:zap: You can use emoji anywhere GitLab Flavored Markdown is supported. :v: -You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/bug.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> patches. If someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/snail.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/birthday.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. People <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that. +You can use it to point out a :bug: or warn about :speak_no_evil: patches. +And if someone improves your really :snail: code, send them some :birthday:. +People :heart: you for that. -If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/fearful.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/family.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Just look up one of the supported codes. +If you're new to this, don't be :fearful:. You can join the emoji :family:. +Just look up one of the supported codes. -Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> +Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) +for a list of all supported emoji codes. :thumbsup: +``` + +::EndTabs #### Emojis and your operating system @@ -249,6 +266,8 @@ this font installed by default. <!-- vale gitlab.Spelling = YES --> +To learn more about adding custom emojis, see [Custom emoji](award_emojis.md#custom-emojis). + ### Front matter Front matter is metadata included at the beginning of a Markdown document, preceding @@ -362,6 +381,10 @@ _KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX. This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). +To prevent malicious activity, GitLab renders only the first 50 inline math instances. +The number of math blocks is also limited based on render time. If the limit is exceeded, +GitLab renders the excess math instances as text. + Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) is rendered inline with the text. @@ -371,15 +394,15 @@ the language declared as `math` is rendered on a separate line: ````markdown This math is inline: $`a^2+b^2=c^2`$. -This math is on a separate line: +This math is on a separate line using a ```` ```math ```` block: ```math a^2+b^2=c^2 ``` -This math is on a separate line: $$a^2+b^2=c^2$$ +This math is on a separate line using inline `$$`: $$a^2+b^2=c^2$$ -This math is on a separate line: +This math is on a separate line using a `$$...$$` block: $$ a^2+b^2=c^2 @@ -388,23 +411,15 @@ $$ This math is inline: $`a^2+b^2=c^2`$. -This math is on a separate line: +This math is on a separate line using a ```` ```math ```` block: ```math a^2+b^2=c^2 ``` -This math is on a separate line: $$a^2+b^2=c^2$$ +This math is on a separate line using inline `$$`: $$a^2+b^2=c^2$$ -This math is on a separate line: - -$$ -a^2+b^2=c^2 -$$ - -This math is on a separate line: $$a^2+b^2=c^2$$ - -This math is on a separate line: +This math is on a separate line using a `$$...$$` block: $$ a^2+b^2=c^2 @@ -736,13 +751,17 @@ you can quote that without having to manually prepend `>` to every line! ``` ->>> -If you paste a message from somewhere else - -that spans multiple lines, +<!-- +Use a standard blockquote here until https://gitlab.com/gitlab-org/gitlab/-/issues/390290 +gets properly fixed. The mixture of HTML comments and HTML tags +trigger this problem. +--> -you can quote that without having to manually prepend `>` to every line! ->>> +> If you paste a message from somewhere else +> +> that spans multiple lines, +> +> you can quote that without having to manually prepend `>` to every line! ### Code spans and blocks @@ -807,7 +826,7 @@ Tildes are OK too. If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). -GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax +GitLab uses the [Rouge Ruby library](https://github.com/rouge-ruby/rouge) for more colorful syntax highlighting in code blocks. For a list of supported languages visit the [Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers). Syntax highlighting is supported only in code blocks, so you can't highlight inline code. diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 7025dc916ac..a61c395ab00 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -8,8 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default. -WARNING: -OKRs are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). +OKRs are an [Experiment](../policy/alpha-beta-support.md#experiment). For the OKR feature roadmap, see [epic 7864](https://gitlab.com/groups/gitlab-org/-/epics/7864). FLAG: @@ -17,7 +16,7 @@ On self-managed GitLab, by default this feature is not available. To make it ava On GitLab.com, this feature is not available. The feature is not ready for production use. -[Objectives and key results](https:://en.wikipedia.org/wiki/OKR) (OKRs) are a framework for setting +[Objectives and key results](https://en.wikipedia.org/wiki/OKR) (OKRs) are a framework for setting and tracking goals that are aligned with your organization's overall strategy and vision. The objective and the key result in GitLab share many features. In the documentation, the term @@ -119,7 +118,6 @@ To edit an OKR: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) to feature flag named `work_items_mvc` in GitLab 15.8. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.10. > - Changing activity sort order [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.8. > - Filtering activity [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389971) in GitLab 15.10. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.10. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 493771fa30a..d013e2813f7 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- 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 9419451fd5d..f873453e049 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -21,7 +21,7 @@ The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage u This page includes the Container Registry usage, which is only available on GitLab.com. Measuring usage is only possible on the new version of the GitLab Container Registry backed by a metadata database. Support for improvements is proposed in epic [5523](https://gitlab.com/groups/gitlab-org/-/epics/5523). -You cannot use the Container Registry in self-managed instances, but epic [5521](https://gitlab.com/groups/gitlab-org/-/epics/5521) proposes to change this behavior. +On self-managed instances, you cannot use the Container Registry with a metadata database. For the plan to change this behavior, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). Image layers stored in the Container Registry are deduplicated at the root namespace level. @@ -112,6 +112,43 @@ to work with all third-party registries in the same predictable way. If you use Registry, this workaround is not required because we implemented a special tag delete operation. In this case, you can expect cleanup policies to be consistent and predictable. +#### Example cleanup policy workflow + +The interaction between the keep and remove rules for the cleanup policy can be complex. +For example, with a project with this cleanup policy configuration: + +- **Keep the most recent**: 1 tag per image name. +- **Keep tags matching**: `production-.*` +- **Remove tags older than**: 7 days. +- **Remove tags matching**: `.*`. + +And a container repository with these tags: + +- `latest`, published 2 hours ago. +- `production-v44`, published 3 days ago. +- `production-v43`, published 6 days ago. +- `production-v42`, published 11 days ago. +- `dev-v44`, published 2 days ago. +- `dev-v43`, published 5 day ago. +- `dev-v42`, published 10 days ago. +- `v44`, published yesterday. +- `v43`, published 12 days ago. +- `v42`, published 20 days ago. + +In this example, the tags that would be deleted in the next cleanup run are `dev-v42`, `v43`, and `v42`. +You can interpret the rules as applying with this precedence: + +1. The keep rules have highest precedence. Tags must be kept when they match **any** rule. + - The `latest` tag must be kept, because `latest` tags are always kept. + - The `production-v44`, `production-v43`, and `production-v42` tags must be kept, + because they match the **Keep tags matching** rule. + - The `v44` tag must be kept because it's the most recent, matching the **Keep the most recent** rule. +1. The remove rules have lower precedence, and tags are only deleted if **all** rules match. + For the tags not matching any keep rules (`dev-44`, `dev-v43`, `dev-v42`, `v43`, and `v42`): + - `dev-44` and `dev-43` do **not** match the **Remove tags older than**, and are kept. + - `dev-v42`, `v43`, and `v42` match both **Remove tags older than** and **Remove tags matching** + rules, so these three tags can be deleted. + ### Create a cleanup policy You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. @@ -119,8 +156,8 @@ You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the To create a cleanup policy in the UI: 1. For your project, go to **Settings > Packages and registries**. -1. Expand the **Clean up image tags** section. -1. Complete the fields. +1. In the **Cleanup policies** section, select **Set cleanup rules**. +1. Complete the fields: | Field | Description | |----------------------------|-------------------------------------------------| diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 05574c54112..5ce65bfd8aa 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -98,8 +98,11 @@ with one of the following: ## Create a Distribution -On the project-level, Debian packages are published using *Debian Distributions*. To publish -packages on the group level, create a distribution with the same `codename`. +At the project level, Debian packages are published with **Debian distributions**. At the +group level, Debian packages are aggregated from the projects in the group provided that: + +- The project visibility is set to `public`. +- The Debian `codename` for the group matches the Debian `codename` for the project. To create a project-level distribution using a personal access token: @@ -162,9 +165,9 @@ EOF dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes ``` -## Directly upload a package +## Upload a package with explicit distribution and component -> Direct upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9. +> Upload with explicit distribution and component [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9. When you don't have access to `.changes` file, you can directly upload a `.deb` by passing distribution `codename` and target `component` as parameters with @@ -173,7 +176,8 @@ For example, to upload to component `main` of distribution `sid` using a persona ```shell curl --request PUT --user "<username>:<personal_access_token>" \ - "https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian/?distribution=sid&component=main" \ + --get --data "distribution=sid" --data "component=main" \ + "https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian/" \ --upload-file /path/to/your.deb ``` diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 8dc3c98795b..d7cf33cc2a4 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -342,13 +342,21 @@ Authenticating with credentials from job payload (GitLab Registry) Make sure you are using the expected authentication mechanism. -### "Not Found" error when pulling image +### `Not Found` or `404` error when pulling image -Docker errors similar to the following may indicate that the user running the build job doesn't have -a minimum of the Guest role in the specified Dependency Proxy group: +Errors like these might indicate that the user running the job doesn't have +a minimum of the Guest role in the Dependency Proxy group: -```plaintext -ERROR: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: not found +- ```plaintext + ERROR: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: not found -failed to solve with frontend dockerfile.v0: failed to create LLB definition: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: not found -``` + failed to solve with frontend dockerfile.v0: failed to create LLB definition: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: not found + ``` + +- ```plaintext + ERROR: Job failed: failed to pull image "gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest" with specified policies [always]: + Error response from daemon: error parsing HTTP 404 response body: unexpected end of JSON input: "" (manager.go:237:1s) + ``` + +For more information about the work to improve the error messages in similar cases to `Access denied`, +see [issue 354826](https://gitlab.com/gitlab-org/gitlab/-/issues/354826). diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 932de0bcde6..bad099e6733 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -22,6 +22,8 @@ do not support the other available mechanisms. The `user-id` is not checked and may be any value, and the `password` must be either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md). +Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. + ## Publish a package file When you publish a package file, if the package does not exist, it is created. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 7418977e0d1..2084de58bdb 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -14,15 +14,9 @@ packages, which can be easily consumed as a dependency in downstream projects. 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. -## Infrastructure Registry +## Terraform Module Registry -The GitLab [Infrastructure Registry](infrastructure_registry/index.md) is a secure and private registry for infrastructure packages. You can use GitLab CI/CD to create and publish infrastructure packages. - -The Infrastructure Registry supports the following formats: - -| Package type | GitLab version | -| ------------ | -------------- | -| [Terraform Module](terraform_module_registry/index.md) | 14.0+ | +The GitLab [Terraform Module Registry](terraform_module_registry/index.md) is a secure and private registry for Terraform modules. You can use GitLab CI/CD to create and publish modules. ## Dependency Proxy diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index d06c5e7fb1e..8c1e8a2ad8a 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -1,102 +1,11 @@ --- -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 +redirect_to: '../terraform_module_registry/index.md' +remove_date: '2023-06-13' --- -# Infrastructure Registry **(FREE)** +This document was moved to [another location](../terraform_module_registry/index.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. - -With the GitLab Infrastructure Registry, you can use GitLab projects as a -private registry for infrastructure packages. You can create and publish -packages with GitLab CI/CD, which can then be consumed from other private -projects. - -## View packages - -To view packages within your project: - -1. Go to the project. -1. Go to **Packages and registries > Infrastructure Registry**. - -You can search, sort, and filter packages on this page. - -For information on how to create and upload a package, view the GitLab -documentation for your package type: - -- [Terraform modules](../terraform_module_registry/index.md) - -## Use GitLab CI/CD to build packages - -To use [GitLab CI/CD](../../../ci/index.md) to build packages, you can -authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables/predefined_variables.md). - -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 CI/CD to build Terraform modules, -see [Publish a Terraform module by using CI/CD](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd). - -If you use CI/CD to build a package, you can find extended activity information -when you view the package details: - - - -You can see the pipeline that published the package as well as the commit and the user who triggered it. However, the history is limited to five updates per package. - -## Download a package - -To download a package: - -1. Go to **Packages and registries > Infrastructure Registry**. -1. Select the name of the package you want to download. -1. In the **Activity** section, select the name of the package you want to download. - -## Delete a package - -You cannot edit a package after you publish it in the Infrastructure Registry. Instead, you -must delete and recreate it. - -To delete a package, you must have suitable [permissions](../../permissions.md). - -You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. - -To delete a package in the UI, from your project: - -1. Go to **Packages and registries > Infrastructure Registry**. -1. Find the name of the package you want to delete. -1. Select **Delete**. - -The package is permanently deleted. - -## Disable the Infrastructure Registry - -The Infrastructure Registry is automatically enabled. - -For self-managed instances, a GitLab administrator can -[disable](../../../administration/packages/index.md) **Packages and registries**, -which removes this menu item from the sidebar. - -You can also remove the Infrastructure Registry for a specific project: - -1. In your project, go to **Settings > General**. -1. Expand the **Visibility, project features, permissions** section and toggle **Packages** off (in gray). -1. Select **Save changes**. - -To enable it back, follow the same steps above and toggle it on (in blue). - -## How module resolution works - -When you upload a new module, GitLab generates a path for the module, for example, `https://gitlab.example.com/parent-group/my-infra-package`. - -- This path conforms with [the Terraform spec](https://www.terraform.io/internals/module-registry-protocol). -- The name of the path must be unique within the namespace. - -For projects in subgroups, GitLab checks that the module name does not already exist anywhere in the namespace, including all subgroups and the parent group. - -For example, if: - -- The project is `gitlab.example.com/parent-group/sub-group/my-project`. -- The infrastructure package is `my-infra-package`. - -The project name must be unique in all projects in all groups under `parent-group`. +<!-- This redirect file can be deleted after <2023-06-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 (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/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 1899cdc213f..7a451ca283f 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -22,6 +22,8 @@ You need an token to publish a package. There are different tokens available dep Create a token and save it to use later in the process. +Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. + ### Edit the `settings.xml` Add the following section to your @@ -64,6 +66,13 @@ The three endpoints are: - **Group-level**: Use when you want to install packages from many different projects in the same GitLab group. GitLab does not guarantee the uniqueness of package names within the group. You can have two projects with the same package name and package version. As a result, GitLab serves whichever one is more recent. - **Instance-level**: Use when you have many packages in different GitLab groups or in their own namespace. +For the instance-level endpoint, ensure the relevant section of your `pom.xml` in Maven looks like this: + +```xml + <groupId>group-slug.subgroup-slug</groupId> + <artifactId>project-slug</artifactId> +``` + **Only packages that have the same path as the project** are exposed by the instance-level endpoint. | Project | Package | Instance-level endpoint available | diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 6ce4aab930e..52fdda0d523 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -23,6 +23,8 @@ You need an token to publish a package. There are different tokens available dep Create a token and save it to use later in the process. +Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. + ### Naming convention Depending on how the package is installed, you may need to adhere to the naming convention. @@ -122,21 +124,50 @@ You can install a package from a GitLab project or instance: - **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. - **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -### Install from the instance level +### Authenticate to the Package Registry -WARNING: -To install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). +You must authenticate to the Package Registry to install a package from a private project. +No authentication is needed if the project is public. -1. Authenticate to the Package Registry +To authenticate with `npm`: - If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. +```shell +npm config set -- //your_domain_name/:_authToken=your_token +``` - ```shell - npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token - ``` +With npm version 7 or earlier, use the full URL to the endpoint. - - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. - - Replace `your_token` with a deploy token, group access token, project access token, or personal access token. +If you're installing: + +- From the instance level: + + ```shell + npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token + ``` + + From the project level: + + ```shell + npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token + ``` + +In these examples: + +- Replace `your_domain_name` with your domain name, for example, `gitlab.com`. +- Replace `your_project_id` is your project ID, found on the project's home page. +- Replace `your_token` with a deploy token, group access token, project access token, or personal access token. + +NOTE: +Starting with npm version 8, you can [use a URI fragment instead of a full URL](https://docs.npmjs.com/cli/v8/configuring-npm/npmrc?v=true#auth-related-configuration) +in the `_authToken` parameter. However, [group-level endpoints](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) +are not supported. + +### Install from the instance level + +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. Set the registry @@ -156,17 +187,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 - - If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. - - ```shell - npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token - ``` - - - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. - - Replace `your_project_id` is your project ID, found on the project's home page. - - Replace `your_token` with a deploy token, group access token, project access token, or personal access token. +1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -184,6 +205,39 @@ To install a package from the instance level, the package must have been publish npm install @scope/my-package ``` +## Deprecate a package + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396763) in GitLab 16.0. + +You can deprecate a package so that a deprecation warning displays when the package is fetched. + +Pre-requisites: + +- The same [permissions](../../permissions.md) as deleting a package. +- [Authenticated to the package registry](#authentication-to-the-package-registry). + +From the command line, run: + +```shell +npm deprecate @scope/package "Deprecation message" +``` + +The CLI also accepts version ranges for `@scope/package`. For example: + +```shell +npm deprecate @scope/package "All package versions are deprecated" +npm deprecate @scope/package@1.0.1 "Only version 1.0.1 is deprecated" +npm deprecate @scope/package@"< 1.0.5" "All package versions less than 1.0.5 are deprecated" +``` + +### Remove deprecation warning + +To remove a package's deprecation warning, specify `""` (an empty string) for the message. For example: + +```shell +npm deprecate @scope/package "" +``` + ## Helpful hints ### Package forwarding to npmjs.com @@ -272,6 +326,8 @@ The GitLab npm repository supports the following commands for the npm CLI (`npm` - `npm dist-tag rm`: Delete a dist-tag. - `npm ci`: Install npm packages directly from your `package-lock.json` file. - `npm view`: Show package metadata. +- `npm pack`: Create a tarball from a package. +- `npm deprecate`: Deprecate a version of a package. ## Troubleshooting diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 4595e0eebb9..c97ce9ec593 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -39,6 +39,8 @@ Some features such as [publishing](#publish-a-nuget-package) a package are only 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. To work around this limitation, set up [authentication](#add-the-package-registry-as-a-source-for-nuget-packages). diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index cd60a229479..eb3fd082d33 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -71,9 +71,13 @@ NOTE: If you have not activated the "Package registry" feature for your project at **Settings > General > Visibility, project features, permissions**, you receive a 403 Forbidden response. Accessing package registry via deploy token is not available when external authorization is enabled. -## Use GitLab CI/CD to build packages +## Use GitLab CI/CD + +You can use [GitLab CI/CD](../../../ci/index.md) to build or import packages into +a package registry. + +### To build packages -You can use [GitLab CI/CD](../../../ci/index.md) to build packages. For Maven, NuGet, npm, Conan, Helm, and PyPI packages, and Composer dependencies, you can authenticate with GitLab by using the `CI_JOB_TOKEN`. @@ -97,6 +101,16 @@ when you view the package details: You can view which pipeline published the package, and the commit and user who triggered it. However, the history is limited to five updates of a given package. +### To import packages + +If you already have packages built in a different registry, you can import them +into your GitLab package registry with the [Packages Importer](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer) + +The Packages Importer runs a CI/CD pipeline that [can import these package types](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer#formats-supported): + +- NPM +- NuGet + ## Reduce storage usage For information on reducing your storage use for the Package Registry, see diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index 0c7813beae0..0f359c70525 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -35,7 +35,7 @@ Packages can be pulled from your project, group, or instance. | Package type | Project | Group | Instance | |-----------------------------------------------------|---------|-------|----------| | [Maven](../maven_repository/index.md) | Y | Y | Y | -| [npm](../npm_registry/index.md) | Y | Y | Y | +| [npm](../npm_registry/index.md) | Y | N | Y | | [NuGet](../nuget_repository/index.md) | Y | Y | N | | [PyPI](../pypi_repository/index.md) | Y | Y | N | | [Generic packages](../generic_packages/index.md) | Y | N | N | diff --git a/doc/user/packages/package_registry/supported_package_managers.md b/doc/user/packages/package_registry/supported_package_managers.md index 75b8c95a0fa..0c33bef5e1c 100644 --- a/doc/user/packages/package_registry/supported_package_managers.md +++ b/doc/user/packages/package_registry/supported_package_managers.md @@ -11,24 +11,20 @@ Not all package manager formats are ready for production use. The Package Registry supports the following package manager types: -| Package type | GitLab version | Status | -| ------------------------------------------------ | -------------- | ---------------------------------------------------------- | -| [Maven](../maven_repository/index.md) | 11.3+ | GA | -| [npm](../npm_registry/index.md) | 11.7+ | GA | -| [NuGet](../nuget_repository/index.md) | 12.8+ | GA | -| [PyPI](../pypi_repository/index.md) | 12.10+ | GA | -| [Generic packages](../generic_packages/index.md) | 13.5+ | GA | -| [Composer](../composer_repository/index.md) | 13.2+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6817) | -| [Conan](../conan_repository/index.md) | 12.6+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6816) | -| [Helm](../helm_repository/index.md) | 14.1+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6366) | -| [Debian](../debian_repository/index.md) | 14.2+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/6057) | -| [Go](../go_proxy/index.md) | 13.1+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3043) | -| [Ruby gems](../rubygems_registry/index.md) | 13.10+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3200) | +| Package type | GitLab version | Status | +| ------------------------------------------------ | -------------- | --------------------------------------------------------------- | +| [Maven](../maven_repository/index.md) | 11.3+ | GA | +| [npm](../npm_registry/index.md) | 11.7+ | GA | +| [NuGet](../nuget_repository/index.md) | 12.8+ | GA | +| [PyPI](../pypi_repository/index.md) | 12.10+ | GA | +| [Generic packages](../generic_packages/index.md) | 13.5+ | GA | +| [Composer](../composer_repository/index.md) | 13.2+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6817) | +| [Conan](../conan_repository/index.md) | 12.6+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6816) | +| [Helm](../helm_repository/index.md) | 14.1+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6366) | +| [Debian](../debian_repository/index.md) | 14.2+ | [Experiment](https://gitlab.com/groups/gitlab-org/-/epics/6057) | +| [Go](../go_proxy/index.md) | 13.1+ | [Experiment](https://gitlab.com/groups/gitlab-org/-/epics/3043) | +| [Ruby gems](../rubygems_registry/index.md) | 13.10+ | [Experiment](https://gitlab.com/groups/gitlab-org/-/epics/3200) | -[Status](../../../policy/alpha-beta-support.md): - -- Alpha: behind a feature flag and not officially supported. -- Beta: several known issues that may prevent expected use. -- GA (Generally Available): ready for production use at any scale. +[View what each status means](../../../policy/alpha-beta-support.md). 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 e5b7f06f6ca..d23966f26fe 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -34,6 +34,8 @@ To do this, you can use: `read_package_registry`, `write_package_registry`, or both. - A [CI job token](#authenticate-with-a-ci-job-token). +Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. + ### Authenticate with a personal access token To authenticate with a personal access token, edit the `~/.pypirc` file and add: diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 66a42f398b0..d7f33dd9e79 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -4,30 +4,53 @@ 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 --- -# Terraform module registry **(FREE)** +# Terraform Module Registry **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. +> - Infrastructure registry and Terraform Module Registry [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/404075) into a single Terraform Module Registry feature in GitLab 15.11. -Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab -as a Terraform module registry. +With the Terraform Module Registry, you can use GitLab projects as a +private registry for terraform modules. You can create and publish +modules with GitLab CI/CD, which can then be consumed from other private +projects. -## Authenticate to the Terraform module registry +## View Terraform modules -To authenticate to the Terraform module registry, you need either: +To view Terraform modules in your project: + +1. Go to the project. +1. On the left sidebar, select **Packages and registries > Terraform modules**. + +You can search, sort, and filter modules on this page. + +For information on how to create and upload a package, view the GitLab +documentation for your package type: + +- [Terraform modules](../terraform_module_registry/index.md) + +## Authenticate to the Terraform Module Registry + +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). -## Publish a Terraform Module +Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. -When you publish a Terraform Module, if it does not exist, it is created. +## Publish a Terraform module + +When you publish a Terraform module, if it does not exist, it is created. + +### Using the API + +You can publish Terraform modules by using the [Terraform Module Registry API](../../../api/packages/terraform-modules.md). Prerequisites: -- The package name and version [must be unique in the top-level namespace](../infrastructure_registry/index.md#how-module-resolution-works). +- The package name and version [must be unique in the top-level namespace](#how-module-resolution-works). - Your project and group names must not include a dot (`.`). For example, `source = "gitlab.example.com/my.group/project.name"`. - You must [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. -- The name of a module [must be unique within the scope of its group](../infrastructure_registry/index.md#how-module-resolution-works), otherwise an +- The name of a module [must be unique in the scope of its group](#how-module-resolution-works), otherwise an [error occurs](#troubleshooting). ```plaintext @@ -37,9 +60,9 @@ PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | -| `module-name` | string | yes | The package name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package name can't exceed 64 characters. -| `module-system` | string | yes | The package system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package system can't exceed 64 characters. More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). -| `module-version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). +| `module-name` | string | yes | The module name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The module name can't exceed 64 characters. +| `module-system` | string | yes | The module system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The module system can't exceed 64 characters. More information can be found in the [Terraform Module Registry protocol documentation](https://www.terraform.io/internals/module-registry-protocol). +| `module-version` | string | yes | The module version. It must be valid according to the [semantic versioning specification](https://semver.org/). Provide the file content in the request body. @@ -55,14 +78,6 @@ curl --fail-with-body --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file" ``` -Example response: - -```json -{ - "message":"201 Created" -} -``` - Example request using a deploy token: ```shell @@ -79,41 +94,13 @@ Example response: } ``` -## Reference a Terraform Module +### Using a CI/CD template (recommended) -Prerequisites: - -- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. - -Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: - -```plaintext -credentials "gitlab.com" { - token = "<TOKEN>" -} -``` - -Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance. - -You can then refer to your Terraform Module from a downstream Terraform project: - -```plaintext -module "<module>" { - source = "gitlab.com/<namespace>/<module-name>/<module-system>" -} -``` - -Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the Terraform module registry. - -## Publish a Terraform module by using CI/CD - -> CI/CD template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9. - -### Use a CI/CD template (recommended) +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9. You can use the [`Terraform-Module.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform-Module.gitlab-ci.yml) or the advanced [`Terraform/Module-Base.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Module-Base.gitlab-ci.yml) -CI/CD template to publish a Terraform module to the GitLab Terraform Registry: +CI/CD template to publish a Terraform module to the GitLab terraform registry: ```yaml include: @@ -124,7 +111,7 @@ The pipeline contains the following jobs: - `fmt` - Validate the formatting of the Terraform module. - `kics-iac-sast` - Test the Terraform module for security issues. -- `deploy` - For tag pipelines only. Deploy the Terraform module to the GitLab Terraform Registry. +- `deploy` - For tag pipelines only. Deploy the Terraform module to the Terraform Module Registry. #### Pipeline variables @@ -137,7 +124,7 @@ You can configure the pipeline with the following variables: | `TERRAFORM_MODULE_SYSTEM` | `local` | The system or provider of your Terraform module targets. For example, `local`, `aws`, `google`. | | `TERRAFORM_MODULE_VERSION` | `${CI_COMMIT_TAG}` | The Terraform module version. You should follow the semantic versioning specification. | -### Deploy manually via CI/CD +### Using CI/CD manually To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. @@ -166,14 +153,97 @@ upload: - if: $CI_COMMIT_TAG ``` -To trigger this upload job, add a Git tag to your commit. Ensure the tag follows the [Semantic Versioning Specification](https://semver.org/) that Terraform requires. The `rules:if: $CI_COMMIT_TAG` ensures that only tagged commits to your repository trigger the module upload job. +To trigger this upload job, add a Git tag to your commit. Ensure the tag follows the [Semantic versioning specification](https://semver.org/) that Terraform requires. The `rules:if: $CI_COMMIT_TAG` ensures that only tagged commits to your repository trigger the module upload job. For other ways to control jobs in your CI/CD pipeline, refer to the [`.gitlab-ci.yml`](../../../ci/yaml/index.md) keyword reference. +## Reference a Terraform module + +Prerequisites: + +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. + +Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: + +```terraform +credentials "gitlab.com" { + token = "<TOKEN>" +} +``` + +Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance. + +You can then refer to your Terraform module from a downstream Terraform project: + +```terraform +module "<module>" { + source = "gitlab.com/<namespace>/<module-name>/<module-system>" +} +``` + +Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the Terraform Module Registry. + +## Download a Terraform module + +To download a Terraform module: + +1. On the left sidebar, select **Packages and registries > Terraform modules**. +1. Select the name of the module you want to download. +1. In the **Activity** section, select the name of the module you want to download. + +## How module resolution works + +When you upload a new module, GitLab generates a path for the module, for example, `https://gitlab.example.com/parent-group/my-infra-package`. + +- This path conforms with [the Terraform spec](https://www.terraform.io/internals/module-registry-protocol). +- The name of the path must be unique in the namespace. + +For projects in subgroups, GitLab checks that the module name does not already exist anywhere in the namespace, including all subgroups and the parent group. + +For example, if: + +- The project is `gitlab.example.com/parent-group/sub-group/my-project`. +- The Terraform module is `my-infra-package`. + +The project name must be unique in all projects in all groups under `parent-group`. + +## Delete a Terraform module + +You cannot edit a Terraform module after you publish it in the Terraform Module Registry. Instead, you +must delete and recreate it. + +To delete a module, you must have suitable [permissions](../../permissions.md). + +You can delete modules by using [the packages API](../../../api/packages.md#delete-a-project-package) or the UI. + +To delete a module in the UI, from your project: + +1. On the left sidebar, select **Packages and registries > Terraform modules**. +1. Find the name of the package you want to delete. +1. Select **Delete**. + +The package is permanently deleted. + +## Disable the Terraform Module Registry + +The Terraform Module Registry is automatically enabled. + +For self-managed instances, a GitLab administrator can +[disable](../../../administration/packages/index.md) **Packages and registries**, +which removes this menu item from the sidebar. + +You can also remove the Terraform Module Registry for a specific project: + +1. In your project, go to **Settings > General**. +1. Expand the **Visibility, project features, permissions** section and toggle **Packages** off (in gray). +1. Select **Save changes**. + +To enable it back, follow the same steps above and toggle it on (in blue). + ## Example projects -For examples of the Terraform module registry, check the projects below: +For examples of the Terraform Module Registry, check the projects below: -- The [_GitLab local file_ project](https://gitlab.com/mattkasa/gitlab-local-file) creates a minimal Terraform module and uploads it into the Terraform module registry using GitLab CI/CD. +- The [_GitLab local file_ project](https://gitlab.com/mattkasa/gitlab-local-file) creates a minimal Terraform module and uploads it into the Terraform Module Registry using GitLab CI/CD. - The [_Terraform module test_ project](https://gitlab.com/mattkasa/terraform-module-test) uses the module from the previous example. ## Troubleshooting diff --git a/doc/user/packages/yarn_repository/index.md b/doc/user/packages/yarn_repository/index.md index e756a912928..c8f4985a518 100644 --- a/doc/user/packages/yarn_repository/index.md +++ b/doc/user/packages/yarn_repository/index.md @@ -302,10 +302,8 @@ Then you can use `yarn add` to install your packages. ## Related topics -- For full helpful hints information, see the - [npm documentation](../npm_registry/index.md#helpful-hints). -- For Yarn 1 to Yarn 2+ migration information see the - [Yarn Migration Guide](https://yarnpkg.com/getting-started/migration). +- [npm documentation](../npm_registry/index.md#helpful-hints) +- [Yarn Migration Guide](https://yarnpkg.com/getting-started/migration) ## Troubleshooting diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 43029e37047..e4a3f60834f 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -23,6 +23,7 @@ The available roles are: - Developer - Maintainer - Owner +- Minimal Access (available for the top-level group only) A user assigned the Guest role has the least permissions, and the Owner has the most. @@ -58,7 +59,7 @@ The following table lists project permissions available for each role: |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|----------| | [Analytics](analytics/index.md):<br>View [issue analytics](analytics/issue_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [value stream analytics](analytics/value_stream_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [value stream analytics](group/value_stream_analytics/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) | | ✓ | ✓ | ✓ | ✓ | @@ -137,7 +138,7 @@ The following table lists project permissions available for each role: | [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | | [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) | | | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Feature flags](../operations/feature_flags.md) | | | ✓ | ✓ | ✓ | | [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Download project | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -327,7 +328,7 @@ This table shows granted privileges for jobs triggered by specific types of user | Push source and LFS | | | | | 1. Only if the triggering user is not an external one. -1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). +1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). ## Group members permissions @@ -423,39 +424,38 @@ nested groups if you have membership in one of its parents. For more information, see [subgroup memberships](group/subgroups/index.md#subgroup-membership). -## Users with minimal access **(PREMIUM)** +## Users with Minimal Access **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in GitLab 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in GitLab 13.4. +> - Support for inviting users with Minimal Access role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106438) in GitLab 15.9. -Owners can add members with a "minimal access" role to a root group. Such users don't automatically have access to -projects and subgroups underneath. Owners must explicitly add these "minimal access" users to the specific subgroups and +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. + +Owners must explicitly add these users to the specific subgroups and projects. -You can use minimal access to give the same member more than one role in a group: +You can use the Minimal Access role to give the same member more than one role in a group: -1. Add the member to the root group with a minimal access role. +1. Add the member to the root group with a Minimal Access role. 1. Invite the member as a direct member with a specific role in any subgroup or project in that group. -Because of an [outstanding issue](https://gitlab.com/gitlab-org/gitlab/-/issues/267996), when minimal access users: +Because of an [outstanding issue](https://gitlab.com/gitlab-org/gitlab/-/issues/267996), when a user with the Minimal Access role: -- Sign in with standard web authentication, they receive a `404` error when accessing the parent group. -- Sign in with Group SSO, they receive a `404` error immediately because they are redirected to the parent group page. +- Signs in with standard web authentication, they receive a `404` error when accessing the parent group. +- Signs in with Group SSO, they receive a `404` error immediately because they are redirected to the parent group page. To work around the issue, give these users the Guest role or higher to any project or subgroup within the parent group. -### Minimal access users take license seats - -Users with even a "minimal access" role are counted against your number of license seats. This -requirement does not apply for [GitLab Ultimate](https://about.gitlab.com/pricing/) -subscriptions. - ## Related topics - [The GitLab principles behind permissions](https://about.gitlab.com/handbook/product/gitlab-the-product/#permissions-in-gitlab) - [Members](project/members/index.md) - Customize permissions on [protected branches](project/protected_branches.md) - [LDAP user permissions](group/access_and_permissions.md#manage-group-memberships-via-ldap) -- [Value stream analytics permissions](analytics/value_stream_analytics.md#access-permissions-for-value-stream-analytics) +- [Value stream analytics permissions](group/value_stream_analytics/index.md#access-permissions-for-value-stream-analytics) - [Project aliases](../user/project/import/index.md#project-aliases) - [Auditor users](../administration/auditor_users.md) - [Confidential issues](project/issues/confidential_issues.md) @@ -539,8 +539,5 @@ the Owner role: ### Known issues - Additional permissions can only be applied to users with the Guest role. -- There is no visual distinction in the UI between the Guest role and the Guest role with additional permission. For more information, see [issue 384099](https://gitlab.com/gitlab-org/gitlab/-/issues/384099). - If a user with a custom role is shared with a group or project, their custom role is not transferred over with them. The user has the regular Guest role in the new group or project. -- If a custom role is deleted, the users associated with that custom role are also removed from the group. For more information, see [issue 370352](https://gitlab.com/gitlab-org/gitlab/-/issues/370352). -- The API endpoint for associating a custom role with a user only works for users with the Guest role in a group. A project member can be associated with a custom role, but not through the API yet. For more information, see [issue 385495](https://gitlab.com/gitlab-org/gitlab/-/issues/385495). -- The only way to remove a custom role from a user's membership to a Group is to delete the custom role, which deletes the user membership entirely. See [issue 387769](https://gitlab.com/gitlab-org/gitlab/-/issues/387769). +- You cannot use an [Auditor user](../administration/auditor_users.md) as a template for a custom role. diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 1a6ad4edf02..4c5733ed5ec 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -4,21 +4,30 @@ 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 --- -# Product analytics **(ULTIMATE)** +# Product analytics (Experiment) **(ULTIMATE)** -> - Introduced in GitLab 15.4 as an [Alpha](../../policy/alpha-beta-support.md#alpha-features) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - Introduced in GitLab 15.4 as an [Experiment](../../policy/alpha-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. > - `cube_api_proxy` revised to only reference the [Product Analytics API](../../api/product_analytics.md) in GitLab 15.6. > - `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10. +> - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. 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/). -## How Product Analytics works +## How product analytics works + +Product analytics uses several tools: + +- [**Jitsu**](https://jitsu.com/docs) - A web and app event collection platform that provides a consistent API to collect user data and pass it through to ClickHouse. +- [**ClickHouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. +- [**Cube.js**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in Clickhouse. + +The following diagram illustrates the product analytics flow: ```mermaid --- @@ -41,25 +50,20 @@ flowchart TB end ``` -Product Analytics uses several tools: - -- [**Jitsu**](https://jitsu.com/docs) - A web and app event collection platform that provides a consistent API to collect user data and pass it through to Clickhouse. -- [**Clickhouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. -- [**Cube.js**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in Clickhouse. - ## Enable product analytics > - Introduced in GitLab 15.6 behind the [feature flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. > - Moved to be behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_admin_settings` in GitLab 15.7. Disabled by default. > - `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10. +> - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_admin_settings`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flags](../../administration/feature_flags.md) named `product_analytics_dashboards` and `product_analytics_admin_settings`. On GitLab.com, this feature is not available. This feature is not ready for production use. -You can enable and configure product analytics to track events -within your project applications on a self-managed instance. +To track events in your project applications on a self-managed instance, +you must enable and configure product analytics. Prerequisite: @@ -71,31 +75,37 @@ Prerequisite: 1. Select **Enable product analytics** and enter the configuration values. The following table shows the required configuration parameters and example values: - | Name | Value | - |------------------------------|------------------------------------------------------------| - | Jitsu host | `https://jitsu.gitlab.com` | - | Jitsu project ID | `g0maofw84gx5sjxgse2k` | - | Jitsu administrator email | `jitsu.admin@gitlab.com` | - | Jitsu administrator password | `<your_password>` | - | Clickhouse URL | `https://<username>:<password>@clickhouse.gitlab.com:8123` | - | Cube API URL | `https://cube.gitlab.com` | - | Cube API key | `25718201b3e9...ae6bbdc62dbb` | + | Name | Value | + |--------------------------------|------------------------------------------------------------| + | Configurator connection string | `https://test:test@configurator.gitlab.com` | + | Jitsu host | `https://jitsu.gitlab.com` | + | Jitsu project ID | `g0maofw84gx5sjxgse2k` | + | Jitsu administrator email | `jitsu.admin@gitlab.com` | + | Jitsu administrator password | `<your_password>` | + | Collector host | `https://collector.gitlab.com` | + | ClickHouse URL | `https://<username>:<password>@clickhouse.gitlab.com:8123` | + | Cube API URL | `https://cube.gitlab.com` | + | Cube API key | `25718201b3e9...ae6bbdc62dbb` | 1. Select **Save changes**. ## Product analytics dashboards -> Introduced in GitLab 15.5 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default. +> - Introduced in GitLab 15.5 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default. +> - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. On GitLab.com, this feature is not available. This feature is not ready for production use. -Each project can define an unlimited number of dashboards. These dashboards are defined using our YAML schema and stored -in the `.gitlab/product_analytics/dashboards/` directory of a project repository. The name of the file is the name of the dashboard, and visualizations are shared across dashboards. +Each project can have an unlimited number of dashboards. +These dashboards are defined using the GitLab YAML schema, and stored in the `.gitlab/product_analytics/dashboards/` directory of a project repository. +The name of the file is the name of the dashboard. +Each dashboard can contain one or more visualizations (charts), which are shared across dashboards. -Project maintainers can enforce approval rules on dashboard changes using features such as code owners and approval rules. Dashboards are versioned in source control with the rest of a project's code. +Project maintainers can enforce approval rules on dashboard changes using features such as code owners and approval rules. +Dashboards are versioned in source control with the rest of a project's code. ### View project dashboards @@ -110,17 +120,25 @@ To view a list of product analytics dashboards for a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Dashboards**. +1. From the list of available dashboards, select the dashboard you want to view. ### Define a dashboard To define a dashboard: -1. In `.gitlab/product_analytics/dashboards/`, create a directory named like the dashboard. Each dashboard should have its own directory. -1. In the new directory, create a `.yaml` file with the same name as the directory. This file contains the dashboard definition, and must conform to the JSON schema defined in `ee/app/validators/json_schemas/product_analytics_dashboard.json`. -1. In the `.gitlab/product_analytics/dashboards/visualizations/` directory, create a `yaml` file. This file defines the visualization type for the dashboard, and must conform to the schema in +1. In `.gitlab/product_analytics/dashboards/`, create a directory named like the dashboard. + + Each dashboard should have its own directory. +1. In the new directory, create a `.yaml` file with the same name as the directory. + + This file contains the dashboard definition. It must conform to the JSON schema defined in `ee/app/validators/json_schemas/product_analytics_dashboard.json`. +1. In the `.gitlab/product_analytics/dashboards/visualizations/` directory, create a `.yaml` file. + + This file defines the visualization type for the dashboard. It must conform to the schema in `ee/app/validators/json_schemas/product_analytics_visualization.json`. -The example below includes three dashboards and one visualization that applies to all dashboards. +For example, if you want to create three dashboards (Conversion funnels, Demographic breakdown, and North star metrics) +and one visualization (line chart) that applies to all dashboards, the file structure would be: ```plaintext .gitlab/product_analytics/dashboards @@ -136,13 +154,13 @@ The example below includes three dashboards and one visualization that applies t ## Funnel analysis -Funnel analysis can be used to understand the flow of users through your application and where +Use funnel analysis to understand the flow of users through your application, and where users drop out of a predefined flow (for example, a checkout process or ticket purchase). Each product can also define an unlimited number of funnels. -These funnels are defined using our YAML schema and stored in the `.gitlab/product_analytics/funnels/` directory of a project repository. +Like dashboards, funnels are defined using the GitLab YAML schema, and stored in the `.gitlab/product_analytics/funnels/` directory of a project repository. -Funnel definitions must include the keys `name`, `seconds_to_convert`, and an array of `steps`. +Funnel definitions must include the keys `name` and `seconds_to_convert`, and an array of `steps`. | Key | Description | |----------------------|----------------------------------------------------------| @@ -160,6 +178,8 @@ Each step must include the keys `name`, `target`, and `action`. ### Example funnel definition +The following example defines a funnel that tracks users who completed a purchase within one hour by going through three target pages: + ```yaml name: completed_purchase seconds_to_convert: 3600 @@ -212,23 +232,33 @@ The `afterDate` filter is not supported. Please use `beforeDate` or `inDateRange Exporting the raw event data from the underlying storage engine can help you debug and create datasets for data analysis. +Because Cube acts as an abstraction layer between the raw data and the API, the exported raw data has some caveats: + +- Data is grouped by the selected dimensions. Therefore, the exported data might be incomplete, unless including both `utcTime` and `userAnonymousId`. +- Data is by default limited to 10,000 rows, but you can increase the limit to maximum 50,000 rows. If your dataset has more than 50,000 rows, you must paginate through the results by using the `limit` and `offset` parameters. +- Data is always returned in JSON format. If you need it in a different format, you need to convert the JSON to the required format using a scripting language of your choice. + +[Issue 391683](https://gitlab.com/gitlab-org/gitlab/-/issues/391683) tracks efforts to implement a more scalable export solution. + ### Export raw data with Cube queries -You can [query the raw data with the REST API](../../api/product_analytics.md#send-query-request-to-cube) and convert the JSON output to any required format. +You can [query the raw data with the REST API](../../api/product_analytics.md#send-query-request-to-cube), +and convert the JSON output to any required format. -You can export the raw data for a specific dimension by passing a list of dimensions to the `dimensions` key. For example, the following query outputs the raw data for the attributes listed: +To export the raw data for a specific dimension, pass a list of dimensions to the `dimensions` key. +For example, the following query outputs the raw data for the attributes listed: ```json POST /api/v4/projects/PROJECT_ID/product_analytics/request/load?queryType=multi { + "query":{ "dimensions": [ "TrackedEvents.docEncoding", "TrackedEvents.docHost", "TrackedEvents.docPath", "TrackedEvents.docSearch", "TrackedEvents.eventType", - "TrackedEvents.idsAjsAnonymousId", "TrackedEvents.localTzOffset", "TrackedEvents.pageTitle", "TrackedEvents.src", @@ -238,16 +268,8 @@ POST /api/v4/projects/PROJECT_ID/product_analytics/request/load?queryType=multi "order": { "TrackedEvents.apiKey": "asc" } + } } ``` If the request is successful, the returned JSON includes an array of rows of results. - -### Caveats - -Because Cube acts as an abstraction layer between the raw data and the API, the exported raw data has some caveats: - -- Data is grouped by the selected dimensions. Therefore, the exported data might be incomplete, unless including both `utcTime` and `userAnonymousId`. -- Data is by default limited to 10,000 rows, but you can increase the limit to maximum 50,000 rows. If your dataset has more than 50,000 rows, you need to paginate through the results by using the `limit` and `offset` parameters. -- Data is always returned in JSON format. If you need it in a different format, you need to convert the JSON to the required format using a scripting language of your choice. -- [Issue 391683](https://gitlab.com/gitlab-org/gitlab/-/issues/391683) tracks the implementation of a more scalable export solution. diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 08d23902095..f405dc42f46 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -36,9 +36,27 @@ To create a user manually: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). 1. Select **New user**. -1. Complete the fields. +1. Complete the required fields, such as name, username, and email. 1. Select **Create user**. +A reset link is sent to the user's email and they are forced to set their +password on first sign in. + +To set a user's password without relying on the email confirmation, after you +create a user following the previous steps: + +1. Select the user. +1. Select **Edit**. +1. Complete the password and password confirmation fields. +1. Select **Save changes**. + +The user can now sign in with the new username and password, and they are asked +to change the password you set up for them. + +NOTE: +If you wanted to create a test user, you could follow the previous steps +by providing a fake email and using the same password in the final confirmation. + ## Create users through authentication integrations Users are: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index fe2e2acaae3..a26f027f329 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -273,7 +273,7 @@ feature flag after WebAuthn devices have been registered, these devices are not On GitLab.com, WebAuthn devices are available. FLAG: -On self-managed GitLab, by default, optional one-time password authentication for WebAuthn devices is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `webauthn_without_topt`. +On self-managed GitLab, by default, optional one-time password authentication for WebAuthn devices is not available. To enable the feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `webauthn_without_totp`. On GitLab.com, this feature is available. WebAuthn is [supported by](https://caniuse.com/#search=webauthn) the following: diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md new file mode 100644 index 00000000000..c8456a80e69 --- /dev/null +++ b/doc/user/profile/achievements.md @@ -0,0 +1,235 @@ +--- +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 +--- + +# Achievements (Experiment) **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113156) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `achievements`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `achievements`. +The feature is not ready for production use. + +Achievements are a way to reward users for their activity on GitLab. +As a namespace maintainer or owner, you can create custom achievements for specific contributions, which you can award to or revoke from users based on your criteria. + +As a user, you can collect achievements to highlight your contributions to different projects or groups on your profile. +An achievement consists of a name, a description, and an avatar. + + + +This feature is an Experiment. +For more information about planned work, see [epic 9429](https://gitlab.com/groups/gitlab-org/-/epics/9429). +Tell us about your use cases by leaving comments in the epic. + +## Types of achievement + +Programmatically, there is only one way to create, award, revoke, or delete achievements. + +Practically, you can differentiate between achievements that are awarded: + +- Once and irrevocable. For example, a "First contribution merged" achievement. +- Once and revocable. For example, a "Core team member" achievement. +- Multiple times. For example, a "Contributor of the month" achievement. + +## View a user's achievements + +You can view a user's achievements on their profile page. + +Prerequisites: + +- The user profile must be public. +- You must be a member of the namespace awarding the achievement, or the namespace must be public. + +To view a user's achievements: + +1. Go to the user's profile page. +1. Below the user's avatar, see their achievements. +1. To view details about an achievement, hover over it. + It displays the following information: + + - Name of the achievement + - Description of the achievement + - Date when the achievement was awarded to the user + - Namespace that awarded the achievement + +To retrieve a list of a user's achievements, query the [`user` GraphQL type](../../api/graphql/reference/index.md#user). + +```graphql +query { + user(username: "<username>") { + userAchievements { + nodes { + achievement { + name + description + avatarUrl + namespace { + fullPath + name + } + } + } + } + } +} +``` + +## Create an achievement + +You can create custom achievements to award for specific contributions. + +Prerequisites: + +- You must have the Maintainer or Owner role for the namespace. + +To create an achievement, call the [`achievementsCreate` GraphQL mutation](../../api/graphql/reference/index.md#mutationachievementscreate). + +```graphql +mutation achievementsCreate($file: Upload!) { + achievementsCreate( + input: { + namespaceId: "gid://gitlab/Namespace/<namespace id>", + name: "<name>", + description: "<description>", + avatar: $file} + ) { + errors + achievement { + id + name + description + avatarUrl + } + } +} +``` + +## Update an achievement + +You can change the name, description, and avatar of an achievement at any time. + +Prerequisites: + +- You must have the Maintainer or Owner role for the namespace. + +To update an achievement, call the [`achievementsUpdate` GraphQL mutation](../../api/graphql/reference/index.md#mutationachievementsupdate). + +```graphql +mutation achievementsUpdate($file: Upload!) { + achievementsUpdate( + input: { + achievementId: "gid://gitlab/Achievements::Achievement/<achievement id>", + name: "<new name>", + description: "<new description>", + avatar: $file} + ) { + errors + achievement { + id + name + description + avatarUrl + } + } +} +``` + +## Award an achievement + +You can award an achievement to a user to recognize their contributions. +The user receives an email notification when they are awarded an achievement. + +Prerequisites: + +- You must have the Maintainer or Owner role for the namespace. + +To award an achievement to a user, call the [`achievementsAward` GraphQL mutation](../../api/graphql/reference/index.md#mutationachievementsaward). + +```graphql +mutation { + achievementsAward(input: { + achievementId: "gid://gitlab/Achievements::Achievement/<achievement id>", + userId: "gid://gitlab/User/<user id>" }) { + userAchievement { + id + achievement { + id + name + } + user { + id + username + } + } + errors + } +} +``` + +## Revoke an achievement + +You can revoke a user's achievement if you consider the user no longer meets the awarding criteria. + +Prerequisites: + +- You must have the Maintainer or Owner role for the namespace. + +To revoke an achievement, call the [`achievementsRevoke` GraphQL mutation](../../api/graphql/reference/index.md#mutationachievementsrevoke). + +```graphql +mutation { + achievementsRevoke(input: { + userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>" }) { + userAchievement { + id + achievement { + id + name + } + user { + id + username + } + revokedAt + } + errors + } +} +``` + +## Delete an achievement + +If you consider you no longer need an achievement, you can delete it. +This will delete all related awarded and revoked instances of the achievement. + +Prerequisites: + +- You must have the Maintainer or Owner role for the namespace. + +To delete an achievement, call the [`achievementsDelete` GraphQL mutation](../../api/graphql/reference/index.md#mutationachievementsdelete). + +```graphql +mutation { + achievementsDelete(input: { + achievementId: "gid://gitlab/Achievements::Achievement/<achievement id>" }) { + achievement { + id + name + } + errors + } +} +``` + +## Hide achievements + +If you don't want to display achievements on your profile, you can opt out. To do this: + +1. On the top bar, in the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. In the **Main settings** section, clear the **Display achievements on your profile** checkbox. +1. Select **Update profile settings**. diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md new file mode 100644 index 00000000000..b9cd595916c --- /dev/null +++ b/doc/user/profile/comment_templates.md @@ -0,0 +1,68 @@ +--- +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 +--- + +# Comment templates **(FREE)** + +> - GraphQL support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352956) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. +> - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113232) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. Enabled for GitLab team members only. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `saved_replies`. +On GitLab.com, this feature is not available by default, but enabled for GitLab team members. + +With comment templates, create and reuse text for any text area in: + +- Merge requests, including diffs. +- Issues, including design management comments. +- Epics. +- Work items. + +Comment templates can be small, like approving a merge request and unassigning yourself from it, +or large, like chunks of boilerplate text you use frequently: + + + +For more information about the rollout plan for this feature, see [issue 352956](https://gitlab.com/gitlab-org/gitlab/-/issues/352956). + +## Use comment templates in a text area + +To include the text of a comment template in your comment: + +1. In the editor toolbar for your comment, select **Comment templates** (**{symlink}**). +1. Select your desired comment template. + +## Create comment templates + +To create a comment template for future use: + +1. On the top bar, in the upper-right corner, select your avatar. +1. From the dropdown list, select **Preferences**. +1. On the left sidebar, select **Comment templates** (**{symlink}**). +1. Provide a **Name** for your comment template. +1. Enter the **Content** of your reply. You can use any formatting you use in + other GitLab text areas. +1. Select **Save**, and the page reloads with your comment template shown. + +## View your comment templates + +To go to your comment templates: + +1. On the top bar, in the upper-right corner, select your avatar. +1. From the dropdown list, select **Preferences**. +1. On the left sidebar, select **Comment templates** (**{symlink}**). +1. Scroll to **My comment templates**. + +## Edit or delete comment templates + +To edit or delete a previously comment template: + +1. On the top bar, in the upper-right corner, select your avatar. +1. From the dropdown list, select **Preferences**. +1. On the left sidebar, select **Comment templates** (**{symlink}**). +1. Scroll to **My comment templates**, and identify the comment template you want to edit. +1. To edit, select **Edit** (**{pencil}**). +1. To delete, select **Delete** (**{remove}**), then select **Delete** again from the modal window. diff --git a/doc/user/profile/img/busy_indicator_note_header_v13_9.png b/doc/user/profile/img/busy_indicator_note_header_v13_9.png Binary files differdeleted file mode 100644 index 63301ebdc14..00000000000 --- a/doc/user/profile/img/busy_indicator_note_header_v13_9.png +++ /dev/null diff --git a/doc/user/profile/img/busy_indicator_notes_v13_9.png b/doc/user/profile/img/busy_indicator_notes_v13_9.png Binary files differdeleted file mode 100644 index 2efe075c72b..00000000000 --- a/doc/user/profile/img/busy_indicator_notes_v13_9.png +++ /dev/null diff --git a/doc/user/profile/img/busy_indicator_profile_page_v13_6.png b/doc/user/profile/img/busy_indicator_profile_page_v13_6.png Binary files differdeleted file mode 100644 index c8e969f38db..00000000000 --- a/doc/user/profile/img/busy_indicator_profile_page_v13_6.png +++ /dev/null diff --git a/doc/user/profile/img/busy_indicator_settings_menu_v13_6.png b/doc/user/profile/img/busy_indicator_settings_menu_v13_6.png Binary files differdeleted file mode 100644 index 711638541dd..00000000000 --- a/doc/user/profile/img/busy_indicator_settings_menu_v13_6.png +++ /dev/null diff --git a/doc/user/profile/img/busy_indicator_sidebar_collapsed_v13_9.png b/doc/user/profile/img/busy_indicator_sidebar_collapsed_v13_9.png Binary files differdeleted file mode 100644 index 3dca88ec8cc..00000000000 --- a/doc/user/profile/img/busy_indicator_sidebar_collapsed_v13_9.png +++ /dev/null diff --git a/doc/user/profile/img/busy_indicator_sidebar_v13_9.png b/doc/user/profile/img/busy_indicator_sidebar_v13_9.png Binary files differdeleted file mode 100644 index 83024b319bf..00000000000 --- a/doc/user/profile/img/busy_indicator_sidebar_v13_9.png +++ /dev/null diff --git a/doc/user/profile/img/busy_indicator_user_popovers_v13_6.png b/doc/user/profile/img/busy_indicator_user_popovers_v13_6.png Binary files differdeleted file mode 100644 index 16fb0e6556b..00000000000 --- a/doc/user/profile/img/busy_indicator_user_popovers_v13_6.png +++ /dev/null diff --git a/doc/user/profile/img/profile-preferences-syntax-themes.png b/doc/user/profile/img/profile-preferences-syntax-themes.png Binary files differdeleted file mode 100644 index 719df9410fc..00000000000 --- a/doc/user/profile/img/profile-preferences-syntax-themes.png +++ /dev/null diff --git a/doc/user/profile/img/profile-preferences-syntax-themes_v15_11.png b/doc/user/profile/img/profile-preferences-syntax-themes_v15_11.png Binary files differnew file mode 100644 index 00000000000..39cd35f3b5b --- /dev/null +++ b/doc/user/profile/img/profile-preferences-syntax-themes_v15_11.png diff --git a/doc/user/profile/img/user_profile_achievements_v15_11.png b/doc/user/profile/img/user_profile_achievements_v15_11.png Binary files differnew file mode 100644 index 00000000000..cf675cd6b06 --- /dev/null +++ b/doc/user/profile/img/user_profile_achievements_v15_11.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d52f119ba09..191695bc7ab 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -135,11 +135,13 @@ To add links to other accounts: 1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. In the **Main settings** section, add your information from: - - Discord ([User ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-)) - - LinkedIn - - Skype - - Twitter +1. In the **Main settings** section, add your: + - Discord [user ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-). + - LinkedIn profile name. + - Skype username. + - Twitter @username. + + Your user ID or username must be 500 characters or less. 1. Select **Update profile settings**. ## Show private contributions on your user profile page @@ -164,7 +166,7 @@ To specify your pronouns: 1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. In the **Pronouns** text box, enter your pronouns. +1. In the **Pronouns** text box, enter your pronouns. The text must be 50 characters or less. 1. Select **Update profile settings**. ## Add your name pronunciation @@ -178,7 +180,7 @@ To add your name pronunciation: 1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. In the **Pronunciation** text box, enter how your name is pronounced. +1. In the **Pronunciation** text box, enter how your name is pronounced. The pronunciation must be plain text and 255 characters or less. 1. Select **Update profile settings**. ## Set your current status @@ -224,25 +226,7 @@ To set the busy status indicator, either: 1. Select **Edit profile**. 1. In the **Current status** section, select the **Set yourself as busy** checkbox. - The busy status is displayed in the user interface. - - Username: - - | Profile page | Settings menu | User popovers | - | --- | --- | --- | - |  |  |  | - - Issue and merge request sidebar: - - | Sidebar| Collapsed sidebar | - | --- | --- | - |  |  | - - Notes: - - | Notes | Note headers | - | --- | --- | - |  |  | + The busy status is displayed next to your name, every time your name is shown in the user interface. ## Set your time zone diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index e6675b4eff2..c0c967a3f18 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -1,5 +1,4 @@ --- -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/notifications.html' 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 diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 0f46c3d6d25..696a5f4b42e 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -39,11 +39,11 @@ The default theme is Indigo. You can choose between 10 themes: ## Dark mode -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Alpha](../../policy/alpha-beta-support.md#alpha-features) release. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Experiment](../../policy/alpha-beta-support.md#experiment) release. -GitLab has started work on dark mode! The dark mode Alpha release is available in the +GitLab has started work on dark mode! The dark mode Experiment release is available in the spirit of iteration and the lower expectations of -[Alpha versions](../../policy/alpha-beta-support.md#alpha-features). +[Experiment features](../../policy/alpha-beta-support.md#experiment). Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). See the epic for: @@ -65,7 +65,7 @@ Dark theme only works with the **Dark** syntax highlighting theme. > Changing the default syntax highlighting theme for new users and users who are not signed in [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25129) in GitLab 15.10. -GitLab uses the [rouge Ruby library](http://rouge.jneen.net/ "Rouge website") +GitLab uses the [Rouge Ruby library](https://github.com/rouge-ruby/rouge) for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for @@ -75,19 +75,7 @@ the respective libraries. Changing this setting allows you to customize the color theme when viewing any syntax highlighted code on GitLab. -The default syntax theme is White, and you can choose among 5 different themes: - -<!-- vale gitlab.Spelling = NO --> - -- White -- Dark -- Solarized light -- Solarized dark -- Monokai - -<!-- vale gitlab.Spelling = YES --> - - + Introduced in GitLab 13.6, the themes [Solarized](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) also apply to the [Web IDE](../project/web_ide/index.md) and [Snippets](../snippets.md). @@ -199,16 +187,15 @@ Open an issue if you notice that using absolute times breaks a layout. ## Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370139) in GitLab 15.7 [with a flag](../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370139) in GitLab 15.7 [with a flag](../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The [Web IDE Beta](../project/web_ide_beta/index.md) is -the default editing environment when the `vscode_web_ide` feature -flag is enabled. - -To stop using the Web IDE Beta: +the default editing environment. To stop using the Web IDE Beta: 1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. 1. Select **Save changes**. diff --git a/doc/user/profile/saved_replies.md b/doc/user/profile/saved_replies.md index 302daceb31d..1f4e4f5fa51 100644 --- a/doc/user/profile/saved_replies.md +++ b/doc/user/profile/saved_replies.md @@ -1,61 +1,11 @@ --- -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 +redirect_to: 'comment_templates.md' +remove_date: '2023-06-22' --- -# Saved replies **(FREE)** +This document was moved to [another location](comment_templates.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352956) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. - -With saved replies, create and reuse text for any text area in: - -- Merge requests, including diffs. -- Issues, including design management comments. -- Epics. -- Work items. - -Saved replies can be small, like approving a merge request and unassigning yourself from it, -or large, like chunks of boilerplate text you use frequently: - - - -## Use saved replies in a text area - -To include the text of a saved reply in your comment: - -1. In the editor toolbar for your comment, select **Saved replies** (**{symlink}**). -1. Select your desired saved reply. - -## Create saved replies - -To create a saved reply for future use: - -1. On the top bar, in the upper-right corner, select your avatar. -1. From the dropdown list, select **Preferences**. -1. On the left sidebar, select **Saved replies** (**{symlink}**). -1. Provide a **Name** for your saved reply. -1. Enter the **Content** of your reply. You can use any formatting you use in - other GitLab text areas. -1. Select **Save**, and the page reloads with your saved reply shown. - -## View your saved replies - -To go to your saved replies: - -1. On the top bar, in the upper-right corner, select your avatar. -1. From the dropdown list, select **Preferences**. -1. On the left sidebar, select **Saved replies** (**{symlink}**). -1. Scroll to **My saved replies**. - -## Edit or delete saved replies - -To edit or delete a previously saved reply: - -1. On the top bar, in the upper-right corner, select your avatar. -1. From the dropdown list, select **Preferences**. -1. On the left sidebar, select **Saved replies** (**{symlink}**). -1. Scroll to **My saved replies**, and identify the saved reply you want to edit. -1. To edit, select **Edit** (**{pencil}**). -1. To delete, select **Delete** (**{remove}**), then select **Delete** again from the modal window. +<!-- This redirect file can be deleted after <2023-06-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/project/badges.md b/doc/user/project/badges.md index 2d36a378b82..76933255820 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -62,7 +62,7 @@ You can access a test coverage report badge image by using the following link: https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg ``` -You can define the regular expression for the [coverage report](../../ci/pipelines/settings.md#merge-request-test-coverage-results) +You can define the regular expression for the [coverage report](../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) that each job log is matched against. This means that each job in the pipeline can have the test coverage percentage value defined. @@ -279,7 +279,7 @@ To add a new badge with a custom image to a group or project: 1. Select **Add badge**. To learn how to use custom images generated through a pipeline, see the documentation on -[accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts). +[accessing the latest job artifacts by URL](../../ci/jobs/job_artifacts.md#from-a-url). ## Placeholders diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index a64edd053b1..8410655c244 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -313,5 +313,5 @@ an error is produced when generating a changelog. ## Related topics -- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API. -- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab. +- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API +- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 3ed8a4a67cf..c4f4f220c9b 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index a7fac2a1cea..bb85662d442 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index e00c4370da9..c6561fffa0b 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -77,7 +77,7 @@ cluster certificates: - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) + - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-resource) of the Virtual Machine instance to base the cluster on. - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster. See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index bf2f6e28d9a..bba05f1e724 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 0eea3ebb8cd..ff30da2ca98 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index e2d0a010293..31d5a73757a 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 46e74eb8460..b321646d8d8 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 490188b27b0..5ce1994ba36 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 9167e6197d6..c8f49b1917d 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index b1f2a9dbb79..a985436d67d 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 0994bff4aa2..f9244177aa5 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,473 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'codeowners/index.md' +remove_date: '2023-07-07' --- -# Code Owners **(PREMIUM)** +This document was moved to [another location](codeowners/index.md). -> Moved to GitLab Premium in 13.9. - -Use the Code Owners feature to define who has expertise for specific parts of your project's codebase. -Define the owners of files and directories in a repository to: - -- **Require owners to approve changes.** Combine protected branches with Code Owners to require - experts to approve merge requests before they merge into a protected branch. -- **Identify owners.** Code Owner names are displayed on the files and directories they own: -  - -Use Code Owners in combination with merge request -[approval rules](merge_requests/approvals/rules.md) (either optional or required) -to build a flexible approval workflow: - -- Use **Code Owners** to ensure quality. Define the users who have domain expertise - for specific paths in your repository. -- Use **Approval rules** to define areas of expertise that don't correspond to specific - file paths in your repository. Approval rules help guide merge request creators to - the correct set of reviewers, such as frontend developers or a security team. - -For example: - -| Type | Name | Scope | Comment | -|------|------|--------|------------| -| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. -| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. -| Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. -| Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. - -<div class="video-fallback"> - Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> -</figure> - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> - -## View a file's Code Owner - -To view the Code Owners for a file: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files**. -1. Go to the file or directory you want to see the Code Owners for. -1. Optional. Select your desired branch. - -GitLab shows the Code Owners at the top of the page. - -## Set up Code Owners - -1. Create a `CODEOWNERS` file in your [preferred location](#code-owners-file). -1. In the file, enter text that follows one of these patterns: - - ```plaintext - # Code Owners for a file - filename @username1 @username2 - - # Code Owners for a directory - directoryname/ @username1 @username2 - - # All group members as Code Owners for a file - filename @groupname - - # All group members as Code Owners for a directory - directoryname/ @groupname - ``` - -### Code Owners file - -A `CODEOWNERS` file (with no extension) specifies the users or -[shared groups](members/share_project_with_groups.md) responsible for -specific files and directories in a repository. - -Each repository uses a single `CODEOWNERS` file. GitLab checks these locations -in your repository in this order. The first `CODEOWNERS` file found is used, and -all others are ignored: - -1. In the root directory: `./CODEOWNERS`. -1. In the `docs` directory: `./docs/CODEOWNERS`. -1. In the `.gitlab` directory: `./.gitlab/CODEOWNERS`. - -### Make Code Owners eligible approvers or require their approval of MRs - -- [Add Code Owners as merge request approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). -- Set up [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch). - -### Groups as Code Owners - -> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. - -You can use members of groups and subgroups as Code Owners for projects: - -```mermaid -graph TD - A[Parent group X] -->|owns| B[Project A] - A -->|contains| C[Subgroup Y] - C -->|owns| D[Project B] - A-. inherits ownership .-> D -``` - -In this example: - -- **Parent group X** (`group-x`) owns **Project A**. -- **Parent group X** also contains a subgroup, **Subgroup Y**. (`group-x/subgroup-y`) -- **Subgroup Y** owns **Project B**. - -The eligible Code Owners are: - -- **Project A**: the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. -- **Project B**: the members of both **Group X** and **Subgroup Y**. - -You can [invite](members/share_project_with_groups.md) **Subgroup Y** to **Project A** -so that their members also become eligible Code Owners. - -```mermaid -graph LR - A[Parent group X] -->|owns| B[Project A] - A -->|also contains| C[Subgroup Y] - C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| F[Approvals can be<br/> required] -.-> B - D{Invite Subgroup Y<br/>to Project A?} -.->|no| I[Subgroup Y cannot be<br /> an approver] -.-> B - C -.->E{Add Subgroup Y<br/>as Code Owners<br/>to Project A?} -.->|yes| H[Approvals can only<br/>be optional] -.-> B -``` - -If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval -of the merge request becomes optional. - -Inviting **Subgroup Y** to a parent group of **Project A** -[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as -Code Owners, add this group directly to the project itself. - -NOTE: -For approval to be required, groups as Code Owners must have a direct membership -(not inherited membership) in the project. Approval can only be optional for groups -that inherit membership. Members in the Code Owners group also must be direct members, -and not inherit membership from any parent groups. - -#### Add a group as a Code Owner - -To set a group as a Code Owner: - -In the `CODEOWNERS` file, enter text that follows one of these patterns: - -```plaintext -# All group members as Code Owners for a file -file.md @group-x - -# All subgroup members as Code Owners for a file -file.md @group-x/subgroup-y - -# All group and subgroup members as Code Owners for a file -file.md @group-x @group-x/subgroup-y -``` - -### Define more specific owners for more specifically defined files or directories - -When a file or directory matches multiple entries in the `CODEOWNERS` file, -the users from last pattern matching the file or directory are used. This enables you -to define more specific owners for more specifically defined files or directories, when -you order the entries in a sensible way. - -For example, in the following `CODEOWNERS` file: - -```plaintext -# This line would match the file terms.md -*.md @doc-team - -# This line would also match the file terms.md -terms.md @legal-team -``` - -The Code Owner for `terms.md` would be `@legal-team`. - -If you use sections, the last pattern matching the file or directory for each section is used. -For example, in a `CODEOWNERS` file using sections: - -```plaintext -[README Owners] -README.md @user1 @user2 -internal/README.md @user4 - -[README other owners] -README.md @user3 -``` - -The Code Owners for the `README.md` in the root directory are `@user1`, `@user2`, -and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. - -Only one CODEOWNERS pattern per section is matched to a file path. - -### Organize Code Owners by putting them into sections - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed. - -You can organize Code Owners by putting them into named sections. - -You can use sections for shared directories, so that multiple -teams can be reviewers. - -To add a section to the `CODEOWNERS` file, enter a section name in brackets, -followed by the files or directories, and users, groups, or subgroups: - -```plaintext -[README Owners] -README.md @user1 @user2 -internal/README.md @user2 -``` - -Each Code Owner in the merge request widget is listed under a label. -The following image shows a **Groups** and **Documentation** section: - - - -#### Set default owner for a section **(PREMIUM SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `codeowners_default_owners`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `codeowners_default_owners`. -The feature is not ready for production use. - -WARNING: -To disable this feature flag after setting default owners per section, edit your -CODEOWNERS file to [list Code Owners per line](#set-up-code-owners). - -If multiple file paths inside a section share the same ownership, define a default -Code Owner for the section. All paths in that section inherit this default, unless -you override the section default on a specific line. - -Default owners are applied when specific owners are not specified for file paths. -Specific owners defined beside the file path override default owners: - -```plaintext -[Documentation] @docs-team -docs/ -README.md - -[Database] @database-team -model/db/ -config/db/database-setup.md @docs-team -``` - -In this example: - -- `@docs-team` owns all items in the `Documentation` section. -- `@database-team` owns all items in the `Database` section except - `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. - -To combine the syntax for default owners with [optional sections](#make-a-code-owners-section-optional) -and required approvals, place default owners at the end: - -```plaintext -[Documentation][2] @docs-team -docs/ -README.md - -^[Database] @database-team -model/db/ -config/db/database-setup.md @docs-team -``` - -#### Sections with duplicate names - -If multiple sections have the same name, they are combined. -Also, section headings are not case-sensitive. For example: - -```plaintext -[Documentation] -ee/docs/ @docs -docs/ @docs - -[Database] -README.md @database -model/db/ @database - -[DOCUMENTATION] -README.md @docs -``` - -This code results in three entries under the **Documentation** section header, and two -entries under **Database**. The entries defined under the sections **Documentation** and -**DOCUMENTATION** are combined, using the case of the first section. - -#### Make a Code Owners section optional - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. - -You can designate optional sections in your Code Owners file. Prepend the -section name with the caret `^` character to treat the entire section as optional. -Optional sections enable you to designate responsible parties for various parts -of your codebase, but not require approval from them. This approach provides -a more relaxed policy for parts of your project that are frequently updated, -but don't require stringent reviews. - -In this example, the `[Go]` section is optional: - -```plaintext -[Documentation] -*.md @root - -[Ruby] -*.rb @root - -^[Go] -*.go @root -``` - -The optional Code Owners section displays in merge requests under the **Approval Rules** area: - - - -If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the section is required. - -Optional sections in the `CODEOWNERS` file are treated as optional only -when changes are submitted by using merge requests. If a change is submitted directly -to the protected branch, approval from Code Owners is still required, even if the -section is marked as optional. - -### Require multiple approvals from Code Owners - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335451) in GitLab 15.9. - -You can require multiple approvals for the Code Owners sections under the Approval Rules area in merge requests. -Append the section name with a number `n` in brackets. This requires `n` approvals from the Code Owners in this section. -Please note valid entries for `n` are integers `≥ 1`. `[1]` is optional as it is the default. Invalid values for `n` are treated as `1`. - -WARNING: -[Issue #384881](https://gitlab.com/gitlab-org/gitlab/-/issues/385881) proposes changes -to the behavior of this setting. Do not intentionally set invalid values. They may -become valid in the future, and cause unexpected behavior. - -Please confirm you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals will be optional. - -In this example, the `[Documentation]` section requires 2 approvals: - -```plaintext -[Documentation][2] -*.md @tech-writer-team - -[Ruby] -*.rb @dev-team -``` - -The `Documentation` Code Owners section under the **Approval Rules** area displays 2 approvals are required: - - - -### Allowed to Push - -The Code Owner approval and protected branch features do not apply to users who -are **Allowed to push**. - -## Example `CODEOWNERS` file - -```plaintext -# This is an example of a CODEOWNERS file. -# Lines that start with `#` are ignored. - -# app/ @commented-rule - -# Specify a default Code Owner by using a wildcard: -* @default-codeowner - -# Specify multiple Code Owners by using a tab or space: -* @multiple @code @owners - -# Rules defined later in the file take precedence over the rules -# defined before. -# For example, for all files with a filename ending in `.rb`: -*.rb @ruby-owner - -# Files with a `#` can still be accessed by escaping the pound sign: -\#file_with_pound.rb @owner-file-with-pound - -# Specify multiple Code Owners separated by spaces or tabs. -# In the following case the CODEOWNERS file from the root of the repo -# has 3 Code Owners (@multiple @code @owners): -CODEOWNERS @multiple @code @owners - -# You can use both usernames or email addresses to match -# users. Everything else is ignored. For example, this code -# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the -# owner for the LICENSE file: -LICENSE @legal this_does_not_match janedoe@gitlab.com - -# Use group names to match groups, and nested groups to specify -# them as owners for a file: -README @group @group/with-nested/subgroup - -# End a path in a `/` to specify the Code Owners for every file -# nested in that directory, on any level: -/docs/ @all-docs - -# End a path in `/*` to specify Code Owners for every file in -# a directory, but not nested deeper. This code matches -# `docs/index.md` but not `docs/projects/index.md`: -/docs/* @root-docs - -# Include `/**` to specify Code Owners for all subdirectories -# in a directory. This rule matches `docs/projects/index.md` or -# `docs/development/index.md` -/docs/**/*.md @root-docs - -# This code makes matches a `lib` directory nested anywhere in the repository: -lib/ @lib-owner - -# This code match only a `config` directory in the root of the repository: -/config/ @config-owner - -# If the path contains spaces, escape them like this: -path\ with\ spaces/ @space-owner - -# Code Owners section: -[Documentation] -ee/docs @docs -docs @docs - -# Use of default owners for a section. In this case, all files (*) are owned by -the dev team except the README.md and data-models which are owned by other teams. -[Development] @dev-team -* -README.md @docs-team -data-models/ @data-science-team - -# This section is combined with the previously defined [Documentation] section: -[DOCUMENTATION] -README.md @docs -``` - -## Technical Resources - -[Code Owners development guidelines](../../../ee/development/code_owners/index.md) - -## Troubleshooting - -### Approvals shown as optional - -A Code Owner approval rule is optional if any of these conditions are true: - -- The user or group are not a member of the project. Code Owners [cannot inherit 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). - -### Approvals do not show - -Code Owner approval rules only update when the merge request is created. -If you update the `CODEOWNERS` file, close the merge request and create a new one. - -### User not shown as possible approver - -A user might not show as an approver on the Code Owner merge request approval rules -if any of these conditions are true: - -- A rule prevents the specific user from approving the merge request. - Check the project [merge request approval](merge_requests/approvals/settings.md#edit-merge-request-approval-settings) settings. -- A Code Owner group has a visibility of **private**, and the current user is not a - member of the Code Owner group. -- Current user is an external user who does not have permission to the internal Code Owner group. - -### Approval rule is invalid. GitLab has approved this rule automatically to unblock the merge request - -This message may appear if an approval rule uses a Code Owner that is not a direct member of the project. -Check that the group or user has been invited to the project. +<!-- This redirect file can be deleted after <2023-07-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/project/codeowners/index.md b/doc/user/project/codeowners/index.md new file mode 100644 index 00000000000..bbb39179975 --- /dev/null +++ b/doc/user/project/codeowners/index.md @@ -0,0 +1,376 @@ +--- +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 +--- + +# Code Owners **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +Use the Code Owners feature to define who has expertise for specific parts of your project's codebase. +Define the owners of files and directories in a repository to: + +- **Require owners to approve changes.** Combine protected branches with Code Owners to require + experts to approve merge requests before they merge into a protected branch. +- **Identify owners.** Code Owner names are displayed on the files and directories they own: +  + +Use Code Owners in combination with merge request +[approval rules](../merge_requests/approvals/rules.md) (either optional or required) +to build a flexible approval workflow: + +- Use **Code Owners** to ensure quality. Define the users who have domain expertise + for specific paths in your repository. +- Use **Approval rules** to define areas of expertise that don't correspond to specific + file paths in your repository. Approval rules help guide merge request creators to + the correct set of reviewers, such as frontend developers or a security team. + +For example: + +| Type | Name | Scope | Comment | +|------|------|--------|------------| +| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. +| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. +| Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. +| Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. + +<div class="video-fallback"> + Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> +</figure> + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + +## View Code Owners of a file or directory + +To view the Code Owners of a file or directory: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. Go to the file or directory you want to see the Code Owners for. +1. Optional. Select a branch or tag. + +GitLab shows the Code Owners at the top of the page. + +## Set up Code Owners + +1. Create a `CODEOWNERS` file in your [preferred location](#code-owners-file). +1. Define some rules in the file following the [Code Owners syntax reference](reference.md). + Some suggestions: + - Configure [All eligible approvers](../merge_requests/approvals/rules.md#code-owners-as-eligible-approvers) approval rule. + - [Require Code Owner approval](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) on a protected branch. +1. Commit your changes, and push them up to GitLab. + +### Code Owners file + +A `CODEOWNERS` file (with no extension) specifies the users or +[shared groups](../members/share_project_with_groups.md) responsible for +specific files and directories in a repository. + +Each repository uses a single `CODEOWNERS` file. GitLab checks these locations +in your repository in this order. The first `CODEOWNERS` file found is used, and +all others are ignored: + +1. In the root directory: `./CODEOWNERS`. +1. In the `docs` directory: `./docs/CODEOWNERS`. +1. In the `.gitlab` directory: `./.gitlab/CODEOWNERS`. + +### Groups as Code Owners + +> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. + +You can use members of groups and subgroups as Code Owners for projects: + +```mermaid +graph TD + A[Parent group X] -->|owns| B[Project A] + A -->|contains| C[Subgroup Y] + C -->|owns| D[Project B] + A-. inherits ownership .-> D +``` + +In this example: + +- **Parent group X** (`group-x`) owns **Project A**. +- **Parent group X** also contains a subgroup, **Subgroup Y**. (`group-x/subgroup-y`) +- **Subgroup Y** owns **Project B**. + +The eligible Code Owners are: + +- **Project A**: the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. +- **Project B**: the members of both **Group X** and **Subgroup Y**. + +You can [invite](../members/share_project_with_groups.md) **Subgroup Y** to **Project A** +so that their members also become eligible Code Owners. + +```mermaid +graph LR + A[Parent group X] -->|owns| B[Project A] + A -->|also contains| C[Subgroup Y] + C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| F[Approvals can be<br/> required] -.-> B + D{Invite Subgroup Y<br/>to Project A?} -.->|no| I[Subgroup Y cannot be<br /> an approver] -.-> B + C -.->E{Add Subgroup Y<br/>as Code Owners<br/>to Project A?} -.->|yes| H[Approvals can only<br/>be optional] -.-> B +``` + +If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval +of the merge request becomes optional. + +Inviting **Subgroup Y** to a parent group of **Project A** +[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as +Code Owners, add this group directly to the project itself. + +NOTE: +For approval to be required, groups as Code Owners must have a direct membership +(not inherited membership) in the project. Approval can only be optional for groups +that inherit membership. Members in the Code Owners group also must be direct members, +and not inherit membership from any parent groups. + +#### Add a group as a Code Owner + +To set a group as a Code Owner: + +In the `CODEOWNERS` file, enter text that follows one of these patterns: + +```plaintext +# All group members as Code Owners for a file +file.md @group-x + +# All subgroup members as Code Owners for a file +file.md @group-x/subgroup-y + +# All group and subgroup members as Code Owners for a file +file.md @group-x @group-x/subgroup-y +``` + +### Define more specific owners for more specifically defined files or directories + +When a file or directory matches multiple entries in the `CODEOWNERS` file, +the users from last pattern matching the file or directory are used. This enables you +to define more specific owners for more specifically defined files or directories, when +you order the entries in a sensible way. + +For example, in the following `CODEOWNERS` file: + +```plaintext +# This line would match the file terms.md +*.md @doc-team + +# This line would also match the file terms.md +terms.md @legal-team +``` + +The Code Owner for `terms.md` would be `@legal-team`. + +If you use sections, the last pattern matching the file or directory for each section is used. +For example, in a `CODEOWNERS` file using sections: + +```plaintext +[README Owners] +README.md @user1 @user2 +internal/README.md @user4 + +[README other owners] +README.md @user3 +``` + +The Code Owners for the `README.md` in the root directory are `@user1`, `@user2`, +and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. + +Only one CODEOWNERS pattern per section is matched to a file path. + +### Organize Code Owners by putting them into sections + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed. + +You can organize Code Owners by putting them into named sections. + +You can use sections for shared directories, so that multiple +teams can be reviewers. + +To add a section to the `CODEOWNERS` file, enter a section name in brackets, +followed by the files or directories, and users, groups, or subgroups: + +```plaintext +[README Owners] +README.md @user1 @user2 +internal/README.md @user2 +``` + +Each Code Owner in the merge request widget is listed under a label. +The following image shows a **Groups** and **Documentation** section: + + + +#### Set default owner for a section + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `codeowners_default_owners`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115888) in GitLab 15.11. Feature flag `codeowners_default_owners` removed. + +If multiple file paths inside a section share the same ownership, define a default +Code Owner for the section. All paths in that section inherit this default, unless +you override the section default on a specific line. + +Default owners are applied when specific owners are not specified for file paths. +Specific owners defined beside the file path override default owners: + +```plaintext +[Documentation] @docs-team +docs/ +README.md + +[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +In this example: + +- `@docs-team` owns all items in the `Documentation` section. +- `@database-team` owns all items in the `Database` section except + `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. + +To combine the syntax for default owners with [optional sections](#make-a-code-owners-section-optional) +and required approvals, place default owners at the end: + +```plaintext +[Documentation][2] @docs-team +docs/ +README.md + +^[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +#### Sections with duplicate names + +If multiple sections have the same name, they are combined. +Also, section headings are not case-sensitive. For example: + +```plaintext +[Documentation] +ee/docs/ @docs +docs/ @docs + +[Database] +README.md @database +model/db/ @database + +[DOCUMENTATION] +README.md @docs +``` + +This code results in three entries under the **Documentation** section header, and two +entries under **Database**. The entries defined under the sections **Documentation** and +**DOCUMENTATION** are combined, using the case of the first section. + +#### Make a Code Owners section optional + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. + +You can designate optional sections in your Code Owners file. Prepend the +section name with the caret `^` character to treat the entire section as optional. +Optional sections enable you to designate responsible parties for various parts +of your codebase, but not require approval from them. This approach provides +a more relaxed policy for parts of your project that are frequently updated, +but don't require stringent reviews. + +In this example, the `[Go]` section is optional: + +```plaintext +[Documentation] +*.md @root + +[Ruby] +*.rb @root + +^[Go] +*.go @root +``` + +The optional Code Owners section displays in merge requests under the **Approval Rules** area: + + + +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the section is required. + +Optional sections in the `CODEOWNERS` file are treated as optional only +when changes are submitted by using merge requests. If a change is submitted directly +to the protected branch, approval from Code Owners is still required, even if the +section is marked as optional. + +### Require multiple approvals from Code Owners + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335451) in GitLab 15.9. + +You can require multiple approvals for the Code Owners sections under the Approval Rules area in merge requests. +Append the section name with a number `n` in brackets. This requires `n` approvals from the Code Owners in this section. +Please note valid entries for `n` are integers `≥ 1`. `[1]` is optional as it is the default. Invalid values for `n` are treated as `1`. + +WARNING: +[Issue #384881](https://gitlab.com/gitlab-org/gitlab/-/issues/385881) proposes changes +to the behavior of this setting. Do not intentionally set invalid values. They may +become valid in the future, and cause unexpected behavior. + +Please confirm you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals will be optional. + +In this example, the `[Documentation]` section requires 2 approvals: + +```plaintext +[Documentation][2] +*.md @tech-writer-team + +[Ruby] +*.rb @dev-team +``` + +The `Documentation` Code Owners section under the **Approval Rules** area displays 2 approvals are required: + + + +### Allowed to Push + +The Code Owner approval and protected branch features do not apply to users who +are **Allowed to push**. + +## Technical Resources + +[Code Owners development guidelines](../../../development/code_owners/index.md) + +## Troubleshooting + +For more information about how the Code Owners feature handles errors, see the +[Code Owners reference](reference.md). + +### Approvals shown as optional + +A Code Owner approval rule is optional if any of these conditions are true: + +- The user or group are not a member of the project. Code Owners [cannot inherit 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). + +### Approvals do not show + +Code Owner approval rules only update when the merge request is created. +If you update the `CODEOWNERS` file, close the merge request and create a new one. + +### User not shown as possible approver + +A user might not show as an approver on the Code Owner merge request approval rules +if any of these conditions are true: + +- A rule prevents the specific user from approving the merge request. + Check the project [merge request approval](../merge_requests/approvals/settings.md#edit-merge-request-approval-settings) settings. +- A Code Owner group has a visibility of **private**, and the current user is not a + member of the Code Owner group. +- Current user is an external user who does not have permission to the internal Code Owner group. + +### Approval rule is invalid. GitLab has approved this rule automatically to unblock the merge request + +This message may appear if an approval rule uses a Code Owner that is not a direct member of the project. +Check that the group or user has been invited to the project. diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md new file mode 100644 index 00000000000..dbb39fafabe --- /dev/null +++ b/doc/user/project/codeowners/reference.md @@ -0,0 +1,371 @@ +--- +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 +--- + +# Code Owners syntax and error handling **(PREMIUM)** + +This page describes the syntax and error handling used in Code Owners files, +and provides an example file. + +## Code Owners syntax + +### Comments + +Lines beginning with `#` are ignored: + +```plaintext +# This is a comment +``` + +### Sections + +Sections are groups of entries. A section begins with a section heading in square brackets, followed by the entries. + +```plaintext +[Section name] +/path/of/protected/file.rb @username +/path/of/protected/dir/ @group +``` + +#### Section headings + +Section headings must always have a name. They can also be made optional, or +require a number of approvals. A list of default owners can be added to the section heading line. + +```plaintext +# Required section +[Section name] + +# Optional section +^[Section name] + +# Section requiring 5 approvals +[Section name][5] + +# Section with @username as default owner +[Section name] @username + +# Section with @group and @subgroup as default owners and requiring 2 approvals +[Section name][2] @group @subgroup +``` + +#### Section names + +Sections names are defined between square brackets. Section names are not case-sensitive. +[Sections with duplicate names](index.md#sections-with-duplicate-names) are combined. + +```plaintext +[Section name] +``` + +#### Required sections + +Required sections do not include `^` before the [section name](#section-names). + +```plaintext +[Required section] +``` + +#### Optional sections + +Optional sections include a `^` before the [section name](#section-names). + +```plaintext +^[Optional section] +``` + +#### Sections requiring multiple approvals + +Sections requiring multiple approvals include the number of approvals in square brackets after the [section name](#section-names). + +```plaintext +[Section requiring 5 approvals][5] +``` + +NOTE: +Optional sections ignore the number of approvals required. + +#### Sections with default owners + +You can define a default owner for the entries in a section by appending the owners to the [section heading](#section-headings). + +```plaintext +# Section with @username as default owner +[Section name] @username + +# Section with @group and @subgroup as default owners and requiring 2 approvals +[Section name][2] @group @subgroup +``` + +### Code Owner entries + +Each Code Owner entry includes a path followed by one or more owners. + +```plaintext +README.md @username1 +``` + +NOTE: +If an entry is duplicated in a section, [the last entry is used from each section.](index.md#define-more-specific-owners-for-more-specifically-defined-files-or-directories) + +### Relative paths + +If a path does not start with a `/`, the path is treated as if it starts with +a [globstar](#globstar-paths). `README.md` is treated the same way as `/**/README.md`: + +```plaintext +# This will match /README.md, /internal/README.md, /app/lib/README.md +README.md @username + +# This will match /internal/README.md, /docs/internal/README.md, /docs/api/internal/README.md +internal/README.md +``` + +### Absolute paths + +If a path starts with a `/` it matches the root of the repository. + +```plaintext +# Matches only the file named `README.md` in the root of the repository. +/README.md + +# Matches only the file named `README.md` inside the `/docs` directory. +/docs/README.md +``` + +### Directory paths + +If a path ends with `/`, the path matches any file in the directory. + +```plaintext +# This is the same as `/docs/**/*` +/docs/ +``` + +### Wildcard paths + +Wildcards can be used to match one of more characters of a path. + +```plaintext +# Any markdown files in the docs directory +/docs/*.md @username + +# /docs/index file of any filetype +# For example: /docs/index.md, /docs/index.html, /docs/index.xml +/docs/index.* @username + +# Any file in the docs directory with 'spec' in the name. +# For example: /docs/qa_specs.rb, /docs/spec_helpers.rb, /docs/runtime.spec +/docs/*spec* @username + +# README.md files one level deep within the docs directory +# For example: /docs/api/README.md +/docs/*/README.md @username +``` + +### Globstar paths + +Globstars (`**`) can be used to match zero or more directories and subdirectories. + +```plaintext +# This will match /docs/index.md, /docs/api/index.md, /docs/api/graphql/index.md +/docs/**/index.md +``` + +### Entry owners + +Entries must be followed by one or more owner. These can be groups, subgroups, +and users. Order of owners is not important. + +```plaintext +/path/to/entry.rb @group +/path/to/entry.rb @group/subgroup +/path/to/entry.rb @user +/path/to/entry.rb @group @group/subgroup @user +``` + +#### Groups as entry owners + +Groups and subgroups can be owners of an entry. +Each entry can be owned by [one or more owners](#entry-owners). +For more details see the [Groups as Code Owners section](index.md#groups-as-code-owners). + +```plaintext +/path/to/entry.rb @group +/path/to/entry.rb @group/subgroup +/path/to/entry.rb @group @group/subgroup +``` + +### Users as entry owners + +Users can be owners of an entry. Each entry can be owned by +[one or more owners](#entry-owners). + +```plaintext +/path/to/entry.rb @username1 +/path/to/entry.rb @username1 @username2 +``` + +## Error handling in Code Owners + +### Entries with spaces + +Paths containing whitespace must be escaped with backslashes: `path\ with\ spaces/*.md`. +Without the backslashes, the path after the first whitespace is parsed as an owner. +GitLab the parses `folder with spaces/*.md @group` into +`path: "folder", owners: " with spaces/*.md @group"`. + +### Unparsable sections + +If a section heading cannot be parsed, the section is: + +1. Parsed as an entry. +1. Added to the previous section. +1. If no previous section exists, the section is added to the default section. + +For example, this file is missing a square closing bracket: + +```plaintext +* @group + +[Section name +docs/ @docs_group +``` + +GitLab recognizes the heading `[Section name` as an entry. The default section includes 3 rules: + +- Default section + - `*` owned by `@group` + - `[Section` owned by `name` + - `docs/` owned by `@docs_group` + +This file contains an unescaped space between the words `Section` and `name`. +GitLab recognizes the intended heading as an entry: + +```plaintext +[Docs] +docs/**/* @group + +[Section name]{2} @group +docs/ @docs_group +``` + +The `[Docs]` section then includes 3 rules: + +- `docs/**/*` owned by `@group` +- `[Section` owned by `name]{2} @group` +- `docs/` owned by `@docs_group` + +### Malformed owners + +Each entry must contain 1 or more owners to be valid, malformed owners are ignored. +For example `/path/* @group user_without_at_symbol @user_with_at_symbol` +is owned by `@group` and `@user_with_at_symbol`. + +### Inaccessible or incorrect owners + +Inaccessible or incorrect owners are ignored. For example, if `@group`, `@username`, +and `example@gitlab.com` are accessible on the project and we create an entry: + +```plaintext +* @group @grou @username @i_left @i_dont_exist example@gitlab.com invalid@gitlab.com +``` + +GitLab ignores `@grou`, `@i_left`, `@i_dont_exist`, and `invalid@gitlab.com`. + +For more information on who is accessible, see [Groups as Code Owners](index.md#groups-as-code-owners). + +### Zero owners + +If an entry includes no owners, or zero [accessible owners](#inaccessible-or-incorrect-owners) +exist, the entry is invalid. Because this rule can never be satisfied, GitLab +auto-approves it in merge requests. + +NOTE: +When a protected branch has `Require code owner approval` enabled, rules with +zero owners are still honored. + +### Less than 1 required approval + +When [defining the number of approvals](index.md#require-multiple-approvals-from-code-owners) for a section, +the minimum number of approvals is `1`. Setting the number of approvals to +`0` results in GitLab requiring one approval. + +## Example `CODEOWNERS` file + +```plaintext +# This is an example of a CODEOWNERS file. +# Lines that start with `#` are ignored. + +# app/ @commented-rule + +# Specify a default Code Owner by using a wildcard: +* @default-codeowner + +# Specify multiple Code Owners by using a tab or space: +* @multiple @code @owners + +# Rules defined later in the file take precedence over the rules +# defined before. +# For example, for all files with a filename ending in `.rb`: +*.rb @ruby-owner + +# Files with a `#` can still be accessed by escaping the pound sign: +\#file_with_pound.rb @owner-file-with-pound + +# Specify multiple Code Owners separated by spaces or tabs. +# In the following case the CODEOWNERS file from the root of the repo +# has 3 Code Owners (@multiple @code @owners): +CODEOWNERS @multiple @code @owners + +# You can use both usernames or email addresses to match +# users. Everything else is ignored. For example, this code +# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the +# owner for the LICENSE file: +LICENSE @legal this_does_not_match janedoe@gitlab.com + +# Use group names to match groups, and nested groups to specify +# them as owners for a file: +README @group @group/with-nested/subgroup + +# End a path in a `/` to specify the Code Owners for every file +# nested in that directory, on any level: +/docs/ @all-docs + +# End a path in `/*` to specify Code Owners for every file in +# a directory, but not nested deeper. This code matches +# `docs/index.md` but not `docs/projects/index.md`: +/docs/* @root-docs + +# Include `/**` to specify Code Owners for all subdirectories +# in a directory. This rule matches `docs/projects/index.md` or +# `docs/development/index.md` +/docs/**/*.md @root-docs + +# This code makes matches a `lib` directory nested anywhere in the repository: +lib/ @lib-owner + +# This code match only a `config` directory in the root of the repository: +/config/ @config-owner + +# If the path contains spaces, escape them like this: +path\ with\ spaces/ @space-owner + +# Code Owners section: +[Documentation] +ee/docs @docs +docs @docs + +# Use of default owners for a section. In this case, all files (*) are owned by +the dev team except the README.md and data-models which are owned by other teams. +[Development] @dev-team +* +README.md @docs-team +data-models/ @data-science-team + +# This section is combined with the previously defined [Documentation] section: +[DOCUMENTATION] +README.md @docs +``` diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 5adc678e942..09a443614d0 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 362d5826124..92fdc59dde3 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -86,6 +86,7 @@ Prerequisites: 1. Complete the fields. 1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** checkbox. +1. Optional. Update the **Expiration date**. A project deploy key is enabled when it is created. You can modify only a project deploy key's name and permissions. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 23cfa7cc500..a81ccd043bd 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index eeaf5d799d2..7dee92f0c29 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -16,7 +16,7 @@ You might want to use these templates: - For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - For every issue or merge request for a specific project, so the layout is consistent. -- For a [Service Desk email template](service_desk.md#new-service-desk-issues). +- For a [Service Desk email template](service_desk.md#use-a-custom-template-for-service-desk-issues). For description templates to work, they must be: @@ -156,7 +156,7 @@ To set a default description template for merge requests, either: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Merge requests**. - 1. In the **Merge commit message template** section, fill in **Default description template for merge requests**. + 1. In the **Default description template for merge requests** section, fill in the text area. 1. Select **Save changes**. To set a default description template for issues, either: @@ -167,9 +167,9 @@ To set a default description template for issues, either: - Users on GitLab Premium and higher: set the default template in project settings: 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings**. - 1. Expand **Default issue template**. - 1. Fill in the **Default description template for issues** text area. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **Default description template for issues**. + 1. Fill in the text area. 1. Select **Save changes**. Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index b83feda0c96..e4486938edf 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -58,7 +58,7 @@ git-lfs --version ``` If it doesn't recognize this command, you must install it. There are -several [installation methods](https://git-lfs.github.com/) that you can +several [installation methods](https://git-lfs.com/) that you can choose according to your OS. To install it with Homebrew: ```shell diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 9937ea956c4..28ad1f22b8d 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -132,5 +132,4 @@ Consider memory constraints on the system before deciding to increase `SIDEKIQ_M ## Related topics -For information on automating user, group, and project import API calls, see -[Automate group and project import](index.md#automate-group-and-project-import). +- [Automate group and project import](index.md#automate-group-and-project-import) diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 00aebb75a50..99221daf750 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Migrating from CVS **(FREE)** [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version -control system similar to [SVN](svn.md). +control system similar to [SVN](https://subversion.apache.org/). ## CVS vs Git diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index a1d94d81e69..657343261d9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -7,7 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from GitHub to GitLab **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10, you no longer need to add any users to the parent group in GitLab to successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** branch protection rule. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378267) in GitLab 15.11, GitLab instances behind proxies no longer require `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains). You can import your GitHub projects from either GitHub.com or GitHub Enterprise. Importing projects does not migrate or import any types of groups or organizations from GitHub to GitLab. @@ -52,17 +54,16 @@ To import projects from GitHub: are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you may have to add it on existing accounts. -See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional -prerequisites for those imports. +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). ### Importing from GitHub Enterprise to self-managed GitLab If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable the [GitHub integration](../../../integration/github.md). -- If GitLab is behind an HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains) - with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue - [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). +- For GitLab 15.10 and earlier, you must add `github.com` and `api.github.com` entries in the + [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains). ### Importing from GitHub.com to self-managed GitLab @@ -80,10 +81,9 @@ Before you begin, ensure that any GitHub user you want to map to a GitLab user h [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). -We do not recommend this method, as it does not associate all user activity (such as issues and pull requests) with matching GitLab users. -User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with -the user account that is performing the import. +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 @@ -101,9 +101,7 @@ Prerequisite: - Authentication token with administrator access. -Using a personal access token to import projects is not recommended. If you are a GitLab.com user, -you can use a personal access token to import your project from GitHub, but this method cannot -associate all user activity (such as issues and pull requests) with matching GitLab users. +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. @@ -255,10 +253,7 @@ When they are imported, supported GitHub branch protection rules are mapped to e | **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | | **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | | **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | -| **Require a pull request before merging - Allow specified actors to bypass required pull requests** (1) | List of users in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a Premium license, the list of users that are allowed to push is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | - -1. To successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** rule, you must add to the parent group in GitLab - the users that are allowed to bypass required pull requests before you begin importing. +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue @@ -282,7 +277,7 @@ These GitHub collaborator roles are mapped to these GitLab [member roles](../../ GitHub Enterprise Cloud has [custom repository roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles). -These roles aren't supported and cause partial imports. +These roles aren't supported and cause partially completed imports. To import GitHub collaborators, you must have at least the Write role on the GitHub project. Otherwise collaborators import is skipped. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index c00709d9697..9cb3ff75d5d 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -33,7 +33,5 @@ When the importer is done, a new GitLab project is created with your imported da ## Related topics -- To automate user, group, and project import API calls, see - [Automate group and project import](index.md#automate-group-and-project-import). -- To import Wiki and merge request data to your new instance, - see [exporting a project](../settings/import_export.md#export-a-project-and-its-data). +- [Automate group and project import](index.md#automate-group-and-project-import) +- [Export a project](../settings/import_export.md#export-a-project-and-its-data) diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 8c95e68e1f2..ebfe421fd02 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -24,7 +24,7 @@ For any type of source and target, you can migrate GitLab projects: - When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in - [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready for production use. + [Beta](../../../policy/alpha-beta-support.md#beta). The feature is not ready for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. @@ -32,13 +32,27 @@ If you only need to migrate Git repositories, you can [import each project by UR import issues and merge requests this way. To retain metadata like issues and merge requests, either: - [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). - This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. + This feature is in [Beta](../../../policy/alpha-beta-support.md#beta). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). When migrating from self-managed to GitLab.com, user associations (such as comment author) are changed to the user who is importing the projects. +## Security + +Only import projects from sources you trust. If you import a project from an untrusted source, +an attacker could steal your sensitive data. For example, an imported project +with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate group CI/CD variables. + +GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. Scroll to **Import sources**. +1. Clear checkboxes for importers that are not required. + ## Available project importers You can import projects from: @@ -65,7 +79,7 @@ You can then [connect your external repository to get CI/CD benefits](../../../c GitLab can not automatically migrate Subversion repositories to Git. Converting Subversion repositories to Git can be difficult, but several tools exist including: -- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and simple repositories. +- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and basic repositories. - [`reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html), for larger and more complex repositories. ## Migrate using the API @@ -82,10 +96,9 @@ over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve an ## Migrate between two self-managed GitLab instances -To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's -best to [back up](../../../raketasks/backup_restore.md) -the existing instance and restore it on the new instance. For example, this is useful when migrating -a self-managed instance from an old server to a new server. +To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, +you should [back up](../../../raketasks/backup_restore.md) +the existing instance and restore it on the new instance. For example, you could use this method to migrate a self-managed instance from an old server to a new server. The backups produced don't depend on the operating system running GitLab. You can therefore use the restore method to switch between different operating system distributions or versions, as long @@ -154,8 +167,20 @@ GitLab from: For more information, see: +- Information on paid GitLab [migration services](https://about.gitlab.com/services/migration/). - [Quick Start](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start). - [Frequently Asked Migration Questions](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/customer/famq.md), including settings that need checking afterwards and other limitations. For support, customers must enter into a paid engagement with GitLab Professional Services. + +## Troubleshooting + +### Imported repository is missing branches + +If an imported repository does not contain all branches of the source repository: + +1. Set the [environment variable](../../../administration/logs/index.md#override-default-log-level) `IMPORT_DEBUG=true`. +1. Retry the import with a [different group, subgroup, or project name](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#re-import-projects-from-external-providers). +1. If some branches are still missing, inspect [`importer.log`](../../../administration/logs/index.md#importerlog) + (for example, with [`jq`](../../../administration/logs/log_parsing.md#parsing-gitlab-railsimporterlog)). diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 8a2dbba1343..d8784db5e29 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -15,7 +15,7 @@ and will be removed in GitLab 16.0. WARNING: The Phabricator task importer is in -[beta](../../../policy/alpha-beta-support.md#beta-features) and is +[Beta](../../../policy/alpha-beta-support.md#beta) and is [**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports only an issue's title and description. The GitLab project created during the import process contains only issues, and the associated repository is disabled. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md deleted file mode 100644 index c9abc0f459d..00000000000 --- a/doc/user/project/import/svn.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md#import-from-subversion' -remove_date: '2023-03-15' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-03-15>. --> -<!-- 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/index.md b/doc/user/project/index.md index da0546b85e6..1512039fb25 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -179,8 +179,6 @@ Your project's visibility is set to **Private** by default. To change project vi ## Related topics -- For a list of words that you cannot use as project names, see - [reserved project and group names](../../user/reserved_names.md). -- For a list of characters that you cannot use in project and group names, see - [limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). -- [Manage projects](working_with_projects.md). +- [Reserved project and group names](../../user/reserved_names.md) +- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) +- [Manage projects](working_with_projects.md) diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 12039a70d0e..419849ae5a0 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -125,7 +125,7 @@ For example: ### Builds not triggered If builds are not triggered, ensure you entered the right GitLab IP address in -Bamboo under **Trigger IP addresses**. Also check [service hook logs](index.md#troubleshooting-integrations) for request failures. +Bamboo under **Trigger IP addresses**. Also check [integration webhook logs](index.md#troubleshooting) for request failures. ### Advanced Atlassian Bamboo features not available in GitLab UI diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 2933203c593..aeb8871d257 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -57,4 +57,4 @@ internal issue tracker, the internal issue is linked. ## Troubleshooting -To see recent service hook deliveries, check [service hook logs](index.md#troubleshooting-integrations). +For recent integration webhook deliveries, check [integration webhook logs](index.md#troubleshooting). diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 649b0c51818..e23896347ff 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -18,6 +18,10 @@ integrations on GitLab.com. ## Installation +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). +Although functionality has not changed, you should [reinstall the app](#update-the-gitlab-for-slack-app). + ### Through the Slack App Directory To enable the GitLab for Slack app for your workspace, @@ -43,8 +47,8 @@ To enable the GitLab integration for your Slack workspace: 1. Select **Install GitLab for Slack app**. 1. Select **Allow** on Slack's confirmation screen. -You can also select **Reinstall GitLab for Slack app** to update the app in your Slack workspace -to the latest version. See [Version history](#version-history) for details. +To update the app in your Slack workspace to the latest version, +you can also select **Reinstall GitLab for Slack app**. ## Slash commands @@ -63,6 +67,7 @@ Replace `<project>` with the project full path, or create a shorter [project ali | `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | | `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. | | `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. | +| `/gitlab incident declare` | **Beta** Opens modal to [create a new incident](../../../operations/incident_management/slack.md). | ### The deploy slash command @@ -191,8 +196,3 @@ If you're not receiving notifications to a Slack channel, ensure: ### 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). - -## Version history - -In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). -Although there is no change in functionality, you should [reinstall the app](#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 553e82be382..e83602186f3 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -6,10 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Google Play **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `google_play_integration`. On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389611) in GitLab 15.11. Feature flag `google_play_integration` removed. With the Google Play integration, you can configure your CI/CD pipelines to connect to the [Google Play Console](https://play.google.com/console) to build and release apps for Android devices. @@ -27,11 +25,12 @@ To enable the Google Play integration in GitLab: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Google Play**. -1. In **Enable Integration**, select the **Active** checkbox. +1. In **Enable integration**, select the **Active** checkbox. +1. In **Package name**, enter the package name of the app (for example, `com.gitlab.app_name`). 1. In **Service account key (.JSON)**, drag or upload your key file. 1. Select **Save changes**. -After you enable the integration, the global variable `$SUPPLY_JSON_KEY_DATA` is created for CI/CD use. +After you enable the integration, the global variables `$SUPPLY_PACKAGE_NAME` and `$SUPPLY_JSON_KEY_DATA` are created for CI/CD use. ### CI/CD variable security diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 9ff6ad2a237..e5d70dc5790 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -103,9 +103,16 @@ supported by `push_hooks` and `tag_push_hooks` events aren't executed. You can change the number of supported branches or tags by changing the [`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). -## Troubleshooting integrations +## Contribute to integrations + +If you're interested in developing a new native integration for GitLab, see: + +- [Integrations development guidelines](../../../development/integrations/index.md) +- [GitLab Developer Portal](https://developer.gitlab.com) + +## Troubleshooting -Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [Troubleshooting webhooks](webhooks.md#troubleshoot-webhooks). +Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [webhook troubleshooting](webhooks.md#troubleshooting). ### `Test Failed. Save Anyway` error @@ -115,7 +122,3 @@ push data to build the test payload, and there are no push events in the project To resolve this error, initialize the repository by pushing a test file to the project and set up the integration again. - -## Contribute to integrations - -To add a new integration, see the [Integrations development guide](../../../development/integrations/index.md). diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index fc5d4d3cc80..fc448382cb4 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -58,4 +58,4 @@ GitLab to send the notifications: ## Related topics -- [Setting up an incoming webhook on Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). +- [Setting up an incoming webhook on Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook) diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md index bd14021ab1c..c5931928626 100644 --- a/doc/user/project/integrations/mlflow_client.md +++ b/doc/user/project/integrations/mlflow_client.md @@ -4,33 +4,32 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# MLFlow Client Integration **(FREE)** +# MLFlow client integration **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.6 as an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. -DISCLAIMER: -MLFlow Client Integration is an experimental feature being developed by the Incubation Engineering Department, -and will receive significant changes over time. +NOTE: +Model experiment tracking is an [experimental feature](../../../policy/alpha-beta-support.md). +Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. [MLFlow](https://mlflow.org/) is one of the most popular open source tools for Machine Learning Experiment Tracking. -GitLabs works as a backend to the MLFlow Client, [logging experiments](../ml/experiment_tracking/index.md). +GitLab works as a backend to the MLFlow Client, [logging experiments](../ml/experiment_tracking/index.md). Setting up your integrations requires minimal changes to existing code. GitLab plays the role of proxy server, both for artifact storage and tracking data. It reflects the MLFlow [Scenario 5](https://www.mlflow.org/docs/latest/tracking.html#scenario-5-mlflow-tracking-server-enabled-with-proxied-artifact-storage-access). -## Enable MLFlow Client Integration - -Complete this task to enable MLFlow Client Integration. +## Enable MLFlow client integration Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) for the project, with minimum access level of `api`. - The project ID. To find the project ID, on the top bar, select **Main menu > Projects** and find your project. On the left sidebar, select **Settings > General**. -1. Set the tracking URI and token environment variables on the host that runs the code (your local environment, CI pipeline, or remote host). +To enable MLFlow client integration: - For example: +1. Set the tracking URI and token environment variables on the host that runs the code. + This can be your local environment, CI pipeline, or remote host. For example: ```shell export MLFLOW_TRACKING_URI="http://<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow" @@ -39,43 +38,48 @@ Prerequisites: 1. If your training code contains the call to `mlflow.set_tracking_uri()`, remove it. -When running the training code, MLFlow will create experiments, runs, log parameters, metrics, +When running the training code, MLFlow creates experiments, runs, 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, -that can be explored by selecting an experiment. +After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. +Runs are registered as: -## Limitations +- Model Candidates, which can be explored by selecting an experiment. +- Tags, which are registered as metadata. -- The API GitLab supports is the one defined at MLFlow version 1.28.0. -- API endpoints not listed above are not supported. -- During creation of experiments and runs, tags are ExperimentTags and RunTags are stored, even though they are not displayed. -- MLFlow Model Registry is not supported. +## Supported MlFlow client methods and caveats -## Supported methods and caveats - -This is a list of methods we support from the MLFlow client. Other methods might be supported but were not +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). -### `set_experiment()` - -Accepts both `experiment_name` and `experiment_id` - -### `start_run()` - -- Nested runs have not been tested. -- `run_name` is not supported +| Method | Supported | Version Added | Comments | +|--------------------------|------------------|----------------|----------| +| `get_experiment` | Yes | 15.11 | | +| `get_experiment_by_name` | Yes | 15.11 | | +| `set_experiment` | Yes | 15.11 | | +| `get_run` | Yes | 15.11 | | +| `start_run` | Yes | 15.11 | | +| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. +| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. +| `log_batch` | Yes | 15.11 | | +| `log_metric` | Yes | 15.11 | | +| `log_metrics` | Yes | 15.11 | | +| `log_param` | Yes | 15.11 | | +| `log_params` | Yes | 15.11 | | +| `log_figure` | Yes | 15.11 | | +| `log_image` | Yes | 15.11 | | +| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. +| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. +| `set_tag` | Yes | 15.11 | | +| `set_tags` | Yes | 15.11 | | +| `set_terminated` | Yes | 15.11 | | +| `end_run` | Yes | 15.11 | | +| `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. -### `log_param()`, `log_params()`, `log_metric()`, `log_metrics()` - -Work as defined by the documentation - -### `log_artifact()`, `log_artifacts()` - -`artifact_path` must be empty string. - -### `log_model()` +## Limitations -This is an experimental method in MLFlow, and partial support is offered. It stores the model artifacts, but does -not log the model information. The `artifact_path` parameter must be set to `''`, because Generic Packages do not support folder -structure. +- The API GitLab supports is the one defined at MLFlow version 1.28.0. +- API endpoints 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/integrations/slack.md b/doc/user/project/integrations/slack.md index 09e7189d4f5..6806b724ac2 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -3,14 +3,16 @@ stage: Manage group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- +<!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> -# Slack notifications **(FREE)** +# Slack notifications (deprecated) **(FREE)** WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) on GitLab.com -in GitLab 15.9 and is [planned for removal](https://gitlab.com/groups/gitlab-org/-/epics/8673). -For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. -For self-managed GitLab instances, you can continue to use this feature. +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 @@ -150,3 +152,5 @@ p.each do |project| project.slack_integration.update!(:active, false) end ``` + +<!--- end_remove --> diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md index 0f63b4a48db..9625387ad1e 100644 --- a/doc/user/project/integrations/squash_tm.md +++ b/doc/user/project/integrations/squash_tm.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Squash TM integration **(FREE SELF)** +# Squash TM **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337855) in GitLab 15.10. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 53177004888..f0213e9bb48 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -861,6 +861,7 @@ Payload example: "visibility_level":20, "path_with_namespace":"gitlabhq/gitlab-test", "default_branch":"master", + "ci_config_path":"", "homepage":"http://example.com/gitlabhq/gitlab-test", "url":"http://example.com/gitlabhq/gitlab-test.git", "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", @@ -885,7 +886,10 @@ Payload example: "title": "MS-Viewport", "created_at": "2013-12-03T17:23:34Z", "updated_at": "2013-12-03T17:23:34Z", + "last_edited_at": "2013-12-03T17:23:34Z", + "last_edited_by_id": 1, "milestone_id": null, + "state_id": 1, "state": "opened", "blocking_discussions_resolved": true, "work_in_progress": false, @@ -893,6 +897,11 @@ Payload example: "merge_status": "unchecked", "target_project_id": 14, "description": "", + "total_time_spent": 1800, + "time_change": 30, + "human_total_time_spent": "30m", + "human_time_change": "30s", + "human_time_estimate": "30m", "url": "http://example.com/diaspora/merge_requests/1", "source": { "name":"Awesome Project", @@ -929,6 +938,7 @@ Payload example: "last_commit": { "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "message": "fixed readme", + "title": "Update file README.md", "timestamp": "2012-01-03T23:36:29+02:00", "url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "author": { @@ -997,7 +1007,15 @@ Payload example: "type": "ProjectLabel", "group_id": 41 }] - } + }, + "last_edited_at": { + "previous": null, + "current": "2023-03-15 00:00:10 UTC" + }, + "last_edited_by_id": { + "previous": null, + "current": 3278533 + }, }, "assignees": [ { @@ -1074,7 +1092,8 @@ Payload example: "message": "adding an awesome page to the wiki", "slug": "awesome", "url": "http://example.com/root/awesome-project/-/wikis/awesome", - "action": "create" + "action": "create", + "diff_url": "http://example.com/root/awesome-project/-/wikis/home/diff?version_id=78ee4a6705abfbff4f4132c6646dbaae9c8fb6ec" } } ``` @@ -1392,6 +1411,7 @@ Payload example: "build_started_at": null, "build_finished_at": null, "build_duration": null, + "build_queued_duration": 1095.588715, // duration in seconds "build_allow_failure": false, "build_failure_reason": "script_failure", "retries_count": 2, // the second retry of this job diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 1511e37e31e..1c65ab78ee0 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -99,7 +99,7 @@ You can define URL variables directly using the REST API. ## Configure your webhook receiver endpoint Webhook receiver endpoints should be fast and stable. -Slow and unstable receivers can be [disabled automatically](#failing-webhooks) to ensure system reliability. Webhooks that fail can lead to retries, [which cause duplicate events](#webhook-fails-or-multiple-webhook-requests-are-triggered). +Slow and unstable receivers can be [disabled automatically](#failing-webhooks) to ensure system reliability. Webhooks that fail might lead to [duplicate events](#webhook-fails-or-multiple-webhook-requests-are-triggered). Endpoints should follow these best practices: @@ -129,18 +129,17 @@ FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. On GitLab.com, this feature is available. -If a webhook fails repeatedly, it may be disabled automatically. +Project or group webhooks that fail four consecutive times are automatically disabled. -Webhooks that return response codes in the `5xx` range are understood to be failing +Project or group webhooks that return response codes in the `5xx` range are understood to be failing intermittently and are temporarily disabled. These webhooks are initially disabled -for 1 minute, which is extended on each retry up to a maximum of 24 hours. +for one minute, which is extended on each subsequent failure up to a maximum of 24 hours. -Webhooks that return response codes in the `4xx` range are understood to be +Project or group webhooks that return response codes in the `4xx` range are understood to be misconfigured and are permanently disabled until you manually re-enable them yourself. -See [Troubleshooting](#troubleshoot-webhooks) for more information on -disabled webhooks and how to re-enable them. +For more information about disabled webhooks, see [troubleshooting](#troubleshooting). ## Test a webhook @@ -151,7 +150,7 @@ For example, to test `push events`, your project should have at least one commit NOTE: Testing is not supported for some types of events for project and groups webhooks. -Read more in [issue 379201](https://gitlab.com/gitlab-org/gitlab/-/issues/379201). +For more information, see [issue 379201](https://gitlab.com/gitlab-org/gitlab/-/issues/379201). Prerequisites: @@ -259,7 +258,7 @@ Image URLs are not rewritten if: ## Events -For more information about supported events for Webhooks, go to [Webhook events](webhook_events.md). +For more information about supported events for webhooks, see [webhook events](webhook_events.md). ## Delivery headers @@ -275,7 +274,7 @@ Webhook requests to your endpoint include the following headers: | `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | -## Troubleshoot webhooks +## Troubleshooting > **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3. @@ -293,8 +292,9 @@ To view the table: 1. Scroll down to the webhooks. 1. Each [failing webhook](#failing-webhooks) has a badge listing it as: - - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. - - **Fails to connect** if it is temporarily disabled and is retrying later. + - **Failed to connect** if it's misconfigured and must be manually re-enabled. + - **Fails to connect** if it's temporarily disabled and is automatically + re-enabled after the timeout limit has elapsed.  @@ -330,8 +330,7 @@ Missing intermediate certificates are common causes of verification failure. ### Webhook fails or multiple webhook requests are triggered -If you are receiving multiple webhook requests, the webhook might have timed out and -been retried. +If you're receiving multiple webhook requests, the webhook might have timed out. GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#other-limits). On self-managed GitLab instances, you can [change the webhook timeout limit](../../../administration/instance_limits.md#webhook-timeout). diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 98017fb5542..ea775119beb 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -53,7 +53,7 @@ the issue board feature. > - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to GitLab Free in 12.1. > - Multiple issue boards per group are available in GitLab Premium. -Multiple issue boards allow for more than one issue board for a given project in GitLab Free or group in GitLab Premium and higher tiers. +Multiple issue boards allow for more than one issue board for a given project in the Free tier or group in the Premium and Ultimate tier. This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -97,9 +97,9 @@ Here are some common use cases for issue boards. For examples of using issue boards along with [epics](../group/epics/index.md), [issue health status](issues/managing_issues.md#health-status), and -[scoped labels](labels.md#scoped-labels) for various Agile frameworks, check: +[scoped labels](labels.md#scoped-labels) for various Agile frameworks, see: -- The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) +- [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) @@ -132,10 +132,17 @@ If you have the labels **Backend**, **Frontend**, **Staging**, and 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>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/2IaMXteKSD4" frameborder="0" allowfullscreen> </iframe> +</figure> + #### Scrum team With multiple issue boards, each team has one board. Now you can move issues through each -part of the process. For instance: **To Do**, **Doing**, and **Done**. +part of the process. For example: **To Do**, **Doing**, and **Done**. #### Organization of topics @@ -207,7 +214,7 @@ Prerequisites: - You must have at least the Reporter role for the project. When an issue is created, the system assigns a relative order value that is greater than the maximum value -of that issue's project or root group. This means the issue will be at the bottom of any issue list that +of that issue's project or root group. This means the issue is at the bottom of any issue list that it appears in. When you visit a board, issues appear ordered in any list. You're able to change @@ -226,6 +233,18 @@ This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, and vice versa. +## Focus mode + +To enable or disable focus mode, in the upper-right corner, select **Toggle focus mode** (**{maximize}**). +In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. + +## Group issue boards + +Accessible at the group navigation level, a group issue board offers the same features as a project-level board. +It can display issues from all projects that fall under the group and its descendant subgroups. + +Users on GitLab Free can use a single group issue board. + ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -245,7 +264,7 @@ This allows you to create unique boards according to your team's need. You can define the scope of your board when creating it or by selecting the **Edit board** button. After a milestone, iteration, assignee, or weight is assigned to an issue board, you can no longer -filter through these in the search bar. In order to do that, you need to remove the desired scope +filter through these in the search bar. To do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. If you don't have editing permission in a board, you're still able to see the configuration by @@ -255,14 +274,6 @@ selecting **View scope**. Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of the configurable issue board feature. -### Focus mode - -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to GitLab Free SaaS in 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Free self-managed in 13.0. - -To enable or disable focus mode, select the **Toggle focus mode** button (**{maximize}**) at the top -right. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. - ### Sum of issue weights **(PREMIUM)** > Moved to GitLab Premium in 13.9. @@ -273,13 +284,6 @@ especially in combination with [assignee lists](#assignee-lists).  -### Group issue boards - -Accessible at the group navigation level, a group issue board offers the same features as a project-level board. -It can display issues from all projects that fall under the group and its descendant subgroups. - -Users on GitLab Free can use a single group issue board. - ### Assignee lists **(PREMIUM)** As in a regular list showing all issues with a chosen label, you can add @@ -601,7 +605,7 @@ eventually pick it up. When they're done, they move it to **Done**, to close the issue. This process can be seen clearly when visiting an issue. With every move -to another list, the label changes and a system note is recorded. +to another list, the label changes and a [system note](system_notes.md) is recorded.  diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 2b302a60d63..79278d1b3ad 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -85,18 +85,21 @@ Learn how to create [merge requests for confidential issues](../merge_requests/c There are two kinds of level access for confidential issues. The general rule is that confidential issues are visible only to members of a project with at -least the Reporter role. However, a guest user can also create +least the **Reporter role**. + +However, a user with the **Guest role** can create confidential issues, but can only view the ones that they created themselves. -Users with the Guest role or non-members can also read the confidential issue if they are assigned to the issue. + +Users with the Guest role or non-members can read the confidential issue if they are assigned to the issue. When a Guest user or non-member is unassigned from a confidential issue, they can no longer view it. -Confidential issues are also hidden in search results for unprivileged users. +Confidential issues are hidden in search results for unprivileged users. For example, here's what a user with the Maintainer role and the Guest role -sees in the project's search results respectively. +sees in the project's search results: -| Maintainer role | Guest role | -|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| +| Maintainer role | Guest role | +|:----------------|:-----------| |  |  | ## Related topics diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index d852ad3262b..05c348acf58 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -1,5 +1,4 @@ --- -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' 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 diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index e0966909b1e..069bc4582c6 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -103,7 +103,7 @@ When bulk editing issues in a group, you can edit the following attributes: ## Move an issue When you move an issue, it's closed and copied to the target project. -The original issue is not deleted. A system note, which indicates +The original issue is not deleted. A [system note](../system_notes.md), which indicates where it came from and went to, is added to both issues. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. @@ -298,7 +298,7 @@ To disable automatic issue closing: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. -1. Expand **Default branch**. +1. Expand **Branch defaults**. 1. Clear the **Auto-close referenced issues on default branch** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 356e4e1b194..02a563f59b5 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -28,12 +28,14 @@ To invite a group to a project, you must be at least one of the following: In addition: -- The group you're inviting must have a more restrictive - [visibility level](../../public_access.md#project-and-group-visibility) - than the project. For example, you can invite: - - A private group to a public project. - - An internal group to a public project. - - A private group to an internal project. +- The [visibility level](../../public_access.md#project-and-group-visibility) of the group you're inviting +must be at least as restrictive as that of the project. For example, you can invite: + - A _private_ group to a _private_ project + - A _private_ group to an _internal_ project. + - A _private_ group to a _public_ project. + - An _internal_ group to an _internal_ project. + - An _internal_ group to a _public_ project. + - A _public_ group to a _public_ project. - The group or subgroup must be in the project's [namespace](../../namespace/index.md). For example, a project in the namespace `group/subgroup01/project`: diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 21e2055cb61..9988cdcddd0 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -3,7 +3,6 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/approvals/index.html' --- # Merge request approvals **(FREE)** @@ -17,7 +16,7 @@ approve merge requests, these approvals are [optional](#optional-approvals). flexibility: - Create required [rules](rules.md) about the number and type of approvers before work can merge. -- Specify a list of users who act as [code owners](../../code_owners.md) for specific files, +- Specify a list of users who act as [code owners](../../codeowners/index.md) for specific files, and require their approval before work can merge. You can configure merge request approvals on a per-project basis, and some approvals can be configured @@ -36,7 +35,7 @@ required approvals before work can merge into your project. You can also extend rules to define what types of users can approve work. Some examples of rules you can create include: - Users with specific permissions can always approve work. -- [Code owners](../../code_owners.md) can approve work for files they own. +- [Code owners](../../codeowners/index.md) can approve work for files they own. - Users with specific permissions can approve work, [even if they don't have merge rights](rules.md#merge-request-approval-segregation-of-duties) to the repository. @@ -102,20 +101,30 @@ Without the approvals, the work cannot merge. Required approvals enable multiple database, for all proposed code changes. - Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), to determine who should review the work. -- Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) +- Require an [approval before merging code that causes test coverage to decline](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule) - Users on GitLab Ultimate can also [require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. ## Invalid rules -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/389905) in GitLab 15.11 [with a flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Disabled by default. -Whenever an approval rule cannot be satisfied, the rule will be displayed as `Invalid`. This applies to the following conditions: +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, +ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. +On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. + +Whenever an approval rule cannot be satisfied, the rule is displayed as `(!) Auto approved`. This applies to the following conditions: - The only eligible approver is the author of the merge request. - No eligible approvers (either groups or users) have been assigned to the approval rule. -These rules will be automatically approved to unblock their respective merge requests. +These rules will be automatically approved (fail-open state) to unblock their respective merge requests, +unless they were created through a security policy. + +Invalid approval rules created through a security policy are presented with `(!) Action Required` +and are not automatically approved (fail-closed state), blocking their respective merge requests. ## Related topics diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 0a5e7c29860..5c0282dd9e0 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -106,6 +106,9 @@ reduces the number of approvals left (the **Approvals** column) for all rules th  +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Multiple Approvers](https://www.youtube.com/watch?v=8JQJ5821FrA). + ## Eligible approvers > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. @@ -158,7 +161,7 @@ approve in these ways: > Moved to GitLab Premium in 13.9. -If you add [code owners](../../code_owners.md) to your repository, the owners of files +If you add [code owners](../../codeowners/index.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: 1. Go to your project and select **Settings > Merge requests**. @@ -241,6 +244,28 @@ approval rule for certain branches: 1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). +## Code coverage check approval + +You can require specific approvals in the case that a merge request would reduce code test +coverage. + +For more information, see [Coverage check approval rule](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule). + +## Security Approvals **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. + +You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. +Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. + +The security approval rules are applied to all merge requests until the pipeline is complete. The application of the +security approval rules prevents users from merging in code before the security scans run. After the pipeline is +complete, the security approval rules are checked to determine if the security approvals are still required. + + + +These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). + ## Troubleshooting ### Approval rule name can't be blank @@ -262,18 +287,3 @@ isn't recognized as a valid Code Owner for the project, nor does it display in t project's **Approvals** list. To fix this problem, add the approval group as a shared group high enough in the shared hierarchy so the project requiring review inherits this group of users. - -## Security Approvals **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. - -You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. -Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. - -The security approval rules are applied to all merge requests until the pipeline is complete. The application of the -security approval rules prevents users from merging in code before the security scans run. Once the pipeline is -complete, the security approval rules are checked to determine if the security approvals are still required. - - - -These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 1ab564c108b..154be8a83bb 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -78,13 +78,13 @@ their own. To do this: it can't be changed at the project level. 1. Select **Save changes**. -Depending on your version of GitLab, [code owners](../../code_owners.md) who commit +Depending on your version of GitLab, [code owners](../../codeowners/index.md) who commit to a merge request may or may not be able to approve the work: -- In GitLab 13.10 and earlier, [code owners](../../code_owners.md) who commit +- In GitLab 13.10 and earlier, code owners who commit to a merge request can approve it, even if the merge request affects files they own. - In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/331548), - [code owners](../../code_owners.md) who commit + code owners who commit to a merge request cannot approve it, when the merge request affects files they own. For more information, see the [official Git documentation](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). @@ -140,7 +140,7 @@ However, approvals are reset if the target branch is changed. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90578) in GitLab 15.3. -If you only want to remove approvals by Code Owners whose files have been changed: +If you only want to remove approvals by Code Owners whose files have been changed when a commit is added: Prerequisite: @@ -153,13 +153,6 @@ To do this: select **Remove approvals by Code Owners if their files changed**. 1. Select **Save changes**. -## Code coverage check approvals - -You can require specific approvals if a merge request would result in a decline in code test -coverage. - -For more information, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). - ## Settings cascading > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index d2676b1bdf0..004d24778b7 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -125,7 +125,7 @@ project, from the GitLab user interface: ## View system notes for cherry-picked commits -When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a system note +When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a [system note](../system_notes.md) to the related merge request thread in the format **{cherry-pick-commit}** `[USER]` **picked the changes into the branch** `[BRANCHNAME]` with commit** `[SHA]` `[DATE]`: diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 307998f697d..edcc5711b98 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -65,7 +65,7 @@ Your branch, merge requests, and commits remain in your private fork. This preve prematurely revealing confidential information. Open a merge request -[from your fork to the upstream repository](../repository/forking_workflow.md#merging-upstream) when: +[from your fork to the upstream repository](../repository/forking_workflow.md#merge-changes-back-upstream) when: - You are satisfied the problem is resolved in your private fork. - You are ready to make the confidential commits public. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 932eec5e631..cc8f8cb2fe6 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -162,9 +162,8 @@ merge commit. Verify it contains no unintended changes and doesn't break your bu ## Related topics -- [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md). -- [Git GUI apps](https://git-scm.com/downloads/guis) to help you visualize the - differences between branches and resolve them. +- [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 diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 4ea549e5986..8a4a61bb80d 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -3,7 +3,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "How to create merge requests in GitLab." -disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- # Creating merge requests **(FREE)** @@ -34,7 +33,8 @@ be associated with a given target branch at a time. 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). +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. NOTE: @@ -50,7 +50,7 @@ instead of immediately creating the merge request. - 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](../settings/index.md#remove-a-fork-relationship). +[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. @@ -58,8 +58,8 @@ The dropdown list contains the options **Create merge request and branch** and * 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. The default template -is `%{id}-%{title}`. Supported variables for branch name templates are `%{id}` and `%{title}`. +The branch name is based on your project's [branch name template](../repository/branches/index.md), +but this value can be changed. When you select **Create branch** in an empty repository project, GitLab performs these actions: @@ -151,9 +151,8 @@ You can create a merge request from your fork to contribute back to the main pro 1. Select **Create merge request**. After your work is merged, if you don't intend to -make any other contributions to the upstream project, you can unlink your -fork from its upstream project. Go to **Settings > Advanced Settings** and -[remove the forking relationship](../settings/index.md#remove-a-fork-relationship). +make any other contributions to the upstream project, you can +[unlink your fork](../repository/forking_workflow.md#unlink-a-fork) from its upstream project. For more information, [see the forking workflow documentation](../repository/forking_workflow.md). diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 62820988701..839f3d17a43 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -3,7 +3,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html' --- # Draft merge requests **(FREE)** diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md deleted file mode 100644 index 4125d8e8fdb..00000000000 --- a/doc/user/project/merge_requests/getting_started.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-03-31' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-03-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 (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/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f760b1b730a..ee7f4e5dfed 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -30,7 +30,7 @@ Learn the various ways to [create a merge request](creating_merge_requests.md). You can view merge requests for your project, group, or yourself. -### View merge requests for a project +### For a project To view all merge requests for a project: @@ -39,7 +39,7 @@ To view all merge requests for a project: Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. -### View merge requests for all projects in a group +### For all projects in a group To view merge requests for all projects in a group: @@ -48,7 +48,7 @@ To view merge requests for all projects in a group: If your group contains subgroups, this view also displays merge requests from the subgroup projects. -### View all merge requests assigned to you +### Assigned to you To view all merge requests assigned to you: @@ -79,12 +79,12 @@ To filter the list of merge requests: 1. Above the list of merge requests, select **Search or filter results...**. 1. From the dropdown list, select the attribute you wish to filter by. Some examples: - - [**By environment or deployment date**](#filter-merge-requests-by-environment-or-deployment-date). + - [**By environment or deployment date**](#by-environment-or-deployment-date). - **ID**: Enter filter `#30` to return only merge request 30. - User filters: Type (or select from the dropdown list) any of these filters to display a list of users: - **Approved-By**, for merge requests already approved by a user. **(PREMIUM)**. - **Approver**, for merge requests that this user is eligible to approve. - (For more information, read about [Code owners](../code_owners.md)). **(PREMIUM)** + (For more information, read about [Code owners](../codeowners/index.md)). **(PREMIUM)** - **Reviewer**, for merge requests reviewed by this user. 1. Select or type the operator to use for filtering the attribute. The following operators are available: @@ -100,7 +100,7 @@ To filter the list of merge requests: GitLab displays the results on-screen, but you can also [retrieve them as an RSS feed](../../search/index.md#retrieve-search-results-as-feed). -### Filter merge requests by environment or deployment date +### By environment or deployment date > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. 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 f0359446b06..102a2ad1c14 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -147,3 +147,11 @@ merge-request-pipeline-job: Instead, use branch (`push`) pipelines or merge request pipelines, when possible. For details on avoiding two pipelines for a single merge request, read the [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines). + +### Merged results pipeline allows merge, despite a failed branch pipeline + +When [the **Pipelines must succeed** setting](#require-a-successful-pipeline-for-merge) +is combined with +[the **Merged results pipelines** feature](../../../ci/pipelines/merged_results_pipelines.md), +failed branch pipeline may be ignored. +[Issue 385841](https://gitlab.com/gitlab-org/gitlab/-/issues/385841) is open to track this. diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 5878873f209..77fd78ee0d0 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -58,7 +58,8 @@ To do this: 1. On the top bar, select **Main menu > Projects** and find your project. 1. If you know the merge request that contains the commit: 1. On the left sidebar, select **Merge requests** and identify your merge request. - 1. Select **Commits**, then select the title of the commit you want to revert. GitLab displays the contents of the commit. + 1. Select **Commits**, then select the title of the commit you want to revert. This displays the commit in the **Changes** tab of your merge request. + 1. Select the commit hash you want to revert. GitLab displays the contents of the commit. 1. If you don't know the merge request the commit originated from: 1. On the left sidebar, select **Repository > Commits**. 1. Select the title of the commit to display full information about the commit. diff --git a/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg Binary files differdeleted file mode 100644 index e8aa4b7c730..00000000000 --- a/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg Binary files differdeleted file mode 100644 index d15f5d53e55..00000000000 --- a/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg Binary files differdeleted file mode 100644 index 3e1e9c20af9..00000000000 --- a/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png Binary files differdeleted file mode 100644 index 170c04542dd..00000000000 --- a/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png Binary files differdeleted file mode 100644 index 80424d1f056..00000000000 --- a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg Binary files differdeleted file mode 100644 index fa8331effdb..00000000000 --- a/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 4bd77c7ebdd..22e95c7e639 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -23,14 +23,14 @@ review merge requests in Visual Studio Code. ## Suggested reviewers **(ULTIMATE SAAS)** -> [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4. +> - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/alpha-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/368356) in GitLab 15.6. +> - Beta designation [removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113058) in GitLab 15.10. GitLab can suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right sidebar.  -This feature is currently in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta) behind a [feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/368356). - For more information, see [Data usage in Suggested Reviewers](data_usage.md). ### Enable suggested reviewers @@ -107,7 +107,7 @@ To download the changes included in a merge request as a patch file: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. 1. Select your merge request. -1. In the upper-right corner, select **Code > Email patches**. +1. In the upper-right corner, select **Code > Patches**. If you know the URL of the merge request, you can also download the patch from the command line by appending `.patch` to the URL. This example downloads the patch @@ -172,7 +172,7 @@ If you have a review in progress, you can also add a comment from the **Overview When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](../approvals/rules.md) -below the name of each suggested reviewer. [Code Owners](../../code_owners.md) are displayed as `Codeowner` without group detail. +below the name of each suggested reviewer. [Code Owners](../../codeowners/index.md) are displayed as `Codeowner` without group detail. This example shows reviewers and approval rules when creating a new merge request: diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 6976d4052e1..9187c5fad44 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -45,28 +45,40 @@ merge request, authored by the user who suggested the changes. > [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/232339) in GitLab 13.11: suggestions in multi-line comments also become multi-line. -Reviewers can also suggest changes to multiple lines with a single suggestion -within merge request diff threads by selecting and dragging selection to all -relevant line numbers or by adjusting the range offsets. The -offsets are relative to the position of the diff thread, and specify the -range to be replaced by the suggestion when it is applied. - - +When you review a merge request diff, you can propose changes to multiple lines (up to 200) +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. + +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 +commented line: + +````markdown +```suggestion:-3+4 + "--talk-name=ca.desrt.dconf", + "--socket=wayland", +``` +```` -In the previous example, the suggestion covers three lines above and four lines -below the commented line. When applied, it would replace from 3 lines _above_ -to 4 lines _below_ the commented line, with the suggested change. +When applied, the suggestion replaces from 3 lines above to 4 lines below the commented line:  -NOTE: 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 suggestion. ## Apply suggestions -The merge request author can apply suggested changes directly from the merge request: +Prerequisites: + +- You must be the author of the merge request, or have at least the Developer role in the project. + +To apply suggested changes directly from the merge request: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** and find your merge request. @@ -143,35 +155,29 @@ For example, to customize the commit message to output ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](../../../../policy/alpha-beta-support.md#alpha-features) with a flag named `batch_suggestions`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. -You can apply multiple suggestions at once to reduce the number of commits added -to your branch to address your reviewers' requests. - -1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: - -  - -1. Add as many additional suggestions to the batch as you wish: +To reduce the number of commits added to your branch, you can apply multiple +suggestions in a single commit. -  - -1. To remove suggestions, select **Remove from batch**: - -  - -1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You - can optionally specify a custom commit message for [batch suggestions](#batch-suggestions) - (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit - message is used. - -  - -WARNING: -Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. For each suggestion you want to apply, and 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**. + + WARNING: + If you apply a batch of suggestions containing changes from multiple authors, + you are credited as the resulting commit's author. If your project is configured + to [prevent approvals from users who add commits](../approvals/settings.md#prevent-approvals-by-users-who-add-commits), you are no longer an eligible + approver for this merge request. + +1. Optional. Provide a custom commit message for [batch suggestions](#batch-suggestions) + (GitLab 14.4 and later) to describe your change. If you don't specify one, + the default commit message is used. ## Related topics diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 9f87f1e2e0d..075716e90c8 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -33,7 +33,14 @@ squash commits and merge commits. ## Set default squash options for a merge request Users with permission to create or edit a merge request can set the default squash options -for a merge request. To do this: +for a merge request. + +Prerequisites: + +- Your project must be [configured](#configure-squash-options-for-a-project) to allow or + encourage squashing. + +To do this: 1. Go to the merge request and select **Edit**. 1. Select or clear the **Squash commits when merge request is accepted** checkbox. @@ -58,6 +65,10 @@ squash the commits as part of the merge process: > - [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/232536) in GitLab 13.8. Feature flag `squash_options` removed. +Prerequisites: + +- You must have at least the Maintainer role for this project. + To configure the default squashing behavior for all merge requests in your project: 1. On the top bar, select **Main menu > Projects** and find your project. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 6a791a17057..4c806086fab 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -3,7 +3,6 @@ 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 -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html' --- # External status checks **(ULTIMATE)** @@ -12,6 +11,8 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/statu > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. > - `failed` status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329636) in GitLab 14.9. +Status checks are API calls to external systems that request the status of an external requirement. + You can create a status check that sends merge request data to third-party tools. When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows can then update the status of merge requests from outside of GitLab. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index e9de780655a..4641af262ca 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -142,7 +142,7 @@ To edit a milestone: 1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. -1. Select **Edit**. +1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**. 1. Edit the title, start date, due date, or description. 1. Select **Save changes**. @@ -158,7 +158,7 @@ To edit a milestone: 1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. -1. Select **Delete**. +1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Delete**. 1. Select **Delete milestone**. ## Promote a project milestone to a group milestone @@ -185,7 +185,7 @@ To promote a project milestone: 1. On the left sidebar, select **Issues > Milestones**. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**) next to the milestone you want to promote. - - Select the milestone title, and then select **Promote**. + - Select the milestone title, and then select **Milestone actions** (**{ellipsis_v}**) > **Promote**. 1. Select **Promote Milestone**. ## Assign a milestone to an issue or merge request diff --git a/doc/user/project/ml/experiment_tracking/img/candidate_v15_11.png b/doc/user/project/ml/experiment_tracking/img/candidate_v15_11.png Binary files differnew file mode 100644 index 00000000000..50bcd1e8479 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/candidate_v15_11.png diff --git a/doc/user/project/ml/experiment_tracking/img/candidates_v15_11.png b/doc/user/project/ml/experiment_tracking/img/candidates_v15_11.png Binary files differnew file mode 100644 index 00000000000..3a2944c92ae --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/candidates_v15_11.png diff --git a/doc/user/project/ml/experiment_tracking/img/experiments_v15_11.png b/doc/user/project/ml/experiment_tracking/img/experiments_v15_11.png Binary files differnew file mode 100644 index 00000000000..f7e25c1a0f1 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/experiments_v15_11.png diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index a7096d633a0..114ccea7c09 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -4,78 +4,86 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# Machine Learning Experiment Tracking **(FREE)** +# Machine learning model experiments **(FREE)** -DISCLAIMER: -Machine Learning Experiment Tracking is an experimental feature being developed by the Incubation Engineering Department, -and will receive significant changes over time. This feature is being release with the aim of getting user feedback, but -is not stable and can lead to performance degradation. See below on how to disable this feature. +FLAG: +On self-managed GitLab, model experiment tracking is disabled by default. +To enable the feature, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. +On GitLab.com, this feature is in private testing only. -When creating machine learning models, data scientists often experiment with different parameters, configurations, feature -engineering, and so on, to improve the performance of the model. Keeping track of all this metadata and the associated +NOTE: +Model experiment tracking is an [experimental feature](../../../../policy/alpha-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. + +When creating machine learning models, data scientists often experiment with different parameters, configurations, and feature +engineering to improve the performance of the model. Keeping track of all this metadata and the associated artifacts so that the data scientist can later replicate the experiment is not trivial. Machine learning experiment tracking enables them to log parameters, metrics, and artifacts directly into GitLab, giving easy access later on. - +These features have been proposed: - +- Searching experiments. +- Visual comparison of candidates. +- Creating, deleting, and updating experiments through the GitLab UI. +- Creating, deleting, and updating candidates through the GitLab UI. - +For feature requests, see [epic 9341](https://gitlab.com/groups/gitlab-org/-/epics/9341). ## What is an experiment? -An experiment is a collection of comparable model candidates. Experiments can be long lived (for example, when they represent -a use case), or short lived (results from hyperparameter tuning triggered by a merge request), but usually hold model candidates -that have a similar set of parameters and metrics. +In a project, an experiment is a collection of comparable model candidates. +Experiments can be long-lived (for example, when they represent a use case), or +short-lived (results from hyperparameter tuning triggered by a merge request), +but usually hold model candidates that have a similar set of parameters measured +by the same metrics. + + ## Model candidate A model candidate is a variation of the training of a machine learning model, that can be eventually promoted to a version -of the model. The goal of a data scientist is to find the model candidate whose parameter values lead to the best model +of the model. + + + +The goal of a data scientist is to find the model candidate whose parameter values lead to the best model performance, as indicated by the given metrics. -Example parameters: + + +Some example parameters: -- Algorithm (linear regression, decision tree, and so on). +- Algorithm (such as linear regression or decision tree). - Hyperparameters for the algorithm (learning rate, tree depth, number of epochs). - Features included. -## Usage +## Track new experiments and candidates -### User access management +Experiment and trials can only be tracked through the +[MLFlow](https://www.mlflow.org/docs/latest/tracking.html) client integration. +See [MLFlow client integration](../../integrations/mlflow_client.md) for more information +on how to use GitLab as a backend for the MLFlow Client. -An experiment is always associated to a project. Only users with access to the project an experiment is associated with -can view that experiment data. +## Explore model candidates -### Tracking new experiments and trials +Prerequisites: -Experiment and trials can only be tracked through the [MLFlow](https://www.mlflow.org/docs/latest/tracking.html) client -integration. More information on how to use GitLab as a backend for MLFlow Client can be found [at the documentation page](../../integrations/mlflow_client.md). +- You must have at least the Developer role to view experiment data. -### Exploring model candidates +To list the current active experiments, either go to `https/-/ml/experiments` or: -To list the current active experiments, navigate to `https/-/ml/experiments`. To display all trials -that have been logged, along with their metrics and parameters, select an experiment. To display details for a candidate, -select **Details**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Packages & registries > Model experiments**. +1. To display all candidates that have been logged, along with their metrics, parameters, and metadata, select an experiment. +1. To display details for a candidate, select **Details**. -### Logging artifacts +## View log artifacts Trial artifacts are saved as [generic packages](../../../packages/generic_packages/index.md), and follow all their -conventions. After an artifact is logged for a candidate, all artifacts logged for the candidate are listed in the -package registry. The package name for a candidate is `ml_candidate_<candidate_id>`, with version `-`. The link to the -artifacts can also be accessed from the **Experiment Candidates** list or **Candidate detail**. - -### Limitations and future - -- Searching experiments, searching trials, visual comparison of trials, and creating, deleting and updating experiments and trials through GitLab UI is under development. - -## Disabling or enabling the Feature - -On self-managed GitLab, ML Experiment Tracking is disabled by default. To enable the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. -On GitLab.com, this feature is currently on private testing. - -## Feedback, roadmap and reports +limitations. After an artifact is logged for a candidate, all artifacts logged for the candidate are listed in the +package registry. The package name for a candidate is `ml_experiment_<experiment_id>`, where the version is the candidate +IID. The link to the artifacts can also be accessed from the **Experiment Candidates** list or **Candidate detail**. -For updates on the development, refer to the [development epic](https://gitlab.com/groups/gitlab-org/-/epics/8560). +## Related topics -For feedback, bug reports and feature requests, refer to the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/381660). +- Development details in [epic 8560](https://gitlab.com/groups/gitlab-org/-/epics/8560). +- Add feedback in [issue 381660](https://gitlab.com/gitlab-org/gitlab/-/issues/381660). 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 a92f65b064e..5cdf493fe6f 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,7 +1,7 @@ --- type: concepts -stage: Create -group: Editor +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 --- 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 3bb62921979..e35be518fc6 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,6 @@ --- -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' -stage: Create -group: Editor +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 --- @@ -197,38 +196,6 @@ from the GitLab project. in place. Your domain is periodically reverified, and may be disabled if the record is removed. -##### Troubleshoot domain verification - -To manually verify that you have properly configured the domain verification -`TXT` DNS entry, you can run the following command in your terminal: - -```shell -dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT -``` - -Expect the output: - -```plaintext -;; ANSWER SECTION: -_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" -``` - -In some cases it can help to add the verification code with the same domain name as you are trying to register. - -For a root domain: - -| From | DNS Record | To | -| ------------------------------------------------- | ---------- | ---------------------- | -| `example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | - -For a subdomain: - -| From | DNS Record | To | -| ------------------------------------------------- | ---------- | ---------------------- | -| `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | - ### Add more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. @@ -352,14 +319,36 @@ To enable this setting: If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). -<!-- ## Troubleshooting +## Troubleshooting + +### Domain verification + +To manually verify that you have properly configured the domain verification +`TXT` DNS entry, you can run the following command in your terminal: + +```shell +dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT +``` + +Expect the output: + +```plaintext +;; ANSWER SECTION: +_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" +``` + +In some cases it can help to add the verification code with the same domain name as you are trying to register. -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. +For a root domain: -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. --> +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + +For a subdomain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | 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 34a2f221327..130709de3a5 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,8 +1,8 @@ --- type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." -stage: Create -group: Editor +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 --- 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 0ba00177659..484dc784fdb 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,7 +1,7 @@ --- type: concepts -stage: Create -group: Editor +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 --- 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 37f74d18d4c..17618146350 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,7 +1,7 @@ --- type: reference, howto -stage: Create -group: Editor +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 --- @@ -37,4 +37,4 @@ For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. To view the HTML and other assets that were created for the site, -[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +[download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts). 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 a864c114b3e..e8de80ac137 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,7 +1,7 @@ --- type: reference, howto -stage: Create -group: Editor +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 --- @@ -18,7 +18,7 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. -1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork). +1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#create-a-fork). 1. In the upper-right corner, select **Fork**, then choose a namespace to fork to. 1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. GitLab CI/CD builds and deploys your site. @@ -65,4 +65,4 @@ you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab ## Related topics -- [Download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts) +- [Download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts) 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 a3d6c8f75f9..c62ead69216 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- @@ -423,16 +423,11 @@ Now GitLab CI/CD not only builds the website, but also: - **Continuously deploys** every push to the `main` branch. To view the HTML and other assets that were created for the site, -[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +[download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts). ## Related topics -For more information, see the following blog posts. - -- Use GitLab CI/CD `environments` to - [deploy your web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). -- Learn how to run jobs - [sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2020/12/10/basics-of-gitlab-ci-updated/). -- Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) - to deploy this website, <https://docs.gitlab.com>. -- Learn [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). +- [Deploy your web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) +- [Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2020/12/10/basics-of-gitlab-ci-updated/) +- [Pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) +- [Use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/) 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 7b6efaa7af4..cb1da3fb21f 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,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- @@ -32,4 +32,4 @@ For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. To view the HTML and other assets that were created for the site, -[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +[download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts). diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index b286c59916a..6eb996db210 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 691757e3eca..f3b94bbf666 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,7 +1,7 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' -stage: Create -group: Editor +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 --- diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 0a8348f468e..05d0b461fea 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- @@ -271,7 +271,7 @@ This problem most likely results from a missing `index.html` file in the public a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`. -The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) from the latest pipeline. +The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts) from the latest pipeline. Files listed under the public directory can be accessed through the Pages URL for the project. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 248a74a8abc..1b046d03f59 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 3007d1a10d1..22e1f242cf8 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -1,8 +1,8 @@ --- description: 'Learn how to configure the build output folder for the most common static site generators' -stage: Create -group: Editor +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 --- @@ -146,7 +146,7 @@ module.exports = { ## Should you commit the `public` folder? Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks -for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. +for an [artifact](../../../ci/jobs/job_artifacts.md) of that name. If you set up a job that creates the `public` folder before deploy, such as by running `npm run build`, committing the folder isn't required. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 75cb1474dc2..bd8206b3bda 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 725818a7d25..fa736e79d93 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -79,7 +79,7 @@ Administrators can set a default branch protection level in the Configure protected branches for all projects in a group, or just for a project. -### For all projects in a group +### For all projects in a group **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 behind a feature flag, disabled by default. @@ -100,8 +100,8 @@ To protect a branch for all the projects in a group: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. In the **Branch** text box, type the branch name or a wildcard. -1. From the **Allowed to merge** list, select a role, group, or user that can merge into this branch. -1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. +1. From the **Allowed to merge** list, select a role that can merge into this branch. +1. From the **Allowed to push** list, select a role that can push to this branch. 1. Select **Protect**. The protected branch is added to the list of protected branches. @@ -270,7 +270,7 @@ Members who can push to this branch can now also force push. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. -For a protected branch, you can require at least one approval by a [Code Owner](code_owners.md). +For a protected branch, you can require at least one approval by a [Code Owner](codeowners/index.md). To protect a new branch and enable Code Owner's approval: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 3a00260770e..38b6bb44b48 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -49,113 +49,117 @@ The following quick actions are applicable to descriptions, discussions, and threads. Some quick actions might not be available to all subscription tiers. <!-- Keep this table sorted alphabetically --> - -| Command | Issue | Merge request | Epic | Action | -|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | -| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | -| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | -| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | +<!-- Don't prettify this table; it will expand out the last field into illegibility --> + +| Command | Issue | Merge request | Epic | Action | +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). +| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | `/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. | -| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | -| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. +| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Mark issue or epic as confidential. Support for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213741) in GitLab 15.6. | -| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | -| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | -| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | -| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. | +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. | `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). Use for toggling the draft status ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.) | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. | -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. | -| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | -| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | -| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | -| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. +| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. +| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | `/link` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). | -| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | -| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | -| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | -| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | -| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | -| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](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. | -| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | -| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) | -| `/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. | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). +| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. +| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](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. +| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) +| `/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. | `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | -| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | -| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | -| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | -| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | -| `/remove_estimate` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | -| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | -| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | -| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | -| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. | -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | -| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8041) in GitLab 12.7). | -| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. +| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. +| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. +| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. +| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. +| `/remove_estimate` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic. +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. +| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. +| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review. +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). | -| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3 | -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3. +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. -| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. | -| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | -| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | -| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident).| +| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). ## Work items -The following quick actions can be applied through the description field when editing work items. - -| Command | Task | Objective | Key Result | Action | -|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/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 creates a specific type of to-do item notification. | -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. | -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. | -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. | -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. | -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. | -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. | -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. | -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +> Executing quick actions from comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391282) in GitLab 15.10. + +Work items in GitLab include [tasks](../tasks.md) and [OKRs](../okrs.md). +The following quick actions can be applied through the description field when editing or commenting on work items. + +| Command | Task | Objective | Key Result | Action +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. +| `/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 creates a specific type of to-do item notification. +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index be2c923adcc..f200b2b396c 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -80,10 +80,11 @@ To create a release in the Releases page: - Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error. - Enter a new Git tag name. - 1. From the **Create from** dropdown list, select a branch or commit SHA to use when + 1. From the **Create tag** popover, select a branch or commit SHA to use when creating the new tag. 1. Optional. In the **Set tag message** text box, enter a message to create an [annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags). + 1. Select **Save**. 1. Optional. Enter additional information about the release, including: - [Title](release_fields.md#title). - [Milestones](#associate-milestones-with-a-release). diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index 36e36412cf1..7b5e808641c 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 953e1d4b082..bd3cfd26f1b 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index 93822be89b6..3269c75d362 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +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 --- @@ -245,7 +245,7 @@ release: ``` NOTE: -Directly attaching [job artifacts](../../../ci/pipelines/job_artifacts.md) +Directly attaching [job artifacts](../../../ci/jobs/job_artifacts.md) links to a release is not recommended, because artifacts are ephemeral and are used to pass data in the same pipeline. This means there's a risk that they could either expire or someone might manually delete them. diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md new file mode 100644 index 00000000000..f8fdd626852 --- /dev/null +++ b/doc/user/project/remote_development/connect_machine.md @@ -0,0 +1,107 @@ +--- +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 +--- + +# Tutorial: Connect a remote machine to the Web IDE **(FREE)** + +This tutorial shows you how to: + +- Create a development environment outside of GitLab. +- Connect a remote machine to the [Web IDE](../web_ide_beta/index.md). + +To connect a remote machine to the Web IDE, you must: + +1. [Generate Let's Encrypt certificates](#generate-lets-encrypt-certificates). +1. [Connect a development environment to the Web IDE](#connect-a-development-environment-to-the-web-ide). + +## Prerequisites + +- A remote virtual machine with root access +- A domain address resolving to that machine +- Docker installation + +## Generate Let's Encrypt certificates + +To generate Let's Encrypt certificates: + +1. Create an `A` record to point a domain to your remote machine (for example, from `example.remote.gitlab.dev` to `1.2.3.4`). +1. Install [Certbot](https://certbot.eff.org/) to enable HTTPS: + + ```shell + sudo apt-get update + sudo apt-get install certbot + ``` + +1. Generate the certificates: + + ```shell + export EMAIL="YOUR_EMAIL@example.com" + export DOMAIN="example.remote.gitlab.dev" + + certbot -d "${DOMAIN}" \ + -m "${EMAIL}" \ + --config-dir ~/.certbot/config \ + --logs-dir ~/.certbot/logs \ + --work-dir ~/.certbot/work \ + --manual \ + --preferred-challenges dns certonly + ``` + +## Connect a development environment to the Web IDE + +To connect a development environment to the Web IDE: + +1. Create a development environment: + + ```shell + export CERTS_DIR="/home/ubuntu/.certbot/config/live/${DOMAIN}" + export PROJECTS_DIR="/home/ubuntu" + + docker run -d \ + --name my-environment \ + -p 3443:3443 \ + -v "${CERTS_DIR}/fullchain.pem:/gitlab-rd-web-ide/certs/fullchain.pem" \ + -v "${CERTS_DIR}/privkey.pem:/gitlab-rd-web-ide/certs/privkey.pem" \ + -v "${PROJECTS_DIR}:/projects" \ + registry.gitlab.com/gitlab-org/remote-development/gitlab-rd-web-ide-docker:0.2-alpha \ + --log-level warn --domain "${DOMAIN}" --ignore-version-mismatch + ``` + + The new development environment starts automatically. + +1. Fetch a token: + + ```shell + docker exec my-environment cat TOKEN + ``` + +1. [Configure a remote connection](#configure-a-remote-connection). + +### Configure a remote connection + +To configure a remote connection from the Web IDE: + +1. Open the Web IDE. +1. On the menu bar, select **View > Terminal** or press <kbd>Control</kbd>+<kbd>`</kbd>. +1. In the terminal panel, select **Configure a remote connection**. +1. Enter the URL for the remote host including the port (for example, `yourdomain.com:3443`). +1. Enter the project path. +1. Enter the token you've fetched. + +Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE: + +1. Run this command: + + ```shell + echo "https://gitlab-org.gitlab.io/gitlab-web-ide?remoteHost=${DOMAIN}:3443&hostPath=/projects" + ``` + +1. Go to that URL and enter the token you've fetched. + +You've done it! Your development environment now runs as a remote host that's connected to the Web IDE. + +## Related topics + +- [Manage a development environment](index.md#manage-a-development-environment) diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 58d43f64812..e3c2b6ccfb2 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -1,18 +1,20 @@ --- stage: Create -group: Editor +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 --- -# Remote Development **(FREE)** +# Remote development **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. WARNING: -This feature is in [Alpha](../../../policy/alpha-beta-support.md#alpha-features) and subject to change without notice. +This feature is an [Experiment](../../../policy/alpha-beta-support.md#experiment) and subject to change without notice. DISCLAIMER: This page contains information related to upcoming products, features, and functionality. @@ -22,70 +24,40 @@ As with all projects, the items mentioned on this page are subject to change or The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. -You can use the [Web IDE](../web_ide/index.md) to commit changes to a project directly from your web browser without installing any dependencies or cloning any repositories. The Web IDE, however, lacks a native runtime environment on which you would compile code, run tests, or generate real-time feedback in the IDE. For a more complete IDE experience, you can pair the [Web IDE Beta](../web_ide_beta/index.md) with a Remote Development environment that has been properly configured to run as a host. +## Web IDE as a frontend -## Connect a remote machine to the Web IDE +You can use the [Web IDE](../web_ide_beta/index.md) to make, commit, and push changes to a project directly from your web browser. +This way, you can update any project without having to install any dependencies or clone any repositories locally. -Prerequisites: +The Web IDE, however, lacks a native runtime environment where you could compile code, run tests, or generate real-time feedback. +With remote development, you can use: -- A remote virtual machine with root access -- A domain address resolving to that machine -- Docker installation +- The Web IDE as a frontend +- A separate machine as a backend runtime environment -To connect a remote machine to the Web IDE, you must: +For a complete IDE experience, connect the Web IDE to a [development environment](#workspace) that's configured to run as a remote host. +For more information, see [connect a remote machine to the Web IDE](connect_machine.md). -1. [Generate Let's Encrypt certificates](#generate-lets-encrypt-certificates). -1. [Connect a development environment to the Web IDE](#connect-a-development-environment-to-the-web-ide). +## Workspace -### Generate Let's Encrypt certificates +A workspace is a virtual sandbox environment for your code that includes: -To generate Let's Encrypt certificates: +- A runtime environment +- Dependencies +- Configuration files -1. [Point a domain to your remote machine](#point-a-domain-to-your-remote-machine). -1. [Install Certbot](#install-certbot). -1. [Generate the certificates](#generate-the-certificates). +You can create a workspace from scratch or from a template that you can also customize. -#### Point a domain to your remote machine +When you configure and connect a workspace to the [Web IDE](../web_ide_beta/index.md), you can: -To point a domain to your remote machine, create an `A` record from `example.remote.gitlab.dev` to `1.2.3.4`. +- Edit files directly from the Web IDE and commit and push changes to GitLab. +- Use the Web IDE to run tests, debug code, and view real-time feedback. -#### Install Certbot +## Manage a development environment -[Certbot](https://certbot.eff.org/) is a free and open-source software tool that automatically uses Let's Encrypt certificates on manually administered websites to enable HTTPS. +### Create a development environment -To install Certbot, run the following command: - -```shell -sudo apt-get update -sudo apt-get install certbot -``` - -#### Generate the certificates - -```shell -export EMAIL="YOUR_EMAIL@example.com" -export DOMAIN="example.remote.gitlab.dev" - -certbot -d "${DOMAIN}" \ - -m "${EMAIL}" \ - --config-dir ~/.certbot/config \ - --logs-dir ~/.certbot/logs \ - --work-dir ~/.certbot/work \ - --manual \ - --preferred-challenges dns certonly -``` - -### Connect a development environment to the Web IDE - -To connect a development environment to the Web IDE: - -1. [Create a development environment](#manage-a-development-environment). -1. [Fetch a token](#fetch-a-token). -1. [Configure a remote connection](#configure-a-remote-connection). - -#### Manage a development environment - -**Create a development environment** +To create a development environment, run this command: ```shell export CERTS_DIR="/home/ubuntu/.certbot/config/live/${DOMAIN}" @@ -103,58 +75,31 @@ docker run -d \ The new development environment starts automatically. -**Stop a development environment** +### Stop a development environment + +To stop a running development environment, run this command: ```shell docker container stop my-environment ``` -**Start a development environment** +### Start a development environment + +To start a stopped development environment, run this command: ```shell docker container start my-environment ``` -The token changes every time you restart the development environment. +The token changes every time you start the development environment. -**Remove a development environment** +### Remove a development environment To remove a development environment: -1. Stop the development environment. -1. Run the following command: +1. [Stop the development environment](#stop-a-development-environment). +1. Run this command: ```shell docker container rm my-environment ``` - -#### Fetch a token - -```shell -docker exec my-environment cat TOKEN -``` - -#### Configure a remote connection - -To configure a remote connection from the Web IDE: - -1. Open the Web IDE. -1. In the Menu Bar, select **View > Terminal** or press <kbd>Control</kbd>+<kbd>`</kbd>. -1. In the terminal panel, select **Configure a remote connection**. -1. Enter the URL for the remote host including the port (for example, `yourdomain.com:3443`). -1. Enter the project path. -1. Enter the [token you fetched](#fetch-a-token). - -Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE: - -1. Run the following command: - - ```shell - echo "https://gitlab-org.gitlab.io/gitlab-web-ide?remoteHost=${DOMAIN}:3443&hostPath=/projects" - ``` - -1. Go to that URL and enter the [token you fetched](#fetch-a-token). - -## Related topics - -- [Web IDE Beta](../web_ide_beta/index.md) diff --git a/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png Binary files differindex 09b30af91d0..8472015c21b 100644 --- a/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png +++ b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index ef625739956..bb02e5876c9 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -25,6 +25,61 @@ Branches are the foundation of development in a project: 1. Preview changes in a branch with a [review app](../../../../ci/review_apps/index.md). 1. After the contents of your branch are merged, [delete the merged branch](#delete-merged-branches). +## Create branch + +To create a new branch from the GitLab UI: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. +1. On the top right, select **New branch**. +1. Enter a **Branch name**. +1. In **Create from**, select the base of your branch: an existing branch, an existing + tag, or a commit SHA. +1. Select **Create branch**. + +### In a blank project + +A [blank project](../../index.md#create-a-blank-project) does not contain a branch, but +you can add one. + +Prerequisites: + +- You must have at least the Developer role in the project. +- Unless you have the Maintainer or Owner roles, the + [default branch protection](../../../group/manage.md#change-the-default-branch-protection-of-a-group) + must be set to `Partially protected` or `Not protected` for you to push a commit + to the default branch. + +To add a [default branch](default.md) to an empty project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. Scroll to **The repository for this project is empty** and select the type of + file you want to add. +1. In the Web IDE, make any desired changes to this file, then select **Create commit**. +1. Enter a commit message, and select **Commit**. + +GitLab creates a default branch and adds your file to it. + +### From an issue + +When viewing an issue, you can create an associated branch directly from that page. + +Prerequisites: + +- You must have the Developer or higher role in the project. + +To create a branch from an issue: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues** (**{issues}**) and find your issue. +1. Below the issue description, find the **Create merge request** dropdown list, and select + **{chevron-down}** to display the dropdown list. +1. Select **Create branch**. A default **Branch name** is provided, based on the + [default pattern](#configure-default-pattern-for-branch-names-from-issues) for + this project. If desired, enter a different **Branch name**. +1. Select **Create branch** to create the branch based on your project's + [default branch](default.md). + ## Manage and protect branches GitLab provides you multiple methods to protect individual branches. These methods @@ -63,9 +118,10 @@ On this page, you can: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.10. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.11 FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../feature_flags.md) named `branch_rules`. On GitLab.com, this feature is available. Branches in your repository can be [protected](../../protected_branches.md) in multiple ways. You can: @@ -82,7 +138,7 @@ and their protection methods: Prerequisites: -- You must have at least the Developer role in the project. +- You must have at least the Maintainer role in the project. To view the **Branch rules overview** list: @@ -99,7 +155,35 @@ To view the **Branch rules overview** list: - [Approval rules](../../merge_requests/approvals/rules.md). - [Status checks](../../merge_requests/status_checks.md). -## Prefix branch names with issue numbers +## Name your branch + +If you follow GitLab standards for [naming branches](#prefix-branch-names-with-issue-numbers), +and configure branch names that follow these standards, GitLab can streamline your workflow: + +- Connect a merge request to its parent issue. +- Connect a branch to an issue. +- [Close the issue](../../issues/managing_issues.md#closing-issues-automatically) + when the connected merge request closes, and the connected branch merges. + +### Configure default pattern for branch names from issues + +By default, GitLab uses the pattern `%{id}-%{title}` when creating a branch from +an issue, but you can change this pattern. + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To change the default pattern for branches created from issues: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository** and expand **Branch defaults**. +1. Scroll to **Branch name template** and enter a value. The field supports these variables: + - `%{id}`: The numeric ID of the issue. + - `%{title}`: The title of the issue, modified to use only characters acceptable in Git branch names. +1. Select **Save changes**. + +### Prefix branch names with issue numbers To streamline the creation of merge requests, start your branch name with an issue number. GitLab uses the issue number to import data into the merge request: @@ -144,10 +228,10 @@ automatically when a merge request was merged. ## Related topics -- [Protected branches](../../protected_branches.md) user documentation. -- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [Protected Branches API](../../../../api/protected_branches.md). -- [Getting started with Git](../../../../topics/git/index.md) and GitLab. +- [Protected branches](../../protected_branches.md) +- [Branches API](../../../../api/branches.md) +- [Protected Branches API](../../../../api/protected_branches.md) +- [Getting started with Git](../../../../topics/git/index.md) ## Troubleshooting diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md new file mode 100644 index 00000000000..68b1551eb16 --- /dev/null +++ b/doc/user/project/repository/code_suggestions.md @@ -0,0 +1,142 @@ +--- +stage: ModelOps +group: AI Assisted +info: To 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 +--- + +# Code Suggestions (Beta) **(ULTIMATE SAAS)** + +> - Enabled as opt-in with GitLab 15.11 as [Beta](/ee/policy/alpha-beta-support.md#beta). +> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/alpha-beta-support.md#beta) for early access Ultimate customers. + +WARNING: +This feature is in [Beta](/ee/policy/alpha-beta-support.md#beta). Code Suggestions use generative AI to suggest code while you're developing. Due to high demand, this feature will have unscheduled downtime and code suggestions in VS Code may be delayed. Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your feedback. + +Use Code Suggestions to write code more efficiently by viewing code suggestions +as you type. Depending on the cursor position, the extension either: + +- Provides entire code snippets, like generating functions. +- Completes the current line. + +To accept a suggestion, press <kbd>Tab</kbd>. + +Code Suggestions are supported in Visual Studio Code with the GitLab Workflow extension. GitLab plans to support the [new GitLab WebIDE in an upcoming release](../web_ide_beta/index.md) in the future. + +Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). Beta users should read about the [known limitations](#known-limitations). The best results from Code Suggestions are expected for these six languages: + +- C +- C++ +- Go +- Java +- JavaScript +- Python + +Suggestions may be mixed for other languages. Using natural language code comments to request completions may also not function as expected. + +GitLab is continuously improving the model and expects to support an additional seven languages soon, as well as natural language code comments. + +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). + +## Group level setting + +[Group owners](../../permissions.md#group-members-permissions) can enable Code Suggestions for all projects in a group by using the [group level Code Suggestions setting](../../group/manage.md#group-code-suggestions). + +## Enable Code Suggestions in VS Code + +Prerequisites: + +- Your group owner must enable the [group level code suggestions setting](../../group/manage.md#group-code-suggestions). +- You must have [a personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` and `read_user` scopes. + +To enable Code Suggestions in VS Code: + +1. Download and configure the + [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) + for Visual Studio Code. +1. In **GitLab: Add Account to VS Code on Mac**, add your GitLab work account to the VS Code extension: + - In macOS, press <kbd>Shift</kbd> + <kbd>Command</kbd> + <kbd>P</kbd>. + - In Windows, press <kbd>Shift</kbd> + <kbd>Control</kbd> + <kbd>P</kbd>. +1. Provide your GitLab instance URL. A default is provided. +1. Provide your personal access token. +1. After your GitLab account connects successfully, in the left sidebar, select **Extensions**. +1. Find the **GitLab workflow** extension, select **Settings** (**{settings}**), and select **Extension Settings**. +1. Enable **GitLab > AI Assisted Code Suggestions**. + +Start typing and receive suggestions for your GitLab projects. + +<div class="video-fallback"> + See an end-to-end demo: <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">Get started with GitLab Code Suggestions in VS Code</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> +</figure> + +## Code Suggestions Data Usage + +### Overview + +Code Suggestions is a generative artificial intelligence (AI) model hosted on GitLab.com that can empower your developers to code more efficiently by suggesting code as they type. + +The personal access token enables a secure API connection to GitLab.com. This API connection securely transmits a context window from VS Code to the Code Suggestions ML model for inference, and the generated suggestion is transmitted back to VS Code. + +#### Progressive enhancement + +This feature is designed as a progressive enhancement to the existing VS Code GitLab Workflow plugin. Code Suggestions offer a completion if the machine learning engine can generate a recommendation. 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 VS Code. + +#### Off by default + +Code Suggestions are off by default and require a group owner to enable the feature with a [group-level setting](#group-level-setting). + +After the group level setting is enabled, Developers using Visual Studio Code with the [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) can connect to GitLab.com via a GitLab [personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` and `read_user` scopes. + +#### Generating suggestions + +Once configured by a developer in VS Code. The personal access token enables a secure API connection to GitLab.com. This API connection securely transmits a context window from VS Code to the Code Suggestions ML model for inference, and the generated suggestion is transmitted back to VS Code. + +Code Suggestions only work when you have internet connectivity and can access GitLab.com. Code Suggestions are not available for self-managed customers, nor customers operating within an air-gapped environment. + +### Stability and performance + +This feature is currently in [Beta](/ee/policy/alpha-beta-support.md#beta). While the Code Suggestions inference API operates completely within GitLab.com's enterprise infrastructure, we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. + +## Data privacy + +Code Suggestions operate completely in the GitLab.com infrastructure, providing the same level of [security](https://about.gitlab.com/security/) as any other feature of GitLab.com, and processing any personal data in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). + +No new additional data is collected to enable this feature. The content of your GitLab hosted source code is not used as training data. Source code inference against the Code Suggestions model is not used to re-train the model. Your data also never leaves GitLab.com. All training and inference is done in GitLab.com infrastructure. + +[Read more about the security of GitLab.com](https://about.gitlab.com/security/faq/). + +### Model accuracy and quality + +While in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. We strongly encourage all beta users to leverage GitLab native [Code Quality Scanning](../../../ci/testing/code_quality.md) and [Security Scanning](../../application_security/index.md) capabilities. + +GitLab uses a customized open source dataset to fine-tune the model to support multiple languages. Based on the languages you code in, GitLab routes the request to a targeted inference and prompt engine to get relevant suggestions. + +GitLab is actively refining these models to improve the quality of recommendations, add support for more languages, and add protections to limit personal data, insecure code, and other unwanted behavior that the model may have learned from training data. + +### Training data + +Code Suggestions uses open source pre-trained base models from the [CodeGen family](https://openreview.net/forum?id=iaYcJKpY2B_) including CodeGen-MULTI and CodeGen-NL. We then re-train and fine-tune these base models with a customized open source dataset to enable multi-language support and additional use cases. This customized dataset contains non-preprocessed open source code in 13 programming languages from [The Pile](https://pile.eleuther.ai/) and [Google's BigQuery source code dataset](https://cloud.google.com/blog/topics/public-datasets/github-on-bigquery-analyze-all-the-open-source-code). We then process this raw dataset against heuristics that aim to increase the quality of the dataset. + +The Code Suggestions model is not trained on GitLab customer data. + +## Known limitations + +While in Beta, we are working on improving the accuracy of overall generated content. However, Code Suggestions may generate suggestions that are: + +- Low-quality +- Incomplete +- Produce failed pipelines +- Insecure code +- Offensive or insensitive + +We are also aware of specific situations that can produce unexpected or incoherent results including: + +- Suggestions based on natural language code comments. +- Suggestions that mixed programming languages in unexpected ways. + +## Feedback + +Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 3fcc19db344..e22dc549a4a 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,42 +1,28 @@ --- stage: Create -group: Editor +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 -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- # File finder **(FREE)** -The file finder feature allows you to search for a file in a repository using the -GitLab UI. To use it: +With file finder, you can search for a file in a repository directly from the GitLab UI. -1. Go to your project's **Repository > Files**. -1. In the upper-right corner, select **Find File**. +File finder is powered by the [`fuzzaldrin-plus`](https://github.com/jeancroy/fuzz-aldrin-plus) library, which uses fuzzy search and highlights results as you type. -If you prefer to keep your fingers on the keyboard, use the -[shortcut button](../../shortcuts.md), which you can invoke from anywhere -in a project. +## Search for a file -Press `t` to launch the File search function when in **Issues**, -**Merge requests**, **Milestones**, even the project's settings. +To search for a file: -Start typing what you are searching for and watch the magic happen. With the -up/down arrows, you go up and down the results, with `Esc` you close the search -and go back to **Files** +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. In the upper right, select **Find file**. +1. In the search box, start typing the filename. +1. From the dropdown list, select the file. -## How it works +To go to file finder, you can also press <kbd>t</kbd> anywhere in your project. +To go back to **Files**, press <kbd>Esc</kbd>. -The File finder feature is powered by the [Fuzzy filter](https://github.com/jeancroy/fuzz-aldrin-plus) library. - -It implements a fuzzy search with the highlight and tries to provide intuitive -results by recognizing patterns that people use while searching. - -For example, consider the [GitLab FOSS repository](https://gitlab.com/gitlab-org/gitlab-foss/tree/master) and that we want to open -the `app/controllers/admin/deploy_keys_controller.rb` file. - -Using a fuzzy search, we start by typing letters that get us closer to the file. - -NOTE: -To narrow down your search, include `/` in your search terms. +To narrow down your results, include `/` in your search.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 8c7c94613a7..423bdd178c6 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- # Project forking workflow **(FREE)** @@ -16,7 +15,7 @@ A fork is a personal copy of the repository and all its branches, which you crea in a namespace of your choice. Make changes in your own fork and submit them through a merge request to the repository you don't have access to. -## Creating a fork +## Create a fork > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) a new form in GitLab 13.11 [with a flag](../../../user/feature_flags.md) named `fork_project_form`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77181) in GitLab 14.8. Feature flag `fork_project_form` removed. @@ -40,7 +39,7 @@ GitLab creates your fork, and redirects you to the new fork's page. ## Update your fork To copy the latest changes from the upstream repository into your fork, update it -[from the command line](#from-the-command-line). GitLab Premium and higher tiers can also +from the command line. GitLab Premium and higher tiers can also [configure forks as pull mirrors](#with-repository-mirroring) of the upstream repository. @@ -102,7 +101,7 @@ an `upstream` remote repository for your fork: A fork can be configured as a mirror of the upstream if all these conditions are met: -1. Your subscription is **(PREMIUM)** or a higher tier. +1. Your subscription is **Premium** or higher. 1. You create all changes in branches (not `main`). 1. You do not work on [merge requests for confidential issues](../merge_requests/confidential.md), which requires changes to `main`. @@ -114,7 +113,7 @@ For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull- WARNING: With mirroring, before approving a merge request, you are asked to sync. You should automate it. -## Merging upstream +## Merge changes back upstream When you are ready to send your code back to the upstream project, [create a merge request](../merge_requests/creating_merge_requests.md). For **Source branch**, @@ -129,19 +128,55 @@ Then you can add labels, a milestone, and assign the merge request to someone wh your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your changes are added to the repository and branch you're merging into. -## Removing a fork relationship +## Unlink a fork -You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#remove-a-fork-relationship). +Removing a fork relationship unlinks your fork from its upstream project. +Your fork then becomes an independent project. + +Prerequisites: + +- You must be a project owner to unlink a fork. + +WARNING: +If you remove a fork relationship, you can't send merge requests to the source. +If anyone has forked your project, their fork also loses the relationship. +To restore the fork relationship, [use the API](../../../api/projects.md#create-a-forked-fromto-relation-between-existing-projects). + +To remove a fork relationship: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the **Remove fork relationship** section, select **Remove fork relationship**. +1. To confirm, enter the project path and select **Confirm**. + +When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_types.md#hashed-object-pools) +to share objects with another repository: + +- All objects are copied from the pool into your fork. +- After the copy process completes, no further updates from the storage pool are propagated to your fork. ## Related topics -- GitLab blog post: [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). -- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/). +- GitLab blog post: [Keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/) +- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/) ## Troubleshooting -### An error occurred while forking the project. Please try again +### Error: `An error occurred while forking the project. Please try again` This error can be due to a mismatch in shared runner settings between the forked project and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks) in the Runner documentation for more information. + +### Removing fork relationship fails + +If removing the fork through the UI or API is not working, you can attempt the +fork relationship removal in a +[Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +p = Project.find_by_full_path('<project_path>') +u = User.find_by_username('<username>') +Projects::UnlinkForkService.new(p, u).execute +``` diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 1c64a47985b..9f0c46591b9 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -277,15 +277,15 @@ to fetch configuration from a project that is renamed or moved. ## Related topics -- [GitLab Workflow VS Code extension](vscode.md). -- To lock files and prevent change conflicts, use [file locking](../file_lock.md). -- [Repository API](../../../api/repositories.md). -- [Find files](file_finder.md) in a repository. -- [Branches](branches/index.md). -- [Create a directory](web_editor.md#create-a-directory). -- [Find file history](git_history.md). -- [Identify changes by line (Git blame)](git_blame.md). -- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). +- [GitLab Workflow VS Code extension](vscode.md) +- [Lock files and prevent change conflicts](../file_lock.md) +- [Repository API](../../../api/repositories.md) +- [Find files](file_finder.md) +- [Branches](branches/index.md) +- [Create a directory](web_editor.md#create-a-directory) +- [Find file history](git_history.md) +- [Identify changes by line (Git blame)](git_blame.md) +- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md) ## Troubleshooting diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 28f0ffb6fbd..1526c7b4dc2 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,7 +25,7 @@ GitLab. ## Cleaner diffs and raw diffs -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Alpha](../../../../policy/alpha-beta-support.md#alpha-features) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. > - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 15.6. Feature flag `ipynb_semantic_diff` removed. diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 9942469dd5c..0563f747e8d 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Bidirectional mirroring **(PREMIUM)** @@ -168,4 +167,4 @@ Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manual ## Related topics -- [Configure server hooks](../../../../administration/server_hooks.md) on a GitLab server. +- [Configure server hooks](../../../../administration/server_hooks.md) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 7a50c294dfc..61aa2ae3300 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Repository mirroring **(FREE)** @@ -331,6 +330,29 @@ and requires the full version including the protocol (`ssh://git@gitlab.com/gitl Make sure that host and project path are separated using `/` instead of `:`. +### Host key verification failed + +This error is returned when the target host public SSH key changes. +Public SSH keys rarely, if ever, change. If host key verification fails, +but you suspect the key is still valid, you can refresh the key's information. + +Prerequisites: + +- You must have at least the Maintainer role for a project. + +To resolve the issue: + +1. [Verify the host key](#verify-a-host-key). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. To refresh the keys, either: + + - Select **Detect host keys** for GitLab to fetch the host keys from the server, and display the fingerprints. + - Select **Input host keys manually**, and enter the host key into the **SSH host key** field. + +- Select **Mirror repository**. + ### Transfer mirror users and tokens to a single service account in Rails console This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 0eb51f40208..2b8470b9e3d 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Pull from a remote repository **(PREMIUM)** @@ -142,6 +141,5 @@ end ## Related topics -- Configure [pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) - on self-managed instances. -- Configure [pull mirroring through the API](../../../../api/projects.md#configure-pull-mirroring-for-a-project). +- [Pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) +- [Pull mirroring API](../../../../api/projects.md#configure-pull-mirroring-for-a-project) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index ea58c472f4a..11093958650 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Push mirroring **(FREE)** @@ -196,4 +195,4 @@ If it isn't working correctly, a red `error` tag appears, and shows the error me ## Related topics -- [Remote mirrors API](../../../../api/remote_mirrors.md). +- [Remote mirrors API](../../../../api/remote_mirrors.md) 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 cf7d4f44aad..4bebe4c1a97 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 @@ -22,16 +22,27 @@ Rewriting repository history is a destructive operation. Make sure to back up yo you begin. The best way to back up a repository is to [export the project](../settings/import_export.md#export-a-project-and-its-data). +## Calculate repository size + +The size of a repository is determined by computing the accumulated size of all files in the repository. +It is similar to executing `du --summarize --bytes` on your repository's +[hashed storage path](../../../administration/repository_storage_types.md). + ## Purge files from repository history -To reduce the size of your repository in GitLab, you must first remove references to large files from branches, tags, *and* -other internal references (refs) that are automatically created by GitLab. These refs include: +GitLab [prunes unreachable objects](../../../administration/housekeeping.md#prune-unreachable-objects) +as part of housekeeping. In GitLab, to reduce the disk size of your repository manually, you must +first remove references to large files from branches, tags, *and* other internal references (refs) +created by GitLab. These refs include: -- `refs/merge-requests/*` for merge requests. -- `refs/pipelines/*` for - [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). -- `refs/environments/*` for environments. -- `refs/keep-around/*` are created as hidden refs to prevent commits referenced in the database from being removed +- `refs/merge-requests/*` +- `refs/pipelines/*` +- `refs/environments/*` +- `refs/keep-around/*` + +NOTE: +For details on each of these references, see +[GitLab-specific references](../../../development/gitaly.md#gitlab-specific-references). These refs are not automatically downloaded and hidden refs are not advertised, but we can remove these refs using a project export. diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index 706b50a916d..e252a9a433b 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -101,8 +101,20 @@ To create a tag from the GitLab UI: To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md). +## Trigger pipelines from a tag + +GitLab CI/CD provides a [`CI_COMMIT_TAG` variable](../../../../ci/variables/predefined_variables.md) +to identify tags. Use this variable in job rules and workflow rules to test if the pipeline +was triggered by a tag. + +In your `.gitlab-ci.yml` file for the CI/CD pipeline configuration of your project, +you can trigger based on a new tag: + +- At the job level, with the [`only` keyword](../../../../ci/yaml/index.md#only--except). +- At the pipeline level, with the [workflow rules keywords](../../../../ci/yaml/workflow.md). + ## Related topics -- [Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) Git reference page. -- [Protected tags](../../protected_tags.md). -- [Tags API](../../../../api/tags.md). +- [Tagging (Git reference page)](https://git-scm.com/book/en/v2/Git-Basics-Tagging) +- [Protected tags](../../protected_tags.md) +- [Tags API](../../../../api/tags.md) diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 9260d59bc3a..2a33476b545 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +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 --- @@ -22,6 +22,7 @@ do more day-to-day tasks in Visual Studio Code, such as: and paste snippets to, and from, your editor. - [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) without cloning them. +- [Receive Code Suggestions](code_suggestions.md) ## Download the extension @@ -34,6 +35,7 @@ you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.g - [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). - [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. +- [Code Suggestions](code_suggestions.md) ## Report issues with the extension @@ -44,5 +46,4 @@ Report any issues, bugs, or feature requests in the - [Download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) - [Extension documentation](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/README.md) -- The extension source code is available in the - [`gitlab-vscode-extension`](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) project. +- [View source code](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index ace7e119469..dc988846676 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +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 --- diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 42f7be30822..4d0ffd6a70a 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -101,7 +101,7 @@ To configure Windows or macOS: - Downloading the installer. - Running `brew install smimesign` on macOS. 1. Get the ID of your certificate by running `smimesign --list-keys`. -1. Set your signing key by running `git config --global user.signingkey ID`. +1. Set your signing key by running `git config --global user.signingkey <ID>`, replacing `<ID>` with the certificate ID. 1. Configure X.509 with this command: ```shell diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index d385daa4fa1..b623be20b3a 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -24,6 +24,12 @@ If an industry standard *requires* that your application has a certain feature o [create a requirement](#create-a-requirement) to reflect this. When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement). +NOTE: +Requirements and [test cases](../../../ci/test_cases/index.md) are being +[migrated to work items](https://gitlab.com/groups/gitlab-org/-/epics/5171). +[Issue 323790](https://gitlab.com/gitlab-org/gitlab/-/issues/323790) proposes to link requirements to test cases. +For more information, see [Product Stage Direction - Plan](https://about.gitlab.com/direction/plan/). + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index c4fcdc5733e..1dd83949716 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -41,44 +41,45 @@ Meanwhile: - Your team saves time by not having to leave GitLab (or set up integrations) to follow up with your customer. -## Configuring Service Desk +## Configure Service Desk -Users with Maintainer and higher access in a project can configure Service Desk. +To start using Service Desk for a project, you must first turn it on. +By default, Service Desk is turned off. -Service Desk issues are [confidential](issues/confidential_issues.md), so they are -only visible to project members. +Prerequisites: -If you have [templates](description_templates.md) in your repository, you can optionally select -one from the selector menu to append it to all Service Desk issues. +- You must have at least the Maintainer role for the project. +- On GitLab self-managed, you must [set up incoming email](../../administration/incoming_email.md#set-it-up) + for the GitLab instance. You should use + [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. To enable Service Desk in your project: -1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - You should use [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). -1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. -1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues - to the project. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. +1. Turn on the **Activate Service Desk** toggle. +1. Optional. Complete the fields. + - [Add a suffix](#configure-a-custom-email-address-suffix) to your Service Desk email address. + - If the list below **Template to append to all Service Desk issues** is empty, create a + [description template](description_templates.md) in your repository. +1. Select **Save changes**. -Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select -**Issues > Service Desk**. +Service Desk is now enabled for this project. +If anyone sends an email to the address available below **Email address to use for Support Desk**, +GitLab creates a confidential issue with the email's content. -WARNING: -Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless -of their access level** to your GitLab instance. +### Improve your project's security -To improve your project's security, you should: +To improve your Service Desk project's security, you should: - Put the Service Desk email address behind an alias on your email system so you can change it later. - [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. Unblocked email spam can result in many spam issues being created. -The unique internal email address is visible to project members at least -the Reporter role in your GitLab instance. -An external user (issue creator) cannot see the internal email address -displayed in the information note. - -### Using customized email templates +### Create customized email templates > - Moved from GitLab Premium to GitLab Free in 13.2. > - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. @@ -89,14 +90,6 @@ An email is sent to the author when: - A new note is created on a Service Desk issue. You can customize the body of these email messages with templates. -Save your templates in the `.gitlab/service_desk_templates/` -directory in your repository. - -With Service Desk, you can use templates for: - -- [Thank you emails](#thank-you-email) -- [New note emails](#new-note-email) -- [New Service Desk issues](#new-service-desk-issues) #### Email header and footer **(FREE SELF)** @@ -109,7 +102,9 @@ visible in the email template. For more information, see #### Thank you email When a user submits an issue through Service Desk, GitLab sends a **thank you email**. -You must name the template file `thank_you.md`. + +To create a custom email template, in the `.gitlab/service_desk_templates/` +directory in your repository, create a file named `thank_you.md`. You can use these placeholders to be automatically replaced in each email: @@ -126,7 +121,9 @@ the response email does not contain the issue link. #### New note email When a user-submitted issue receives a new comment, GitLab sends a **new note email**. -You must name the template file `new_note.md`. + +To create a custom email template, in the `.gitlab/service_desk_templates/` +directory in your repository, create a file named `new_note.md`. You can use these placeholders to be automatically replaced in each email: @@ -138,7 +135,7 @@ You can use these placeholders to be automatically replaced in each email: - `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) - `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) -#### New Service Desk issues +### Use a custom template for Service Desk issues You can select one [description template](description_templates.md#create-an-issue-template) **per project** to be appended to every new Service Desk issue's description. @@ -151,44 +148,57 @@ 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: + +- You must have [created a description template](description_templates.md#create-an-issue-template). + To use a custom description template with Service Desk: 1. On the top bar, select **Main menu > Projects** and find your project. -1. [Create a description template](description_templates.md#create-an-issue-template). -1. On the left sidebar, select **Settings > General > Service Desk**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. 1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. -### Using a custom email display name +### Support Bot user + +Behind the scenes, Service Desk works by the special Support Bot user creating issues. +This user isn't a [billable user](../../subscriptions/self_managed/index.md#billable-users), +so it does not count toward the license limit count. + +#### Change the Support Bot's display name -You can customize the email display name. Emails sent from Service Desk have +You can change the display name of the Support Bot user. Emails sent from Service Desk have this name in the `From` header. The default display name is `GitLab Support Bot`. To edit the custom email display name: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General > Service Desk**. -1. Enter a new name in **Email display name**. -1. Select **Save Changes**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email display name**, enter a new name. +1. Select **Save changes**. -### Using a custom email address **(FREE SELF)** +### Use a custom email address **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. -It is possible to customize the email address used by Service Desk. To do this, you must configure -a [custom mailbox](#configuring-a-custom-mailbox). If you want you can also configure a -[custom suffix](#configuring-a-custom-email-address-suffix). +You can use a custom email address with Service Desk. -#### Configuring a custom mailbox +To do this, you must configure +a [custom mailbox](#configure-a-custom-mailbox). You can also configure a +[custom suffix](#configure-a-custom-email-address-suffix). + +#### Configure a custom mailbox NOTE: On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, you can still configure the -[custom suffix](#configuring-a-custom-email-address-suffix) in project settings. +[custom suffix](#configure-a-custom-email-address-suffix) in project settings. Service Desk uses the [incoming email](../../administration/incoming_email.md) configuration by default. However, by using the `service_desk_email` configuration, you can customize the mailbox used by Service Desk. This allows you to have -a separate email address for Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) +a separate email address for Service Desk by also configuring a [custom suffix](#configure-a-custom-email-address-suffix) in project settings. Prerequisites: @@ -255,7 +265,7 @@ The configuration options are the same as for configuring > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally -use an encrypted file for the Incoming email credentials. +use an encrypted file for the incoming email credentials. Prerequisites: @@ -384,7 +394,8 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre > - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth 2.0 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). +Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph +[the same way as for incoming email](../../administration/incoming_email.md#microsoft-graph). - Example for Omnibus GitLab installations: @@ -403,32 +414,44 @@ Graph API instead of IMAP. Follow the [documentation in the incoming email secti } ``` -For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azure_ad_endpoint` and `graph_endpoint` settings. - Example for Microsoft Cloud for US Government: ```ruby - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } +gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional } ``` -The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details. +The Microsoft Graph API is not yet supported in source installations. +For more information, see [issue 326169](https://gitlab.com/gitlab-org/gitlab/-/issues/326169). -#### Configuring a custom email address suffix +#### Configure a custom email address suffix -You can set a custom suffix in your project's Service Desk settings after you have configured a [custom mailbox](#configuring-a-custom-mailbox). -It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). +You can set a custom suffix in your project's Service Desk settings. + +A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). When configured, the custom suffix creates a new Service Desk email address, consisting of the `service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` +Prerequisites: + +- You must have configured a [custom mailbox](#configure-a-custom-mailbox). + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email address suffix**, enter the suffix to use. +1. Select **Save changes**. + For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: - Email address suffix is set to `support`. @@ -437,13 +460,23 @@ For example, suppose the `mygroup/myproject` project Service Desk settings has t The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. The [incoming email](../../administration/incoming_email.md) address still works. -If you don't configure the custom suffix, the default project identification is used for identifying the project. You can see that email address in the project settings. +If you don't configure a custom suffix, the default project identification is used for identifying +the project. -## Using Service Desk +## Use Service Desk You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). +### View Service Desk email address + +To check what the Service Desk email address is for your project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > Service Desk**. + +The email address is available at the top of the issue list. + ### As an end user (issue creator) > Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. @@ -483,42 +516,51 @@ You can read and write comments as you usually do in GitLab: - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. -#### Receiving files attached to comments as email attachments +#### View Service Desk issues -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. -On GitLab.com, this feature is available. +Prerequisites: -If a comment contains any attachments and their total size is less than or equal to 10 MB, these -attachments are sent as part of the email. In other cases, the email contains links to the attachments. +- You must have at least the Reporter role for the project. -In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. +To view Service Desk issues: -#### Special HTML formatting in HTML emails +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > Service Desk**. -<!-- When the feature flag is removed, delete this topic and add as a line in version history under one of the topics above this one.--> +### Email contents and formatting -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372301) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +#### Special HTML formatting in HTML emails -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. -On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. -When this feature is enabled, HTML emails correctly show additional HTML formatting, such as: +HTML emails show HTML formatting, such as: - Tables - Blockquotes - Images - Collapsible sections -#### Privacy considerations +#### Files attached to comments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is available. + +If a comment contains any attachments and their total size is less than or equal to 10 MB, these +attachments are sent as part of the email. In other cases, the email contains links to the attachments. + +In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. + +## Privacy considerations > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. -Service Desk issues are confidential, but the project owner can +Service Desk issues are [confidential](issues/confidential_issues.md), so they are +only visible to project members. The project owner can [make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). When a Service Desk issue becomes public, the issue creator's and participants' email addresses are visible to signed-in users with at least the Reporter role for the project. @@ -526,17 +568,18 @@ visible to signed-in users with at least the Reporter role for the project. In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email address is disclosed to everyone who can view the project. -### Support Bot user +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their role** in the project. -Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user -does not count toward the license limit count. +The unique internal email address is visible to project members at least +the Reporter role in your GitLab instance. +An external user (issue creator) cannot see the internal email address +displayed in the information note. ### Moving a Service Desk issue > [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. -Service Desk issues can be moved like any other issue in GitLab. - You can move a Service Desk issue the same way you [move a regular issue](issues/managing_issues.md#move-an-issue) in GitLab. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 230795222a0..85ef3dc8405 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -7,40 +7,64 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Migrating projects using file exports **(FREE)** Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and -then imported into a new GitLab instance. You can also: +then imported into another GitLab instance. You can also copy GitLab projects to another location with more automation by +[migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). -- Migrate projects when you [migrate groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). -- [Migrate groups by using file exports](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated). +## Preserving user contributions + +Preserving user contribution depends on meeting the following requirements: + +### Migrating from GitLab self-managed to GitLab.com + +When migrating projects by using file exports, an administrator's access token is required for user contributions to map correctly. + +Therefore, user contributions never map correctly when importing file exports from a self-managed instance to GitLab.com. Instead, all GitLab user associations (such as +comment author) are changed to the user importing the project. To preserve contribution history, do one of the following: + +- [Migrate by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- Consider paid GitLab [migration services](https://about.gitlab.com/services/migration/). + +### Migrating to GitLab self-managed -GitLab maps user contributions correctly when an admin access token is used to perform the import. +To ensure GitLab maps users and their contributions correctly: -Consequently, migrating projects using file exports does not map user contributions correctly when you are importing -projects from a self-managed instance to GitLab.com. +- The owner of the project's top-level group should export the project so that the information of all members (direct and inherited) with access to the project can be included in the exported file. Project maintainers and owners can initiate the project export. However, only direct members of a project are then exported. +- An administrator must perform the import with an administrator access token. +- Required users must exist on the destination GitLab instance. An administrator can create confirmed users either in bulk in a Rails console or one by one in the UI. +- Users must [set a public email in their profiles](../../profile/index.md#set-your-public-email) on the source GitLab instance that matches their primary email + address on the destination GitLab instance. You can also manually add users' public emails by + [editing project export files](#edit-project-export-files). -Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. For more -information, see the prerequisites and important notes in these sections: +When the email of an existing user matches the email of an imported user, that user is added as a [direct member](../members/index.md) to the imported project. -- [Export a project and its data](../settings/import_export.md#export-a-project-and-its-data). -- [Import the project](../settings/import_export.md#import-a-project-and-its-data). +If any of the previous conditions are not met, user contributions are not mapped correctly. Instead, all GitLab user associations are changed to the user who performed the import. +That user becomes an author of merge requests created by other users. Supplementary comments mentioning original authors are: -To preserve contribution history, [migrate using direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- Added for comments, merge request approvals, linked tasks, and items. +- Not added for the merge request or issue creator, added or removed labels, and merged-by information. -If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. +## Edit project export files + +You can add or remove data from export files. For example, you can: + +- Manually add users public emails to the `project_members.ndjson` file. +- Trim CI pipelines by removing lines from the `ci_pipelines.ndjson` file. + +To edit a project export file: + +1. Extract the exported `.tar.gz` file. +1. Edit the appropriate file . For example, `tree/project/project_members.ndjson`. +1. Compress the files back to a `.tar.gz` file. + +You can also make sure that all members were exported by checking the `project_members.ndjson` file. ## Compatibility -FLAG: -On self-managed GitLab by default project, file exports are in NDJSON format. To make GitLab produce project file -exports in JSON format, ask an administrator to [disable the feature flags](../../../administration/feature_flags.md) -named `project_export_as_ndjson`. To allow GitLab to import project file exports in JSON format, ask an administrator to -[disable the feature flags](../../../administration/feature_flags.md) named `project_import_ndjson`. On GitLab.com, -project file exports are in NDJSON format only. +> Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389888) in GitLab 15.11. -Project file exports are in NDJSON format. Before version 14.0, GitLab produced project file exports in JSON format. -To support transitions, you can still import JSON-formatted project file exports if you configure the relevant feature -flags. +Project file exports are in NDJSON format. -From GitLab 13.0, GitLab can import project file exports that were exported from a version of GitLab up to two +You can import project file exports that were exported from a version of GitLab up to two [minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for [security releases](../../../policy/maintenance.md#security-releases). @@ -85,7 +109,6 @@ Prerequisites: - Review the list of [items that are exported](#items-that-are-exported). Not all items are exported. - You must have at least the Maintainer role for the project. -- Users must [set a public email](../../profile/index.md#set-your-public-email) in the source GitLab instance that matches one of their verified emails in the target GitLab instance for the user mapping to work correctly. To export a project and its data, follow these steps: @@ -103,64 +126,68 @@ moved to your configured `uploads_directory`. Every 24 hours, a worker deletes t ### Items that are exported -The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) -file for projects lists many of the items exported and imported when migrating projects using file exports. View this file in the branch -for your version of GitLab to see the list of items relevant to you. For example, -[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). +Exported project items depend on the version of GitLab you use. To determine if a +specific project item is exported: -Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and -[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. +1. Check the [`exporters` array](https://gitlab.com/gitlab-org/gitlab/blob/0a60d6dcfa7b809cf4fe0c2e239f406014d92e34/app/services/projects/import_export/export_service.rb#L25-28). +1. Check the [`project/import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file for projects for your GitLab version (for example, `<https://gitlab.com/gitlab-org/gitlab/-/blob/15-9-stable-ee/lib/gitlab/import_export/project/import_export.yml>` for GitLab 15.9). -Items that are exported include: +For a quick overview, items that are exported include: - Project and wiki repositories - Project uploads - Project configuration, excluding integrations - Issues - Issue comments - - Issue iteration ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96184) in 15.4) - - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - - Issue resource iteration events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue iterations ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96184) in GitLab 15.4) + - Issue resource state events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource milestone events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource iteration events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Merge requests - Merge request diffs - Merge request comments - - Merge request resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - - Merge request multiple assignees ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) - - Merge request reviewers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) - - Merge request approvers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request resource state events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Merge request multiple assignees ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request reviewers ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request approvers ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) +- Commit comments ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391601) in GitLab 15.10) - Labels - Milestones - Snippets - Time tracking and other project entities -- Design Management files and data +- Design management files and data - LFS objects - Issue boards - Pipelines history -- Push Rules +- Push rules - Awards -- Group members are exported as project members, as long as the user has the Maintainer role in the - exported project's group, or is an administrator +- Group members as long as the user has the Maintainer role in the + exported project's group or is an administrator + +### Items that are not exported Items that are **not** exported include: - [Child pipeline history](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) +- Pipeline triggers - Build traces and artifacts - Package and container registry images - CI/CD variables -- Pipeline triggers - Webhooks - Any encrypted tokens - [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221087) - Repository size limits - Deploy keys allowed to push to protected branches -- Secure Files +- Secure files - [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700) (for example, pushing and creating tags) - Security policies associated with your project +Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and +[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. + ## Import a project and its data -> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. +> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. Administrators of self-managed instances can [set maximum import file size](#set-maximum-import-file-size). On GitLab.com, the value is [set to 5 GB](../../gitlab_com/index.md#account-and-limit-settings). WARNING: Only import projects from sources you trust. If you import a project from an untrusted source, it @@ -203,12 +230,7 @@ Deploy keys aren't imported. To use deploy keys, you must enable them in your im If you have a larger project, consider [using a Rake task](../../../administration/raketasks/project_import_export.md#import-large-projects). -## Automate group and project import **(PREMIUM)** - -For information on automating user, group, and project import API calls, see -[Automate group and project import](../import/index.md#automate-group-and-project-import). - -## Maximum import file size +## Set maximum import file size **(FREE SELF)** Administrators can set the maximum import file size one of two ways: @@ -217,34 +239,15 @@ Administrators can set the maximum import file size one of two ways: The default is `0` (unlimited). -For the GitLab.com setting, see the [Account and limit settings](../../gitlab_com/index.md#account-and-limit-settings) -section of the GitLab.com settings page. - -## Map users for import - -Imported users can be mapped by their public email addresses on self-managed instances, if an administrator (not an owner) does the import. - -- The project must be exported by a project or group member with the Owner role. -- Public email addresses are not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) - for mapping to work correctly. -- For contributions to be mapped correctly, users must be an existing member of the namespace, - or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original - author and the merge requests, notes, or issues that are owned by the importer. -- Imported users are set as [direct members](../members/index.md) - in the imported project. - -For project migration imports performed over GitLab.com groups, preserving author information is -possible through a [professional services engagement](https://about.gitlab.com/services/migration/). - ## Rate limits To help avoid abuse, by default, users are rate limited to: -| Request Type | Limit | -| ---------------- | ----- | -| Export | 6 projects per minute | -| Download export | 1 download per group per minute | -| Import | 6 projects per minute | +| Request type | Limit | +|:----------------|:--------------------------------| +| Export | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | ## Related topics @@ -252,3 +255,5 @@ To help avoid abuse, by default, users are rate limited to: - [Project import and export administration Rake tasks](../../../administration/raketasks/project_import_export.md) - [Migrating GitLab groups](../../group/import/index.md) - [Group import and export API](../../../api/group_import_export.md) +- [Migrate groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- [Migrate groups by using file exports](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated). diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 82412a1dcbf..530e7497b52 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -10,10 +10,10 @@ If you have problems with [migrating projects using file exports](import_export. ## Troubleshooting commands -Finds information about the status of the import and further logs using the JID: +Finds information about the status of the import and further logs using the JID, +using the [Rails console](../../../administration/operations/rails_console.md): ```ruby -# Rails console Project.find_by_full_path('group/project').import_state.slice(:jid, :status, :last_error) > {"jid"=>"414dec93f941a593ea1a6894", "status"=>"finished", "last_error"=>nil} ``` @@ -35,6 +35,27 @@ Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and - Ensure shared runners are enabled in both the source and destination projects. - Disable shared runners on the parent group when you import the project. +## Users missing from imported project + +If users aren't imported with imported projects, see the [preserving user contributions](import_export.md#preserving-user-contributions) requirements. + +A common reason for missing users is that the [public email setting](../../profile/index.md#set-your-public-email) isn't configured for users. +To resolve this issue, ask users to configure this setting using the GitLab UI. + +If there are too many users for manual configuration to be feasible, +you can set all user profiles to use a public email address using the +[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +User.where("public_email IS NULL OR public_email = '' ").find_each do |u| + next if u.bot? + + puts "Setting #{u.username}'s currently empty public email to #{u.email}…" + u.public_email = u.email + u.save! +end +``` + ## Import workarounds for large repositories [Maximum import size limitations](import_export.md#import-a-project-and-its-data) @@ -153,12 +174,12 @@ Rather than attempting to push all changes at once, this workaround: You usually export a project through [the web interface](import_export.md#export-a-project-and-its-data) or through [the API](../../../api/project_import_export.md). Exporting using these methods can sometimes fail without giving enough information to troubleshoot. In these cases, -[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and loop through +[open a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and loop through [all the defined exporters](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/projects/import_export/export_service.rb). Execute each line individually, rather than pasting the entire block at once, so you can see any errors each command returns. -```shell +```ruby # User needs to have permission to export u = User.find_by_username('someuser') p = Project.find_by_full_path('some/project') diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 7250406144f..18030ab0a81 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -75,28 +75,28 @@ To configure visibility, features, and permissions for a project: Use the toggles to enable or disable features in the project. -| Option | More access limit options | Description | -| :------------------------------- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Issues** | ✓ | Activates the GitLab issues tracker. | -| **Repository** | ✓ | Enables [repository](../repository/index.md) functionality | -| **Merge requests** | ✓ | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | -| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | -| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | -| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | -| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. | -| **Analytics** | ✓ | Enables [analytics](../../analytics/index.md). | -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | -| **Security and Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | -| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/index.md). | -| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | -| **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | -| **Releases** | ✓ | Control access to [Releases](../releases/index.md). | -| **Environments** | ✓ | Control access to [Environments and Deployments](../../../ci/environments/index.md). | -| **Feature flags** | ✓ | Control access to [Feature Flags](../../../operations/feature_flags.md). | -| **Monitor** | ✓ | Control access to [Monitor](../../../operations/index.md) features. | -| **Infrastructure** | ✓ | Control access to [Infrastructure](../../infrastructure/index.md) features. | +| Option | More access limit options | Description +| :------------------------------- | :------------------------ | :---------- | +| **Issues** | **{check-circle}** Yes | Activates the GitLab issues tracker. +| **Repository** | **{check-circle}** Yes | Enables [repository](../repository/index.md) functionality. +| **Merge requests** | **{check-circle}** Yes | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). +| **Forks** | **{check-circle}** Yes | Enables [forking](../repository/forking_workflow.md) functionality. +| **Git Large File Storage (LFS)** | **{dotted-circle}** No | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). +| **Packages** | **{dotted-circle}** No | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. +| **CI/CD** | **{check-circle}** Yes | Enables [CI/CD](../../../ci/index.md) functionality. +| **Container Registry** | **{dotted-circle}** No | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. +| **Analytics** | **{check-circle}** Yes | Enables [analytics](../../analytics/index.md). +| **Requirements** | **{check-circle}** Yes | Control access to [Requirements Management](../requirements/index.md). +| **Security and Compliance** | **{check-circle}** Yes | Control access to [security features](../../application_security/index.md). +| **Wiki** | **{check-circle}** Yes | Enables a separate system for [documentation](../wiki/index.md). +| **Snippets** | **{check-circle}** Yes | Enables [sharing of code and text](../../snippets.md). +| **Pages** | **{check-circle}** Yes | Allows you to [publish static websites](../pages/index.md). +| **Metrics Dashboard** | **{check-circle}** Yes | Control access to [metrics dashboard](../integrations/prometheus.md). +| **Releases** | **{check-circle}** Yes | Control access to [Releases](../releases/index.md). +| **Environments** | **{check-circle}** Yes | Control access to [Environments and Deployments](../../../ci/environments/index.md). +| **Feature flags** | **{check-circle}** Yes | Control access to [Feature flags](../../../operations/feature_flags.md). +| **Monitor** | **{check-circle}** Yes | Control access to [Monitor](../../../operations/index.md) features. +| **Infrastructure** | **{check-circle}** Yes | Control access to [Infrastructure](../../infrastructure/index.md) features. When you disable a feature, the following additional features are also disabled: @@ -162,6 +162,7 @@ Configure your project's merge request settings: - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. +- Enable [Suggested Reviewers](../merge_requests/reviews/index.md#suggested-reviewers). ## Service Desk @@ -174,7 +175,7 @@ Learn how to [export a project](import_export.md#import-a-project-and-its-data) ## Advanced project settings Use the advanced settings to archive, rename, transfer, -remove a fork relationship, or delete a project. +[remove a fork relationship](../repository/forking_workflow.md#unlink-a-fork), or delete a project. ### Archive a project @@ -347,24 +348,6 @@ To restore a project marked for deletion: 1. Navigate to your project, and select **Settings > General > Advanced**. 1. In the Restore project section, select **Restore project**. -## Remove a fork relationship - -Prerequisites: - -- You must be a project owner to remove a fork relationship. - -WARNING: -If you remove a fork relationship, you can't send merge requests to the source. If anyone has forked your project, their fork also loses the relationship. -To restore the fork relationship, [use the API](../../../api/projects.md#create-a-forked-fromto-relation-between-existing-projects). - -To remove a fork relationship: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Advanced**. -1. In the **Remove fork relationship** section, select **Remove fork relationship**. -1. To confirm, enter the project path and select **Confirm**. - ## Monitor settings ### Alerts @@ -398,16 +381,6 @@ to enable the syncing of public Issues to a [deployed status page](../../../oper When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. -### Remove a fork relationship through console - -If removing the fork through the UI or API is not working, you can attempt the fork relationship removal in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -```ruby -p = Project.find_by_full_path('<project_path>') -u = User.find_by_username('<username>') -Projects::UnlinkForkService.new(p, u).execute -``` - ### 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). diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md new file mode 100644 index 00000000000..1eee4364d95 --- /dev/null +++ b/doc/user/project/system_notes.md @@ -0,0 +1,56 @@ +--- +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 +--- + +# System notes **(FREE)** + +System notes are short descriptions that help you understand the history of events +that occur during the life cycle of a GitLab object, such as: + +- [Alerts](../../operations/incident_management/alerts.md). +- [Designs](issues/design_management.md). +- [Issues](issues/index.md). +- [Merge requests](merge_requests/index.md). +- [Objectives and key results](../okrs.md) (OKRs). +- [Tasks](../tasks.md). + +GitLab logs information about events triggered by Git or the GitLab application +in system notes. System notes use the format `<Author> <action> <time ago>`. + +## Show or filter system notes + +By default, system notes do not display. When displayed, they are shown oldest first. +If you change the filter or sort options, your selection is remembered across sections. +The filtering options are: + +- **Show all activity** displays both comments and history. +- **Show comments only** hides system notes. +- **Show history only** hides user comments. + +### On an epic + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Epics** (**{epic}**). +1. Identify your desired epic, and select its title. +1. Go to the **Activity** section. +1. For **Sort or filter**, select **Show all activity**. + +### On an issue + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues** and find your issue. +1. Go to **Activity**. +1. For **Sort or filter**, select **Show all activity**. + +### On a merge request + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. Go to **Activity**. +1. For **Sort or filter**, select **Show all activity**. + +## Related topics + +- [Notes API](../../api/notes.md) diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index d5f0b7e6180..bd935db6f02 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -1,6 +1,5 @@ --- type: reference -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' 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 diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index e2a74f02008..889ab1442b6 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +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 --- @@ -296,7 +296,7 @@ An example `package.json`: > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) from GitLab Ultimate to GitLab Free in 13.1. WARNING: -Interactive Web Terminals for the Web IDE is currently in [**Beta**](../../../policy/alpha-beta-support.md#beta-features). +Interactive Web Terminals for the Web IDE is currently in [Beta](../../../policy/alpha-beta-support.md#beta). GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), so you must use your own private runner to make use of this feature. @@ -450,7 +450,7 @@ when: - You select any area outside the file editor after editing a file. - A file or folder is created, deleted, or renamed. -### Known issues +## Known issues The Web IDE has a few limitations: @@ -458,7 +458,9 @@ The Web IDE has a few limitations: active terminal at a time. - LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. -### Troubleshooting +## Troubleshooting + +### Web terminals - If the terminal's text is gray and unresponsive, then the terminal has stopped and it can no longer be used. A stopped terminal can be restarted by selecting @@ -466,7 +468,3 @@ The Web IDE has a few limitations: - If the terminal displays **Connection Failure**, then the terminal could not connect to the runner. Try to stop and restart the terminal. If the problem persists, double check your runner configuration. - -## Related topics - -- [Web IDE Beta](../web_ide_beta/index.md) diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index 635b5e12575..933634f0c29 100644 --- a/doc/user/project/web_ide_beta/index.md +++ b/doc/user/project/web_ide_beta/index.md @@ -1,15 +1,17 @@ --- stage: Create -group: Editor +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 --- # Web IDE Beta **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. As announced in [this blog post](https://about.gitlab.com/blog/2022/05/23/the-future-of-the-gitlab-web-ide/), the current implementation of the [Web IDE](../web_ide/index.md) is being replaced @@ -18,15 +20,6 @@ development. For updates, see [this epic](https://gitlab.com/groups/gitlab-org/- To pair the Web IDE Beta with a Remote Development environment, see [Remote Development](../remote_development/index.md). -## Enable the Web IDE Beta - -To use the Web IDE Beta on a self-managed GitLab instance, -ensure that the `vscode_web_ide` feature flag -[is enabled](../../../administration/feature_flags.md). - -On GitLab.com, this feature is available by default. However, you can -[stop using it if you choose](#stop-using-the-web-ide-beta). - ## Use the Web IDE Beta To open the Web IDE Beta from anywhere in the UI: @@ -55,6 +48,10 @@ To open the Web IDE Beta from a merge request: 1. Go to your merge request. 1. In the upper-right corner, select **Code > Open in Web IDE**. +The Web IDE Beta opens new and modified files in separate tabs and displays changes side by side with the original source. To optimize loading time, only the top 10 files (by number of lines changed) are opened automatically. + +In the file tree, any new or modified file in the merge request is indicated by an icon next to the filename. To view changes to a file, right-click the filename and select **Compare with merge request base**. + ## Open a file in the Web IDE Beta To open any file by its name: @@ -99,11 +96,21 @@ Full file search is planned for a later date. ## View a list of changed files To view a list of files you changed in the Web IDE Beta, -in the Activity Bar on the left, select **Source Control**. +on the Activity Bar on the left, select **Source Control**. Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. For details, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). +## Commit changes + +To commit your changes in the Web IDE Beta: + +1. On the Activity Bar on the left, select **Source Control**, +or press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. +1. Enter your commit message. +1. Select **Commit & Push**. +1. Commit to the current branch, or create a new branch. + ## Open the command palette In the Web IDE Beta, you can access many commands through the command palette. @@ -128,8 +135,3 @@ The [Web Terminal](../web_ide/index.md#interactive-web-terminals-for-the-web-ide and [Live Preview](../web_ide/index.md#live-preview-removed) are not available in the Web IDE Beta. These features might become available at a later date. - -## Related topics - -- [Remote Development](../remote_development/index.md) -- [Web IDE](../web_ide/index.md) diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 1513ea18ed2..a3a6cad65e1 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- @@ -71,7 +71,7 @@ To open group settings: 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: - - **Enabled**: Everyone who can access the group can access the wiki. + - **Enabled**: For public groups, everyone can access the wiki. For internal groups, only authenticated users can access the wiki. - **Private**: Only group members can access the wiki. - **Disabled**: The wiki isn't accessible, and cannot be downloaded. 1. Select **Save changes**. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index f01331ac784..eb13814f2ad 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +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 --- diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 24ca86fc93b..69087791a3e 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -328,7 +328,7 @@ download starts, the `insteadOf` configuration sends the traffic to the secondar - [Import a project](../../user/project/import/index.md). - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). -- [Fork a project](repository/forking_workflow.md#creating-a-fork). +- [Fork a project](repository/forking_workflow.md#create-a-fork). - [Adjust project visibility and access levels](settings/index.md#configure-project-visibility-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 87380ec324e..58eebc16d74 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -95,8 +95,7 @@ For more information, see [Restrict visibility levels](admin_area/settings/visib ## Related topics -- For more granular control of project features, you can - [change the visibility of features](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project). +- [Change the visibility of features](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project) <!-- ## Troubleshooting diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index a20a699e550..de2b82c28d3 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -66,5 +66,4 @@ A URL to the reported user's comment is pre-filled in the abuse report's ## Related topics -- Administrators can view and resolve abuse reports. - For more information, see [abuse reports administration documentation](admin_area/review_abuse_reports.md). +- [Abuse reports administration documentation](admin_area/review_abuse_reports.md) diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md index 76a298a2cee..674b2813985 100644 --- a/doc/user/search/exact_code_search.md +++ b/doc/user/search/exact_code_search.md @@ -10,9 +10,8 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt` which enables indexing and searching respectively. Both are disabled by default. WARNING: -Exact Code Search is an MVC. For the Exact Code Search feature roadmap, see [epic 9404](https://gitlab.com/groups/gitlab-org/-/epics/9404). -When this feature reaches the [**Alpha**](../../policy/alpha-beta-support.md#alpha-features) version, GitLab will dogfood it, and roll it out only to specific customers on GitLab.com who request access to it. -On self-managed GitLab, this feature is available and can be enabled. However, GitLab does not provide support or documentation at this development stage. +We are still actively making changes to the Exact Code Search feature. GitLab will dogfood it first, and roll it out only to specific customers on GitLab.com who request access to it. We will make an announcement when it's available for GitLab.com customers to tryout. You can follow our development progress by checking [the Exact Code Search feature roadmap](https://gitlab.com/groups/gitlab-org/-/epics/9404). +On self-managed GitLab, it is technically possible to enable this feature, however, GitLab does not provide support or documentation at this stage of development and it has not been widely tested at scale. There are also many known limitations. ## Usage @@ -27,5 +26,7 @@ expressions, certain special characters will require escaping. Backslash can escape special characters and wrapping in double quotes can be used for phrase searches. +## Syntax + To understand the possible filtering options, see the [Zoekt query syntax](https://github.com/sourcegraph/zoekt/blob/main/doc/query_syntax.md). diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 310d733800a..f6733abd305 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -95,12 +95,10 @@ To filter code search results by one or more languages: ## Search for projects by full path -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `full_path_project_search`. -On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/388473) on GitLab.com in GitLab 15.9. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111808) on self-managed GitLab 15.10. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. You can search for a project by entering its full path (including the namespace it belongs to) in the search box. As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 9c2925ec647..c0d2b74fd84 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,9 +1,8 @@ --- stage: Create -group: Editor +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 type: reference -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' --- # GitLab keyboard shortcuts **(FREE)** @@ -242,7 +241,7 @@ This shortcut is available when viewing a [wiki page](project/wiki/index.md): ### Content editor These shortcuts are available when editing a file with the -[Content Editor](https://about.gitlab.com/direction/create/editor/content_editor/): +[Content Editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/): | macOS shortcut | Windows shortcut | Description | |----------------|------------------|-------------| diff --git a/doc/user/ssh.md b/doc/user/ssh.md index 7b6fa66b1d7..a74c3fea360 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -20,8 +20,6 @@ SSH uses two keys, a public key and a private key. - The public key can be distributed. - The private key should be protected. -When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. - You cannot expose data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. You can use your private key to [sign commits](project/repository/ssh_signed_commits/index.md), @@ -280,7 +278,7 @@ You can use [1Password](https://1password.com/) and the [1Password browser exten 1. Sign in to GitLab. 1. On the top bar, in the upper-right corner, select your avatar. -1. Select **Preferences**. +1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. 1. Select **Key**, and you should see the 1Password helper appear. 1. Select the 1Password icon and unlock 1Password. @@ -291,7 +289,7 @@ You can use [1Password](https://1password.com/) and the [1Password browser exten 1. Optional. Update **Expiration date** to modify the default expiration date. 1. Select **Add key**. -For more information about using 1Password with SSH keys, see the [1Password documentation](https://developer.1password.com/docs/ssh/get-started). +For more information about using 1Password with SSH keys, see the [1Password documentation](https://developer.1password.com/docs/ssh/get-started/). ## Add an SSH key to your GitLab account @@ -325,7 +323,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: 1. Sign in to GitLab. 1. On the top bar, in the upper-right corner, select your avatar. -1. Select **Preferences**. +1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. 1. In the **Key** box, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key, @@ -398,7 +396,7 @@ on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`. 1. Sign in to GitLab. 1. On the top bar, in the upper-right corner, select your avatar. -1. Select **Preferences**. +1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. Your existing SSH keys are listed at the bottom of the page. The information includes: diff --git a/doc/user/tasks.md b/doc/user/tasks.md index eb0184da929..48a6b3e6490 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -298,10 +298,6 @@ To add a task to an iteration: > - Filtering activity [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389971) in GitLab 15.10. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.10. -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 always change the sorting order to **Newest first**, which is remembered across sessions. You can also filter activity by **Comments only** and **History only** in addition to the default **All activity** which is remembered across sessions. diff --git a/doc/user/todos.md b/doc/user/todos.md index 4951ba024af..29fe3336ea2 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -1,5 +1,4 @@ --- -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/todos.html' 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 @@ -34,12 +33,13 @@ Also, you can sort them by [**Label priority**](project/labels.md#set-label-prio ## Actions that create to-do items Many to-do items are created automatically. -A to-do item is added to your To-Do List when: +Some of the actions that add a to-do item to your To-Do List: - An issue or merge request is assigned to you. +- A [merge request review](project/merge_requests/reviews/index.md) is requested. - You're [mentioned](discussions/index.md#mentions) in the description or comment of an issue, merge request, or epic. -- You are mentioned in a comment on a commit or design. +- You're mentioned in a comment on a commit or design. - The CI/CD pipeline for your merge request fails. - An open merge request cannot be merged due to conflict, and one of the following is true: diff --git a/doc/user/workspace/quick_start/index.md b/doc/user/workspace/quick_start/index.md new file mode 100644 index 00000000000..933dbf1766b --- /dev/null +++ b/doc/user/workspace/quick_start/index.md @@ -0,0 +1,18 @@ +--- +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 +type: reference +--- + +> Introduced in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `remote_development_feature_flag`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +# Tutorial: Create and run your first GitLab Workspace **(ULTIMATE)** + +This tutorial shows you how to configure and run your first Remote Development Workspace in GitLab. |
