diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-11-18 13:16:36 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-11-18 13:16:36 +0000 |
| commit | 311b0269b4eb9839fa63f80c8d7a58f32b8138a0 (patch) | |
| tree | 07e7870bca8aed6d61fdcc810731c50d2c40af47 /doc/user | |
| parent | 27909cef6c4170ed9205afa7426b8d3de47cbb0c (diff) | |
| download | gitlab-ce-311b0269b4eb9839fa63f80c8d7a58f32b8138a0.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-5-stable-eev14.5.0-rc42
Diffstat (limited to 'doc/user')
261 files changed, 4790 insertions, 2497 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index b5294bb265d..62fea3c266a 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -4,21 +4,21 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# DevOps Report **(FREE SELF)** +# DevOps Reports **(FREE SELF)** -> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) from Conversational Development Index in GitLab 12.6. - -The DevOps Report gives you an overview of your entire instance's adoption of +DevOps Reports give you an overview of your entire instance's adoption of [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) from planning to monitoring. -To see DevOps Report: +To see DevOps Reports: 1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Analytics > DevOps Report**. +1. On the left sidebar, select **Analytics > DevOps Reports**. ## DevOps Score +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) from Conversational Development Index in GitLab 12.6. + NOTE: To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). This is because DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. @@ -72,4 +72,4 @@ DevOps Adoption allows you to: - Identify specific groups that are lagging in their adoption of GitLab, so you can help them along in their DevOps journey. - Find the groups that have adopted certain features, and can provide guidance to other groups on how to use those features. - + diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index dd1efc913fa..cd505e154c6 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -15,5 +15,5 @@ Administrators have access to instance-wide analytics: There are several kinds of statistics: -- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. +- [DevOps Reports](dev_ops_report.md): Provides an overview of your entire instance's feature usage. - [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. diff --git a/doc/user/admin_area/img/index_runners_search_or_filter_v14_1.png b/doc/user/admin_area/img/index_runners_search_or_filter_v14_1.png Binary files differdeleted file mode 100644 index ab196a0ca9e..00000000000 --- a/doc/user/admin_area/img/index_runners_search_or_filter_v14_1.png +++ /dev/null diff --git a/doc/user/admin_area/img/index_runners_search_or_filter_v14_5.png b/doc/user/admin_area/img/index_runners_search_or_filter_v14_5.png Binary files differnew file mode 100644 index 00000000000..10b8cc01103 --- /dev/null +++ b/doc/user/admin_area/img/index_runners_search_or_filter_v14_5.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 27d2bd8f764..4de2397706b 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -107,6 +107,22 @@ You can combine the filter options. For example, to list only public projects wi 1. Click the **Public** tab. 1. Enter `score` in the **Filter by name...** input box. +#### Deleted projects **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3. + +When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-removal), +projects within that group are not deleted immediately, but only after a delay. To access a list of all projects that are pending deletion: + +1. On the top bar, select **Menu > Projects > Explore projects**. +1. Select the **Deleted projects** tab. + +Listed for each project is: + +- The time the project was marked for deletion. +- The time the project is scheduled for final deletion. +- A **Restore** link to stop the project being eventually deleted. + ### Administering Users You can administer all users in the GitLab instance from the Admin Area's Users page: @@ -241,21 +257,27 @@ To [Create a new group](../group/index.md#create-a-group) click **New group**. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. -You can administer all topics in the GitLab instance from the Admin Area's Topics page. +You can administer all [topics](../project/working_with_projects.md#explore-topics) in the +GitLab instance from the Admin Area's Topics page. To access the Topics page: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Topics**. -For each topic, the page displays their name and number of projects labeled with the topic. +For each topic, the page displays its name and the number of projects labeled with the topic. To create a new topic, select **New topic**. To edit a topic, select **Edit** in that topic's row. To search for topics by name, enter your criteria in the search box. The topic search is case -insensitive, and applies partial matching. +insensitive and applies partial matching. + +NOTE: +The assigned topics are visible only to everyone with access to the project, +but everyone can see which topics exist at all on the GitLab instance. +Do not include sensitive information in the name of a topic. ### Administering Jobs @@ -309,11 +331,11 @@ To search runners' descriptions: You can also filter runners by status, type, and tag. To filter: -1. Click in the **Search or filter results...** field. -1. Select **Status**, **Type**, or **Tags**. +1. Select a tab or the **Search or filter results...** field. +1. Select any **Type**, or filter by **Status** or **Tags**. 1. Select or enter your search criteria. - + For each runner, the following attributes are listed: diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 18151fc17d5..0ecf76902e1 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -5,34 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request approval rules **(PREMIUM SELF)** +# Merge request approvals **(PREMIUM SELF)** -> Introduced in [GitLab Premium](https://gitlab.com/gitlab-org/gitlab/-/issues/39060) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39060) in GitLab 12.8. -Merge request approval rules prevent users from overriding certain settings on the project -level. When enabled at the instance level, these settings are no longer editable on the -project level. +Merge request approval rules prevent users from overriding certain settings on the project level. +When enabled at the instance level, these settings [cascade](../project/merge_requests/approvals/settings.md#settings-cascading) +and can no longer be changed: -To enable merge request approval rules for an instance: +- In projects. +- In groups. Cascading to groups was [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) + in GitLab 14.5. + +To enable merge request approval settings for an instance: 1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request (MR) approvals**. -1. Set the required rule. +1. On the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request approvals**. +1. Choose the required options. 1. Click **Save changes**. ## Available rules -Merge request approval rules that can be set at an instance level are: +Merge request approval settings that can be set at an instance level are: -- **Prevent approval by author**. Prevents project -maintainers from allowing request authors to merge their own merge requests. -- **Prevent approvals by users who add commits**. Prevents project -maintainers from allowing users to approve merge requests if they have submitted -any commits to the source branch. -- **Prevent editing approval rules in projects and merge requests**. Prevents users from -modifying the approvers list in project settings or in individual merge requests. +- **Prevent approval by author**. Prevents project maintainers from allowing request authors to + merge their own merge requests. +- **Prevent approvals by users who add commits**. Prevents project maintainers from allowing users + to approve merge requests if they have submitted any commits to the source branch. +- **Prevent editing approval rules in projects and merge requests**. Prevents users from modifying + the approvers list in project settings or in individual merge requests. See also the following, which are affected by instance-level rules: -- [Project-level merge request approval rules](../project/merge_requests/approvals/index.md). -- [Group-level merge request approval rules](../group/index.md#group-approval-rules) available in GitLab 13.9 and later. +- [Project merge request approval rules](../project/merge_requests/approvals/index.md). +- [Group merge request approval rules](../group/index.md#group-approval-rules) available in GitLab 13.9 and later. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index c8f160f729f..a98250dfc56 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -17,7 +17,7 @@ pending approval state because an administrator has enabled any of the following - [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. - [User cap](settings/sign_up_restrictions.md#user-cap). -- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#initial-omniauth-configuration) +- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#configure-initial-settings) - [Block auto-created users (LDAP)](../../administration/auth/ldap/index.md#basic-configuration-settings) When a user registers for an account while this setting is enabled: diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index da245300e1d..66001a987a4 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -24,7 +24,7 @@ prevent integer overflow for some tables. ## Check the status of background migrations All migrations must have a `Finished` status before you [upgrade GitLab](../../../update/index.md). -You can [check the status of existing migrations](../../../update/index.md#checking-for-background-migrations-before-upgrading). +You can [check the status of existing migrations](../../../update/index.md#batched-background-migrations). ## Enable or disable batched background migrations diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index c5ffb032afd..1d2d7be146c 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,8 +1,7 @@ --- -stage: none -group: unassigned +stage: Monitor +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: concepts, howto --- # Health Check **(FREE SELF)** diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 3549aa5323b..c511e85f3ce 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -61,10 +61,15 @@ details. ## Personal Access Token prefix +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. + You can set a global prefix for all generated Personal Access Tokens. A prefix can help you identify PATs visually, as well as with automation tools. +NOTE: +For GitLab.com and self-managed instances, the default prefix is `glpat-`. + ### Set a prefix Only a GitLab administrator can set the prefix, which is a global setting applied @@ -125,7 +130,7 @@ is rejected. NOTE: The repository size limit includes repository files and LFS, but does not include artifacts, uploads, -wiki, packages, or snippets. +wiki, packages, or snippets. The repository size limit applies to both private and public projects. For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). @@ -148,7 +153,7 @@ add the line below to `/etc/gitlab/gitlab.rb` before increasing the max attachme nginx['client_max_body_size'] = "200m" ``` -## Customize session duration for Git Operations when 2FA is enabled **(PREMIUM)** +## Customize session duration for Git Operations when 2FA is enabled **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296669) in GitLab 13.9. > - It's deployed behind a feature flag, disabled by default. @@ -173,7 +178,7 @@ To set a limit on how long these sessions are valid: ## Limit the lifetime of personal access tokens **(ULTIMATE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab Ultimate 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. Users can optionally specify a lifetime for [personal access tokens](../../profile/personal_access_tokens.md). @@ -222,7 +227,7 @@ Disabling SSH key expiration immediately enables all expired SSH keys. ## Allow expired Personal Access Tokens to be used **(ULTIMATE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab Ultimate 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab 13.1. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296881) in GitLab 13.9. By default, expired personal access tokens (PATs) **are not usable**. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 1b6da0e2806..565e905d732 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -221,7 +221,7 @@ It is also possible to specify a [custom CI/CD configuration file for a specific By default, a banner displays in merge requests with no pipeline suggesting a walkthrough on how to add one. - + To enable or disable the banner: diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md index a2edb6da86e..9be703f3b82 100644 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ b/doc/user/admin_area/settings/deprecated_api_rate_limits.md @@ -47,7 +47,7 @@ To override the general user and IP rate limits for requests to deprecated API e 1. Select the **Maximum authenticated API requests per period per user**. 1. Select the **Authenticated API rate limit period in seconds**. -## Resources +## Related topics - [Rate limits](../../../security/rate_limits.md) - [User and IP rate limits](user_and_ip_rate_limits.md) diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md index f91d4b2fb0c..4f0f50dbcd2 100644 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ b/doc/user/admin_area/settings/files_api_rate_limits.md @@ -49,7 +49,7 @@ To override the general user and IP rate limits for requests to the Repository f 1. Select the **Max authenticated API requests per period per user**. 1. Select the **Authenticated API rate limit period in seconds**. -## Resources +## Related topics - [Rate limits](../../../security/rate_limits.md) - [Repository files API](../../../api/repository_files.md) diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md index 8a0754374e2..adc6cc2b11b 100644 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ b/doc/user/admin_area/settings/git_lfs_rate_limits.md @@ -29,7 +29,7 @@ supersede the [general user and IP rate limits](user_and_ip_rate_limits.md): 1. Enter a value for **Authenticated Git LFS rate limit period in seconds**. 1. Select **Save changes**. -## Resources +## Related topics - [Rate limiting](../../../security/rate_limits.md) - [User and IP rate limits](user_and_ip_rate_limits.md) diff --git a/doc/user/admin_area/settings/img/suggest_pipeline_banner.png b/doc/user/admin_area/settings/img/suggest_pipeline_banner.png Binary files differdeleted file mode 100644 index 9f118ccc5ed..00000000000 --- a/doc/user/admin_area/settings/img/suggest_pipeline_banner.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/suggest_pipeline_banner_v14_5.png b/doc/user/admin_area/settings/img/suggest_pipeline_banner_v14_5.png Binary files differnew file mode 100644 index 00000000000..0d9bfa4a173 --- /dev/null +++ b/doc/user/admin_area/settings/img/suggest_pipeline_banner_v14_5.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 688734849e5..7945e5d790f 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -7,124 +7,186 @@ type: index # Admin Area settings **(FREE SELF)** -As an administrator of a GitLab self-managed instance, you can manage the behavior of your deployment. To do so, select **Admin Area > Settings**. +As an administrator of a GitLab self-managed instance, you can manage the behavior of your +deployment. -The Admin Area is not accessible on GitLab.com, and settings can only be changed by the -GitLab.com administrators. See the [GitLab.com settings](../../gitlab_com/index.md) -documentation for all current settings and limits on the GitLab.com instance. +The **Admin Area** is not accessible on GitLab.com, and settings can only be changed by the +GitLab.com administrators. For the settings and limits on the GitLab.com instance, +read [GitLab.com settings](../../gitlab_com/index.md). -## General +## Access the Admin Area -To access the default page for Admin Area settings: +To access the **Admin Area**: +1. Sign in to your GitLab instance as an administrator. 1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > General**. - -| Option | Description | -| ------ | ----------- | -| [Visibility and access controls](visibility_and_access_controls.md) | Set default and restrict visibility levels. Configure import sources and Git access protocol. | -| [Account and limit](account_and_limit_settings.md) | Set projects and maximum size limits, session duration, user options, and check feature availability for namespace plan. | -| [Diff limits](../diff_limits.md) | Diff content limits. | -| [Sign-up restrictions](sign_up_restrictions.md) | Configure the way a user creates a new account. | -| [Sign in restrictions](sign_in_restrictions.md) | Set requirements for a user to sign in. Enable mandatory two-factor authentication. | -| [Terms of Service and Privacy Policy](terms.md) | Include a Terms of Service agreement and Privacy Policy that all users must accept. | -| [External Authentication](external_authorization.md#configuration) | External Classification Policy Authorization | -| [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) | Set max session time for web terminal. | -| [Web IDE](../../project/web_ide/index.md#enable-live-preview) | Manage Web IDE features. | -| [FLoC](floc.md) | Enable or disable [Federated Learning of Cohorts (FLoC)](https://en.wikipedia.org/wiki/Federated_Learning_of_Cohorts) tracking. | - -## Integrations - -| Option | Description | -| ------ | ----------- | -| [Elasticsearch](../../../integration/elasticsearch.md#enable-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | -| [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). | -| [Mailgun](../../../administration/integration/mailgun.md) | Enable your GitLab instance to receive invite email bounce events from Mailgun, if it is your email provider. | -| [PlantUML](../../../administration/integration/plantuml.md) | Allow rendering of PlantUML diagrams in documents. | -| [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | -| [Third party offers](third_party_offers.md) | Control the display of third party offers. | -| [Snowplow](../../../development/snowplow/index.md) | Configure the Snowplow integration. | -| [Google GKE](../../project/clusters/add_gke_clusters.md) | Google GKE integration allows you to provision GKE clusters from GitLab. | -| [Amazon EKS](../../project/clusters/add_eks_clusters.md) | Amazon EKS integration allows you to provision EKS clusters from GitLab. | - -## Repository - -| Option | Description | -| ------ | ----------- | -| [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) | Set a custom branch name for new repositories created in your instance. | -| [Repository mirror](visibility_and_access_controls.md#enable-project-mirroring) | Configure repository mirroring. | -| [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. | -| Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. | -| [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives and blobs) from an external storage (for example, a CDN). | - -## Templates **(PREMIUM SELF)** - -| Option | Description | -| ------ | ----------- | -| [Templates](instance_template_repository.md#configuration) | Set instance-wide template repository. | -| [Custom project templates](../custom_project_templates.md) | Select the custom project template source group. | - -## CI/CD - -| Option | Description | -| ------ | ----------- | -| [Continuous Integration and Deployment](continuous_integration.md) | Auto DevOps, runners and job artifacts. | -| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM SELF)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/index.md). This pipeline configuration is run after the project's own configuration. | -| [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using the GitLab Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | - -## Reporting - -| Option | Description | -| ------ | ----------- | -| [Spam and Anti-bot Protection](../../../integration/recaptcha.md) | Enable reCAPTCHA or Akismet and set IP limits. For reCAPTCHA, we currently only support [v2](https://developers.google.com/recaptcha/docs/versions). | -| [Abuse reports](../review_abuse_reports.md) | Set notification email for abuse reports. | - -## Metrics and profiling - -| Option | Description | -| ------ | ----------- | -| [Metrics - Prometheus](../../../administration/monitoring/prometheus/gitlab_metrics.md) | Enable and configure Prometheus metrics. | -| [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integration-with-gitlab-ui) | Enable and configure Grafana. | -| [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-for-non-administrators) | Enable access to the Performance Bar for non-administrator users in a given group. | -| [Self monitoring](../../../administration/monitoring/gitlab_self_monitoring_project/index.md#create-the-self-monitoring-project) | Enable or disable instance self monitoring. | -| [Usage statistics](usage_statistics.md) | Enable or disable version check and Service Ping. | -| [Pseudonymizer data collection](../../../administration/pseudonymizer.md) **(ULTIMATE)** | Enable or disable the Pseudonymizer data collection. | - -## Network - -| Option | Description | -| ------ | ----------- | -| Performance optimization | [Write to "authorized_keys" file](../../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell) and [Push event activities limit and bulk push events](push_event_activities_limit.md). Various settings that affect GitLab performance. | -| [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. | -| [Package Registry Rate Limits](package_registry_rate_limits.md) | Configure specific limits for Packages API requests that supersede the user and IP rate limits. | -| [Git LFS Rate Limits](git_lfs_rate_limits.md) | Configure specific limits for Git LFS requests that supersede the user and IP rate limits. | -| [Files API Rate Limits](files_api_rate_limits.md) | Configure specific limits for Files API requests that supersede the user and IP rate limits. | -| [Deprecated API Rate Limits](deprecated_api_rate_limits.md) | Configure specific limits for deprecated API requests that supersede the user and IP rate limits. | -| [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. | -| [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. | -| [Incident Management](../../../operations/incident_management/index.md) Limits | Limit the 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. | - -## Geo - -| Option | Description | -| ------ | ----------- | -| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings** are no longer available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | - -## Preferences - -| Option | Description | -| ------ | ----------- | -| [Email](email.md) | Various email settings. | -| [What's new](../../../administration/whats-new.md) | Configure What's new drawer and content. | -| [Help page](help_page.md) | Help page text and support page URL. | -| [Pages](../../../administration/pages/index.md#custom-domain-verification) | Size and domain settings for static websites | -| [Polling interval multiplier](../../../administration/polling.md) | Configure how frequently the GitLab UI polls for updates. | -| [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | -| Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | -| [Sidekiq Job Limits](sidekiq_job_limits.md) | Limit the size of Sidekiq jobs stored in Redis. | - -### Default first day of the week +1. On the left sidebar, select **Settings**, and the group of settings to view: + - [General](#general) + - [Geo](#geo) + - [CI/CD](#cicd) + - [Integrations](#integrations) + - [Metrics and profiling](#metrics-and-profiling) + - [Network](#network) + - [Preferences](#preferences) + - [Reporting](#reporting) + - [Repository](#repository) + - [Templates](#templates) + +### General + +The **General** settings contain: + +- [Visibility and access controls](visibility_and_access_controls.md) - Set default and + restrict visibility levels. Configure import sources and Git access protocol. +- [Account and limit](account_and_limit_settings.md) - Set projects and maximum size limits, + session duration, user options, and check feature availability for namespace plan. +- [Diff limits](../diff_limits.md) - Diff content limits. +- [Sign-up restrictions](sign_up_restrictions.md) - Configure the way a user creates a new account. +- [Sign in restrictions](sign_in_restrictions.md) - Set requirements for a user to sign in. + Enable mandatory two-factor authentication. +- [Terms of Service and Privacy Policy](terms.md) - Include a Terms of Service agreement + and Privacy Policy that all users must accept. +- [External Authentication](external_authorization.md#configuration) - External Classification Policy Authorization. +- [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) - + Set max session time for web terminal. +- [Web IDE](../../project/web_ide/index.md#enable-live-preview) - Manage Web IDE features. +- [FLoC](floc.md) - Enable or disable + [Federated Learning of Cohorts (FLoC)](https://en.wikipedia.org/wiki/Federated_Learning_of_Cohorts) tracking. + +### CI/CD + +The **CI/CD** settings contain: + +- [Continuous Integration and Deployment](continuous_integration.md) - + Auto DevOps, runners and job artifacts. +- [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) - + Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/index.md). + This pipeline configuration is run after the project's own configuration. +- [Package Registry](continuous_integration.md#package-registry-configuration) - + Settings related to the use and experience of using the GitLab Package Registry. Some + [risks are involved](../../packages/container_registry/index.md#use-with-external-container-registries) + in enabling some of these settings. + +### Geo **(PREMIUM SELF)** + +The **Geo** setting contains: + +- [Geo](../../../administration/geo/index.md) - Replicate your GitLab instance to other + geographical locations. Redirects to **Admin Area > Geo > Settings** are no + longer available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). + +### Integrations + +The **Integrations** settings contain: + +- [Elasticsearch](../../../integration/elasticsearch.md#enable-advanced-search) - + Elasticsearch integration. Elasticsearch AWS IAM. +- [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) - + Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). +- [Mailgun](../../../administration/integration/mailgun.md) - Enable your GitLab instance + to receive invite email bounce events from Mailgun, if it is your email provider. +- [PlantUML](../../../administration/integration/plantuml.md) - Allow rendering of PlantUML + diagrams in documents. +- [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) - + Slack integration allows you to interact with GitLab via slash commands in a chat window. + This option is only available on GitLab.com, though it may be + [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). +- [Third party offers](third_party_offers.md) - Control the display of third-party offers. +- [Snowplow](../../../development/snowplow/index.md) - Configure the Snowplow integration. +- [Google GKE](../../project/clusters/add_gke_clusters.md) - Google GKE integration enables + you to provision GKE clusters from GitLab. +- [Amazon EKS](../../project/clusters/add_eks_clusters.md) - Amazon EKS integration enables + you to provision EKS clusters from GitLab. + +### Metrics and profiling + +The **Metrics and profiling** settings contain: + +- [Metrics - Prometheus](../../../administration/monitoring/prometheus/gitlab_metrics.md) - + Enable and configure Prometheus metrics. +- [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integration-with-gitlab-ui) - + Enable and configure Grafana. +- [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-for-non-administrators) - + Enable access to the Performance Bar for non-administrator users in a given group. +- [Self monitoring](../../../administration/monitoring/gitlab_self_monitoring_project/index.md#create-the-self-monitoring-project) - + Enable or disable instance self monitoring. +- [Usage statistics](usage_statistics.md) - Enable or disable version check and Service Ping. +- [Pseudonymizer data collection](../../../administration/pseudonymizer.md) - + Enable or disable the Pseudonymizer data collection. + +### Network + +The **Network** settings contain: + +- Performance optimization - Various settings that affect GitLab performance, including: + - [Write to `authorized_keys` file](../../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell). + - [Push event activities limit and bulk push events](push_event_activities_limit.md). +- [User and IP rate limits](user_and_ip_rate_limits.md) - Configure limits for web and API requests. + These rate limits can be overridden: + - [Package Registry Rate Limits](package_registry_rate_limits.md) - Configure specific + limits for Packages API requests that supersede the user and IP rate limits. + - [Git LFS Rate Limits](git_lfs_rate_limits.md) - Configure specific limits for + Git LFS requests that supersede the user and IP rate limits. + - [Files API Rate Limits](files_api_rate_limits.md) - Configure specific limits for + Files API requests that supersede the user and IP rate limits. + - [Deprecated API Rate Limits](deprecated_api_rate_limits.md) - Configure specific limits + for deprecated API requests that supersede the user and IP rate limits. +- [Outbound requests](../../../security/webhooks.md) - Allow requests to the local network from hooks and services. +- [Protected Paths](protected_paths.md) - Configure paths to be protected by Rack Attack. +- [Incident Management Limits](../../../operations/incident_management/index.md) - Limit the + 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. + +### Preferences + +The **Preferences** settings contain: + +- [Email](email.md) - Various email settings. +- [What's new](../../../administration/whats-new.md) - Configure **What's new** drawer and content. +- [Help page](help_page.md) - Help page text and support page URL. +- [Pages](../../../administration/pages/index.md#custom-domain-verification) - + Size and domain settings for static websites. +- [Polling interval multiplier](../../../administration/polling.md) - + Configure how frequently the GitLab UI polls for updates. +- [Gitaly timeouts](gitaly_timeouts.md) - Configure Gitaly timeouts. +- Localization: + - [Default first day of the week](../../profile/preferences.md). + - [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). +- [Sidekiq Job Limits](sidekiq_job_limits.md) - Limit the size of Sidekiq jobs stored in Redis. + +### Reporting + +The **Reporting** settings contain: + +- [Spam and Anti-bot Protection](../../../integration/recaptcha.md) - + Enable anti-spam services, like reCAPTCHA or Akismet, and set IP limits. +- [Abuse reports](../review_abuse_reports.md) - Set notification email for abuse reports. + +### Repository + +The **Repository** settings contain: + +- [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) - + Set a custom branch name for new repositories created in your instance. +- [Repository mirror](visibility_and_access_controls.md#enable-project-mirroring) - + Configure repository mirroring. +- [Repository storage](../../../administration/repository_storage_types.md) - Configure storage path settings. +- Repository maintenance: + - [Repository checks](../../../administration/repository_checks.md) - Configure + automatic Git checks on repositories. + - [Housekeeping](../../../administration/housekeeping.md)). Configure automatic + Git housekeeping on repositories. +- [Repository static objects](../../../administration/static_objects_external_storage.md) - + Serve repository static objects (for example, archives and blobs) from an external storage (for example, a CDN). + +### Templates **(PREMIUM SELF)** + +The **Templates** settings contain: + +- [Templates](instance_template_repository.md#configuration) - Set instance-wide template repository. +- [Custom project templates](../custom_project_templates.md) - Select the custom project template source group. + +## Default first day of the week You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance: diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 044863729db..71eb7bbbdc9 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -7,7 +7,7 @@ type: reference # Instance template repository **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab Premium 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab 11.3. In hosted systems, enterprises often have a need to share their own templates across teams. This feature allows an administrator to pick a project to be the diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index dc328fe8b7c..e686c65fe9a 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -7,28 +7,11 @@ type: reference # Protected paths **(FREE SELF)** -Rate limiting is a common technique used to improve the security and durability -of a web application. For more details, see -[Rate limits](../../../security/rate_limits.md). +Rate limiting is a technique that improves the security and durability of a web +application. For more details, see [Rate limits](../../../security/rate_limits.md). -GitLab rate limits the following paths with Rack Attack by default: - -```plaintext -'/users/password', -'/users/sign_in', -'/api/#{API::API.version}/session.json', -'/api/#{API::API.version}/session', -'/users', -'/users/confirmation', -'/unsubscribes/', -'/import/github/personal_access_token', -'/admin/session' -``` - -GitLab responds with HTTP status code `429` to POST requests at protected paths -that exceed 10 requests per minute per IP address. - -See [User and IP rate limits](../../admin_area/settings/user_and_ip_rate_limits.md#response-headers) for the headers responded to blocked requests. +You can rate limit (protect) specified paths. For these paths, GitLab responds with HTTP status +code `429` to POST requests at protected paths that exceed 10 requests per minute per IP address. For example, the following are limited to a maximum 10 requests per minute: @@ -36,10 +19,15 @@ For example, the following are limited to a maximum 10 requests per minute: - User sign-up (if enabled) - User password reset -After 10 requests, the client must wait 60 seconds before it can -try again. +After 10 requests, the client must wait 60 seconds before it can try again. + +See also: + +- List of paths [protected by default](../../../administration/instance_limits.md#by-protected-path). +- [User and IP rate limits](../../admin_area/settings/user_and_ip_rate_limits.md#response-headers) + for the headers returned to blocked requests. -## Configure using GitLab UI +## Configure protected paths > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31246) in GitLab 12.4. diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 020d02b1635..028d5e4c2f3 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -7,7 +7,7 @@ type: reference # Rate limits on raw endpoints **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30829) in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30635) in GitLab 12.2. This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: @@ -21,7 +21,7 @@ For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gi This limit is: -- Applied independently per project, per commit and per file path. +- Applied independently per project, per file path. - Not applied per IP address. - Active by default. To disable, set the option to `0`. diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index ed80bca470e..8ce3b4f1c18 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -48,7 +48,7 @@ automatically approved in a background job. NOTE: This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for new users signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the -[OmniAuth configuration](../../../integration/omniauth.md#initial-omniauth-configuration) or +[OmniAuth configuration](../../../integration/omniauth.md#configure-initial-settings) or [LDAP configuration](../../../administration/auth/ldap/index.md#basic-configuration-settings). ## Require email confirmation diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index c7c41e665ec..693b3e6c7b6 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -28,13 +28,13 @@ To enforce acceptance of a Terms of Service and Privacy Policy: For each update to the terms, a new version is stored. When a user accepts or declines the terms, GitLab records which version they accepted or declined. +Existing users must accept the terms on their next GitLab interaction. +If a signed-in user declines the terms, they are signed out. + When enabled, it adds a mandatory checkbox to the sign up page for new users:  -Existing users must accept the terms on their next GitLab interaction. -If a logged-in user declines the terms, they are signed out. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index ac6fe29da28..d713ef4b4e0 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -76,7 +76,9 @@ To enable the unauthenticated request rate limit: ## Use a custom rate limit response -A request that exceeds a rate limit returns a 429 response code and a +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50693) in GitLab 13.8. + +A request that exceeds a rate limit returns a `429` response code and a plain-text body, which by default is `Retry later`. To use a custom response: @@ -88,7 +90,7 @@ To use a custom response: ## Response headers -> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/731) in GitLab 13.8, the `Rate-Limit` headers. `Retry-After` was introduced in an earlier version. +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/731) in GitLab 13.8, the `RateLimit` headers. `Retry-After` was introduced in an earlier version. When a client exceeds the associated rate limit, the following requests are blocked. The server may respond with rate-limiting information allowing the 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 075becfd32f..fd44d6445cf 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -68,7 +68,7 @@ GitLab administrators can still update the default branch protection of a group. ## Define which roles can create projects Instance-level protections for project creation define which roles can -[add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group)] +[add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group) on the instance. To alter which roles have permission to create projects: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 4a42133c308..e949f968c2b 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -21,6 +21,12 @@ View pipeline duration history:  +Pipeline statistics are gathered by collecting all available pipelines for the +project regardless of status. The data available for each individual day is based +on when the pipeline was created. The total pipeline calculation includes child +pipelines and pipelines that failed with invalid YAML. If you are interested in +filtering pipelines based on other attributes, consider using the [Pipelines API](../../api/pipelines.md#list-project-pipelines). + ## DevOps Research and Assessment (DORA) key metrics **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index fe091fc9899..496e768456f 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -22,7 +22,7 @@ Initially, no data appears. Data is populated as users comment on open merge req ## Overview -Code Review Analytics is available to users with Reporter access and above, and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. +Code Review Analytics is available to users with at least the Reporter [role](../permissions.md), and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. To access Code Review Analytics, from your project's menu, go to **Analytics > Code Review**. diff --git a/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png b/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png Binary files differnew file mode 100644 index 00000000000..649416c02c0 --- /dev/null +++ b/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png diff --git a/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png b/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png Binary files differnew file mode 100644 index 00000000000..b5d0dd4d2ea --- /dev/null +++ b/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png diff --git a/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png b/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png Binary files differnew file mode 100644 index 00000000000..da5d3aec957 --- /dev/null +++ b/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index c01788f4fc4..0cc21e3f390 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -6,65 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Analyze GitLab usage **(FREE)** -## Definitions - -When we describe GitLab analytics, we use the following terms: - -- **Cycle time:** The duration of only the execution work. Cycle time is often displayed in combination with the lead time, which is longer than the cycle time. 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. GitLab displays cycle time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](../analytics/value_stream_analytics.md). -- **Deploys:** The total number of successful deployments to production in the given time frame (across all applicable projects). GitLab displays deploys in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). -- **DORA (DevOps Research and Assessment)** ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): - - **Speed/Velocity** - - - **Deployment frequency:** The relative frequency of successful deployments to production - (hourly, daily, weekly, monthly, or yearly). - This effectively measures how often you are delivering value to end users. A higher deployment - frequency means you are able to get feedback and iterate more quickly in delivering - improvements and features faster. GitLab measures this as the number of deployments to a - [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in - the given time period. - GitLab displays deployment frequency in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). - - **Lead Time for Changes:** The time it takes for a commit to get into production. (1) GitLab - measures this as the median duration between merge request merge and deployment to a - [production environment](../../ci/environments/index.md#deployment-tier-of-environments) for - all MRs deployed in the given time period. This measure under-estimates lead time because - merge time is always later than commit time. The - [standard definition](https://github.com/GoogleCloudPlatform/fourkeys/blob/main/METRICS.md#lead-time-for-changes) uses median commit time. - [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/328459) to start - measuring from "issue first commit" as a better proxy, although still imperfect. - - - **Stability** - - **Change Failure Rate:** The percentage of deployments causing a failure in production. - GitLab measures this as the number of [incidents](../../operations/incident_management/incidents.md) - divided by the number of deployments to a - [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in - the given time period. This assumes: - - - All incidents are related to a production environment. - - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is - related to only one production deployment, and any production deployment is related to no - more than one incident). - - - **Time to Restore Service:** How long it takes an organization to recover from a failure in - production. GitLab measures this as the average time required to close the - [incidents](../../operations/incident_management/incidents.md) in the given time period. - This assumes: - - - All incidents are related to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). - - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is related to only one production deployment, and any production deployment is related to no more than one incident). - -- **Lead time:** The duration of your value stream, from start to finish. Different from [Lead time for changes](#lead-time-for-changes). Often displayed in combination with "cycle time," which is shorter. GitLab measures lead time from issue creation to issue close. GitLab displays lead time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). -- **MTTC (Mean Time to Change):** The average duration between idea and delivery. GitLab measures MTTC from issue creation to the issue's latest related merge request's deployment to production. -- **MTTD (Mean Time to Detect):** The average duration that a bug goes undetected in production. GitLab measures MTTD from deployment of bug to issue creation. -- **MTTM (Mean Time To Merge):** The average lifespan of a merge request. GitLab measures MTTM from merge request creation to merge request merge (and closed/un-merged merge requests are excluded). For more information, see [Merge Request Analytics](merge_request_analytics.md). -- **MTTR (Mean Time to Recover/Repair/Resolution/Resolve/Restore):** The average duration that a bug is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. -- **Throughput:** The number of issues closed or merge requests merged (not closed) in some period of time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). -- **Value Stream:** The entire work process that is followed to deliver value to customers. For example, the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). -- **Velocity:** The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points/weight of issues closed in a given period of time. - -### Lead time for changes - -"Lead Time for Changes" differs from ordinary "Lead Time" because it "focuses on measuring only the time to deliver a feature once it has been developed", as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). - ## Instance-level analytics > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab 12.2. @@ -112,3 +53,76 @@ The following analytics features are available for users to create personalized - [Application Security](../application_security/security_dashboard/#security-center) Be sure to review the documentation page for this feature for GitLab tier requirements. + +## Definitions + +We use the following terms to describe GitLab analytics: + +- **Cycle time:** The duration of only the execution work. Cycle time is often displayed in combination with the lead time, which is longer than the cycle time. 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. GitLab displays cycle time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](../analytics/value_stream_analytics.md). +- **Deploys:** The total number of successful deployments to production in the given time frame (across all applicable projects). GitLab displays deploys in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). +- **DORA (DevOps Research and Assessment)** ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): + - **Speed/Velocity** + + - **Deployment frequency:** The relative frequency of successful deployments to production + (hourly, daily, weekly, monthly, or yearly). + This measures how often you are delivering value to end users. A higher deployment + frequency means you are able to get feedback and iterate faster to deliver + improvements and features. GitLab measures this as the number of deployments to a + [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in + the given time period. + GitLab displays deployment frequency in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). + - **Lead Time for Changes:** The time it takes for a commit to get into production. GitLab + measures this as the median duration between merge request merge and deployment to a + [production environment](../../ci/environments/index.md#deployment-tier-of-environments) for + all MRs deployed in the given time period. This measure under estimates lead time because + merge time is always later than commit time. The + [standard definition](https://github.com/GoogleCloudPlatform/fourkeys/blob/main/METRICS.md#lead-time-for-changes) uses median commit time. + [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/328459) to start + measuring from "issue first commit" as a better proxy, although still imperfect. + + - **Stability** + - **Change Failure Rate:** The percentage of deployments causing a failure in production. + GitLab measures this as the number of [incidents](../../operations/incident_management/incidents.md) + divided by the number of deployments to a + [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in + the given time period. This assumes: + + - All incidents are related to a production environment. + - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is + related to only one production deployment, and any production deployment is related to no + more than one incident). + + - **Time to Restore Service:** How long it takes an organization to recover from a failure in + production. GitLab measures this as the average time required to close the + [incidents](../../operations/incident_management/incidents.md) in the given time period. + This assumes: + + - All incidents are related to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). + - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is related to only one production deployment, and any production deployment is related to no more than one incident). + +- **Lead time:** The duration of your value stream, from start to finish. Different to +[Lead time for changes](#lead-time-for-changes). Often displayed in combination with "cycle time," +which is shorter. GitLab measures lead time from issue creation to issue close. GitLab displays lead +time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). +- **Mean Time to Change (MTTC):** The average duration between idea and delivery. GitLab measures +MTTC from issue creation to the issue's latest related merge request's deployment to production. +- **Mean Time to Detect (MTTD):** The average duration that a bug goes undetected in production. +GitLab measures MTTD from deployment of bug to issue creation. +- **Mean Time To Merge (MTTM):** The average lifespan of a merge request. GitLab measures MTTM from +merge request creation to merge request merge (and closed/un-merged merge requests are excluded). +For more information, see [Merge Request Analytics](merge_request_analytics.md). +- **Mean Time to Recover/Repair/Resolution/Resolve/Restore (MTTR):** The average duration that a bug +is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. +- **Throughput:** The number of issues closed or merge requests merged (not closed) in a period of +time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). +- **Value Stream:** The entire work process that is followed to deliver value to customers. For example, +the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts +with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). +- **Velocity:** The total issue burden completed in some period of time. The burden is usually measured +in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab +measures velocity as the total points or weight of issues closed in a given period of time. + +## Lead time for changes + +"Lead Time for Changes" differs from "Lead Time" because it "focuses on measuring only the time to +deliver a feature once it has been developed", as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 2ff15c00a3f..bb110ab495f 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -116,4 +116,4 @@ bookmark for those preferred settings in your browser. The **Merge Request Analytics** feature can be accessed only: - On [GitLab Premium](https://about.gitlab.com/pricing/) and above. -- By users with [Reporter access](../permissions.md) and above. +- By users with at least the Reporter [role](../permissions.md). diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index dbe71d5f743..da55a0f093c 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -16,37 +16,79 @@ long, on average, it takes to deliver features is an enormous endeavor. While [Value Stream Analytics](../analytics/value_stream_analytics.md) focuses on the entire Software Development Life Cycle (SDLC) process, Productivity Analytics provides a way for Engineering Management to drill down in a systematic way to uncover patterns and causes for success or failure at an individual, project, or group level. -Productivity can slow down for many reasons ranging from degrading codebase to quickly growing teams. In order to investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged. +Productivity can slow down for many reasons ranging from degrading codebase to quickly growing teams. To investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged. -## Supported features +## Visualizations and metrics -Productivity Analytics allows GitLab users to: +With Productivity Analytics, GitLab users can: -- Visualize typical merge request (MR) lifetime and statistics. Use a histogram that shows the distribution of the time elapsed between creating and merging merge requests. -- Drill down into the most time consuming merge requests, select a number of outliers, and filter down all subsequent charts to investigate potential causes. +- Visualize typical merge request (MR) lifetime and statistics. A histogram shows the distribution of the time elapsed between creating and merging merge requests. +- Drill down into the most time consuming merge requests, select outliers, and filter subsequent charts to investigate potential causes. - Filter by group, project, author, label, milestone, or a specific date range. For example, filter down to the merge requests of a specific author in a group or project during a milestone or specific date range. -- Measure velocity over time. Visualize the trends of each metric from the charts above over time in order to observe progress. Zoom in on a particular date range if you notice outliers. +- Measure velocity over time. To observe progress, visualize the trends of each metric from the charts over time. Zoom in on a particular date range if you notice outliers. -## Accessing metrics and visualizations +## Metrics charts -To access the chart, navigate to a group's sidebar and select **Analytics > Productivity Analytics**. +To access the charts, navigate to a group's sidebar and select **Analytics > Productivity Analytics**. +Metrics and visualizations of **merged** merge requests are available on a project or group level. -The following metrics and visualizations are available on a project or group level - currently only covering **merged** merge requests: +### Time to merge -- Histogram showing the number of merge request that took a specified number of days to merge after creation. Select a specific column to filter down subsequent charts. -- Histogram showing a breakdown of the time taken (in hours) to merge a merge request. The following intervals are available: - - Time from first commit to first comment. - - Time from first comment until last commit. - - Time from last commit to merge. -- Histogram showing the size or complexity of a merge request, using the following: - - Number of commits per merge request. - - Number of lines of code per commit. - - Number of files touched. -- Scatterplot showing all MRs merged on a certain date, together with the days it took to complete the action and a 30 day rolling median. -- Table showing the list of merge requests with their respective time duration metrics. - - Users can sort by any of the above metrics. +The **Time to merge** histogram shows the number of merge requests and the number +of days it took to merge after creation. Select a column to filter subsequent charts. -## Date ranges + + +### Trendline + +The **Trendline** scatterplot shows all merge requests on a certain date, +and the days it took to complete the action and a 30 day rolling median. Select the dropdown to view: + +- Time from first commit to first comment. +- Time from first comment until last commit. +- Time from last commit to merge. +- Number of commits per merge request. +- Number of lines of code (LOC) per commit. +- Number of files touched. + + + +### Commits and merge request size + +Under the **Trendline** scatterplot, the left-side histogram shows +the time taken (in hours) between commits and comments until the merge +request is merged. Select the dropdown to view: + +- Time from first commit to first comment. +- Time from first comment until last commit. +- Time from last commit to merge. + +The right-side histogram shows the size or complexity of a merge request. +Select the dropdown to view: + +- Number of commits per merge request. +- Number of lines of code (LOC) per commit. +- Number of files touched. + + + +### Merge request list + +The **List** table shows a list of merge requests with their respective time duration metrics. + +Sort metrics by: + +- Time from first commit to first comment. +- Time from first comment until last commit. +- Time from last commit to merge. + +Filter metrics by: + +- Number of commits per merge request. +- Number of lines of code per commit. +- Number of files touched. + +## Filter by date range > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13188) in GitLab 12.4. @@ -61,4 +103,4 @@ You can filter analytics based on a date range. To filter results: The **Productivity Analytics** dashboard can be accessed only: - On [GitLab Premium](https://about.gitlab.com/pricing/) and above. -- By users with [Reporter access](../permissions.md) and above. +- By users with at least the Reporter [role](../permissions.md). diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index e8f8acf5661..936504187b4 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -29,7 +29,7 @@ Commits in a project's [wiki](../project/wiki/index.md#track-wiki-events) are no ### Charts -The data in the charts are updated soon after each commit in the default branch. +The data in the charts are queued. Background workers update the charts 10 minutes after each commit in the default branch. Depending on the size of the GitLab installation, it may take longer for data to refresh due to variations in the size of background job queues. Available charts: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index e32989c2915..5cef0040ac3 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -111,12 +111,9 @@ To generate an API Fuzzing configuration snippet: ### OpenAPI Specification -> Support for OpenAPI Specification v3.1 was -> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.2. -> Support for OpenAPI Specification using YAML format was -> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. -> Support for OpenAPI Specification v3.0 was -> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228652) in GitLab 13.9. +> - Support for OpenAPI Specification v3.0 was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228652) in GitLab 13.9. +> - Support for OpenAPI Specification using YAML format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. +> - Support for OpenAPI Specification v3.1 was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.2. The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. @@ -214,7 +211,7 @@ To configure API fuzzing to use a HAR file: ``` 1. Provide the location of the HAR specification. You can provide the specification as a file - or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) + or URL. URL support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_HAR` variable. 1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` @@ -285,7 +282,7 @@ To configure API fuzzing to use a Postman Collection file: ``` 1. Provide the location of the Postman Collection specification. You can provide the specification - as a file or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) + as a file or URL. URL support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_POSTMAN_COLLECTION` variable. @@ -613,15 +610,15 @@ Overrides use a JSON document, where each type of override is represented by a J }, "body-form": { "form-param1": "value", - "form-param1": "value", + "form-param2": "value" }, "body-json": { "json-path1": "value", - "json-path2": "value", + "json-path2": "value" }, "body-xml" : { "xpath1": "value", - "xpath2": "value", + "xpath2": "value" } } ``` @@ -975,7 +972,7 @@ reported. ### View details of an API Fuzzing vulnerability -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. +> Introduced in GitLab 13.7. Faults detected by API Fuzzing occur in the live web application, and require manual investigation to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a @@ -1156,12 +1153,41 @@ Profiles: ## Running API fuzzing in an offline environment -For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for the Web API Fuzz testing job to -successfully run. For more information, see [Offline environments](../offline_deployments/index.md). +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the Web API Fuzz testing job to successfully run. + +Steps: + +1. Host the Docker image in a local container registry. +1. Set the `SECURE_ANALYZERS_PREFIX` to the local container registry. + +The Docker image for API Fuzzing must be pulled (downloaded) from the public registry and then pushed (imported) into a local registry. The GitLab container registry can be used to locally host the Docker image. This process can be performed using a special template. See [loading Docker images onto your offline host](../offline_deployments/index.md#loading-docker-images-onto-your-offline-host) for instructions. + +Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-fuzzing:1` results in a valid image location. + +For example, the below line sets a registry for the image `registry.gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing:1`: + +`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/gitlab-org/security-products/analyzers"` + +NOTE: +Setting `SECURE_ANALYZERS_PREFIX` changes the Docker image registry location for all GitLab Secure templates. + +For more information, see [Offline environments](../offline_deployments/index.md). ## Troubleshooting +### Error waiting for API Security 'http://127.0.0.1:5000' to become available + +A bug exists in versions of the API Fuzzing analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the DAST API analyzer. + +The version information can be found in the job details for the `apifuzzer_fuzz` job. + +If the issue is occuring with versions v1.6.196 or greater, please contact Support and provide the following information: + +1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. +1. The full console output of the job. +1. The `gl-api-security-scanner.log` file available as a job artifact. In the right-hand panel of the job details page, select the **Browse** button. +1. The `apifuzzer_fuzz` job definition from your `.gitlab-ci.yml` file. + ### Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema At the start of an API Fuzzing job the OpenAPI Specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI Specification has validation errors. Errors can be introduced when creating an OpenAPI Specification manually, and also when the schema is generated. diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index abbe00a85ab..790b428bac9 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cluster Image Scanning **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 14.1. WARNING: This analyzer is in [Alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) @@ -26,10 +26,18 @@ GitLab provides integration with open-source tools for vulnerability analysis in To integrate GitLab with security scanners other than those listed here, see [Security scanner integration](../../../development/integrations/secure.md). -You can enable cluster image scanning by [including the CI job](#configuration) +You can use cluster image scanning through the following methods: + +- [The cluster image scanning analyzer](#use-the-cluster-image-scanning-analyzer) +- [The GitLab Kubernetes agent](#cluster-image-scanning-with-the-gitlab-kubernetes-agent) + +## Use the cluster image scanning analyzer + +You can use the cluster image scanning analyzer to run cluster image scanning with [GitLab CI/CD](../../../ci/index.md). +To enable the cluster image scanning analyzer, [include the CI job](#configuration) in your existing `.gitlab-ci.yml` file. -## Prerequisites +### Prerequisites To enable cluster image scanning in your pipeline, you need the following: @@ -45,7 +53,7 @@ To enable cluster image scanning in your pipeline, you need the following: [configuration variable](#cicd-variables-for-cluster-image-scanning) with the type set to `File` (see [Configuring the cluster](#configuring-the-cluster)). -## Configuring the cluster +### Configuring the cluster 1. Create a new service account. @@ -128,7 +136,7 @@ only. You can apply additional protection to your cluster by and [configuring Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/configuration/#install-modes) to install in restricted mode. -## Configuration +### Configuration To include the `Cluster-Image-Scanning.gitlab-ci.yml` template (GitLab 14.1 and later), add the following to your `.gitlab-ci.yml` file: @@ -149,7 +157,7 @@ GitLab saves the results as a that you can download and analyze later. When downloading, you always receive the most recent artifact. -### Customize the cluster image scanning settings +#### Customize the cluster image scanning settings You can customize how GitLab scans your cluster. For example, to restrict the analyzer to get results for only a certain workload, use the [`variables`](../../../ci/yaml/index.md#variables) @@ -157,7 +165,7 @@ parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#cicd-variables-for- The variables you set in your `.gitlab-ci.yml` overwrite those in `Cluster-Image-Scanning.gitlab-ci.yml`. -#### CI/CD variables for cluster image scanning +##### CI/CD variables for cluster image scanning You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by using the following CI/CD variables: @@ -168,8 +176,9 @@ You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by | `CIS_RESOURCE_NAME` | `""` | Name of the Kubernetes resource you want to filter vulnerabilities for. For example, `nginx`. | | `CIS_RESOURCE_NAMESPACE` | `""` | Namespace of the Kubernetes resource you want to filter vulnerabilities for. For example, `production`. | | `CIS_RESOURCE_KIND` | `""` | Kind of the Kubernetes resource you want to filter vulnerabilities for. For example, `deployment`. | +| `CIS_CLUSTER_IDENTIFIER` | `""` | ID of the Kubernetes cluster integrated with GitLab. This is used to map vulnerabilities to the cluster so they can be filtered in the Vulnerability Report page. | -### Override the cluster image scanning template +#### Override the cluster image scanning template If you want to override the job definition (for example, to change properties like `variables`), you must declare and override a job after the template inclusion, and then @@ -186,7 +195,7 @@ cluster_image_scanning: CIS_RESOURCE_NAME: nginx ``` -### Connect with Kubernetes cluster associated to the project +#### Connect with Kubernetes cluster associated to the project If you want to connect to the Kubernetes cluster associated with the project and run Cluster Image Scanning jobs without configuring the `CIS_KUBECONFIG` variable, you must extend `cluster_image_scanning` and specify the environment you want to scan. @@ -200,7 +209,7 @@ cluster_image_scanning: action: prepare ``` -## Reports JSON format +### Reports JSON format The cluster image scanning tool emits a JSON report file. For more information, see the [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json). @@ -208,7 +217,7 @@ The cluster image scanning tool emits a JSON report file. For more information, Here's an example cluster image scanning report: ```json-doc -{{ +{ "version": "14.0.2", "scan": { "scanner": { @@ -265,6 +274,27 @@ Here's an example cluster image scanning report: } ``` +## Cluster image scanning with the GitLab Kubernetes Agent + +You can use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to +scan images from within your Kubernetes cluster and record the vulnerabilities in GitLab. + +### Prerequisites + +- [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) + installed and configured in your cluster. +- [GitLab Kubernetes Agent](../../clusters/agent/install/index.md) + set up in GitLab, installed in your cluster, and configured using a configuration repository. + +### Configuration + +The GitLab Kubernetes agent begins to run cluster image scanning once the `cluster_image_scanning` +directive is added to your Kubernetes Agent configuration repository. + +See the [Kubernetes agent configuration repository](../../clusters/agent/repository.md#scan-your-container-images-for-vulnerabilities) +reference to learn more about the cluster image scanning configuration options for the +GitLab Kubernetes agent. + ## Security Dashboard The [Security Dashboard](../security_dashboard/index.md) shows you an overview of all diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 674eee5e80a..a913d5fba92 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -7,9 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Security Configuration **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. **(ULTIMATE)** -> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. **(ULTIMATE)** -> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. **(ULTIMATE)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in GitLab 12.6. +> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. +> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. > - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. > - [Redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.2. @@ -38,31 +38,31 @@ Select **Configuration history** to see the `.gitlab-ci.yml` file's history. You can configure the following security controls: -- Static Application Security Testing (SAST) **(FREE)** +- [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). -- Dynamic Application Security Testing (DAST) **(ULTIMATE)** +- [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. For more details, read [DAST on-demand scans](../dast/index.md#on-demand-scans). -- Dependency Scanning **(ULTIMATE)** +- [Dependency Scanning](../dependency_scanning/index.md) - Select **Configure via Merge Request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). -- Container Scanning **(ULTIMATE)** +- [Container Scanning](../container_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). -- Cluster Image Scanning **(ULTIMATE)** +- [Cluster Image Scanning](../cluster_image_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). -- Secret Detection +- [Secret Detection](../secret_detection/index.md) - Select **Configure via Merge Request** to create a merge request with the changes required to enable Secret Detection. For more details, read [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). -- API Fuzzing **(ULTIMATE)** +- [API Fuzzing](../api_fuzzing/index.md) - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). -- Coverage Fuzzing **(ULTIMATE)** +- [Coverage Fuzzing](../coverage_fuzzing/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). ## Compliance **(ULTIMATE)** You can configure the following security controls: -- License Compliance **(ULTIMATE)** +- [License Compliance](../../../user/compliance/license_compliance/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 22b54bf019c..da2816ab6ed 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Scanning **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and @@ -148,7 +148,7 @@ Support depends on the scanner: #### UBI-based images -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.1. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5775) in GitLab 14.1. GitLab also offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) versions of the container-scanning images. You can therefore replace standard images with UBI-based diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index cdb2e7109bf..9bb13d26d90 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -70,7 +70,7 @@ my_fuzz_target: - ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target> ``` -The included template makes available the [hidden job](../../../ci/yaml/index.md#hide-jobs) +The included template makes available the [hidden job](../../../ci/jobs/index.md#hide-jobs) `.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzz targets. Each fuzz target **must** have a separate job. For example, the [go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) @@ -146,7 +146,7 @@ corpus. ### Reports JSON format -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). The `gitlab-cov-fuzz` tool emits a JSON report file. For more information, see the [schema for this report](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/browser_based.md b/doc/user/application_security/dast/browser_based.md index 9c5b84f4f36..10ca3430b48 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -54,6 +54,7 @@ The browser-based crawler can be configured using CI/CD variables. | `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | | `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | | `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | +| `DAST_BROWSER_EXCLUDED_ELEMENTS` | selector | `a[href='2.html'],css:.no-follow` | Comma-separated list of selectors that are ignored when scanning. | | `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | | `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | | `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | @@ -127,7 +128,6 @@ dast: DAST_BROWSER_ACTION_TIMEOUT: "10s" DAST_BROWSER_STABILITY_TIMEOUT: "15s" DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT: "15s" - DAST_BROWSER_ACTION_TIMEOUT: "10s" DAST_BROWSER_ACTION_STABILITY_TIMEOUT: "3s" ``` diff --git a/doc/user/application_security/dast/checks/1004.1.md b/doc/user/application_security/dast/checks/1004.1.md new file mode 100644 index 00000000000..cbbcea1d34d --- /dev/null +++ b/doc/user/application_security/dast/checks/1004.1.md @@ -0,0 +1,41 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Sensitive cookie without `HttpOnly` attribute + +## Description + +The {cookie_name} cookie was transmitted in a `Set-Cookie` header without the `HttpOnly` attribute set. +To prevent JavaScript being able to access the cookie value - usually via `document.cookies` - all +cookies that are used for authorization or contain sensitive information should have the `HttpOnly` attribute +set. + +## Remediation + +Most web application frameworks allow configuring how cookies are sent to user-agents. Consult your framework's +documentation for more information on how to enable various security directives when assigning cookies to clients. + +If the application is assigning cookies via writing to the response headers directly, ensure all responses include +the `HttpOnly` attribute. By enabling this protection, the application is able to mitigate the impact of +certain Cross-Site Scripting (XSS) attacks. + +Example: + +```http +Set-Cookie: {cookie_name}=<random secure value>; HttpOnly +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 1004.1 | false | 1004 | Passive | Low | + +## Links + +- [owasp](https://owasp.org/www-community/HttpOnly) +- [cwe](https://cwe.mitre.org/data/definitions/1004.html) +- [Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) diff --git a/doc/user/application_security/dast/checks/16.1.md b/doc/user/application_security/dast/checks/16.1.md new file mode 100644 index 00000000000..bb030d2f9c4 --- /dev/null +++ b/doc/user/application_security/dast/checks/16.1.md @@ -0,0 +1,33 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Missing Content-Type header + +## Description + +The `Content-Type` header ensures that user agents correctly interpret the data being received. Without this header +being sent, the browser may misinterpret the data, leading to MIME confusion attacks. If an attacker were able +to upload files that are accessible by using a browser, they could upload files that may be interpreted as +HTML and so execute Cross-Site Scripting (XSS) attacks. + +## Remediation + +Ensure all resources return a proper `Content-Type` header that matches their format. As an example, +when returning JavaScript files, the response header should be: `Content-Type: application/javascript` + +For added protection, we recommend that all resources return the `X-Content-Type-Options: nosniff` +header to disable user agents from mis-interpreting resources. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.1 | true | 16 | Passive | Low | + +## Links + +- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [Mozilla Blog on MIME Confusion attacks](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) diff --git a/doc/user/application_security/dast/checks/16.2.md b/doc/user/application_security/dast/checks/16.2.md new file mode 100644 index 00000000000..95461e8677d --- /dev/null +++ b/doc/user/application_security/dast/checks/16.2.md @@ -0,0 +1,44 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Server header exposes version information + +## Description + +The target website returns the `Server` header and version information of this website. By +exposing these values, attackers may attempt to identify if the target software is vulnerable to known +vulnerabilities, or catalog known sites running particular versions to exploit in the future when a +vulnerability is identified in the particular version. + +## Remediation + +We recommend that the version information be removed from the `Server` header. + +Apache: +For Apache based web sites, set the `ServerTokens` to `Prod` in the `httpd.conf` configuration file. + +NGINX: +For NGINX based websites, set the `server_tokens` configuration value to `off` in the `nginx.conf` file. + +IIS: +For IIS based websites version 10 and above you can use the `removeServerHeader` element to the `requestFiltering` +section of the `Web.config` file. + +For all other server types, please consult your product's documentation on how to redact the version information from +the `Server` header. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.2 | true | 16 | Passive | Low | + +## Links + +- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [Apache ServerTokens](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) +- [NGINX server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) +- [IIS 10 Remove Server Header](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/security/requestfiltering/#attributes) diff --git a/doc/user/application_security/dast/checks/16.3.md b/doc/user/application_security/dast/checks/16.3.md new file mode 100644 index 00000000000..e4dcf3ece4b --- /dev/null +++ b/doc/user/application_security/dast/checks/16.3.md @@ -0,0 +1,35 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# X-Powered-By header exposes version information + +## Description + +The target website returns the `X-Powered-By` header and version information of this website. By +exposing these values, attackers may attempt to identify if the target software is vulnerable to known +vulnerabilities, or catalog known sites running particular versions to exploit in the future when a +vulnerability is identified in the particular version. + +## Remediation + +We recommend that the version information be removed from the `X-Powered-By` header. + +PHP: +For PHP based web sites, set the `expose_php` option to `off` in the `php.ini` configuration file. + +For all other server types, please consult your product's documentation on how to redact the version +information from the `X-Powered-By` header. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.3 | true | 16 | Passive | Low | + +## Links + +- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [PHP expose_php](https://www.php.net/manual/en/ini.core.php#ini.expose-php) diff --git a/doc/user/application_security/dast/checks/16.4.md b/doc/user/application_security/dast/checks/16.4.md new file mode 100644 index 00000000000..c0161c910b0 --- /dev/null +++ b/doc/user/application_security/dast/checks/16.4.md @@ -0,0 +1,28 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# X-Backend-Server header exposes server information + +## Description + +The target website returns the `X-Backend-Server` header which includes potentially internal/hidden IP addresses +or hostnames. By exposing these values, attackers may attempt to circumvent security proxies and access these +hosts directly. + +## Remediation + +Consult your proxy/load balancer documentation or provider on how to disable revealing the +`X-Backend-Server` header value. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.4 | true | 16 | Passive | Info | + +## Links + +- [cwe](https://cwe.mitre.org/data/definitions/16.html) diff --git a/doc/user/application_security/dast/checks/16.5.md b/doc/user/application_security/dast/checks/16.5.md new file mode 100644 index 00000000000..8a6f3cd8b6a --- /dev/null +++ b/doc/user/application_security/dast/checks/16.5.md @@ -0,0 +1,30 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# AspNet Header(s) exposes version information + +## Description + +The target website returns AspNet header(s) and version information of this website. By +exposing these values attackers may attempt to identify if the target software is vulnerable to known +vulnerabilities, or catalog known sites running particular versions to exploit in the future when a +vulnerability is identified in the particular version. + +## Remediation + +To remove the `X-AspNet-Version` header set `<httpRuntime enableVersionHeader="false" />` in the `<system.Web>` +section of the `Web.config` file. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.5 | true | 16 | Passive | Low | + +## Links + +- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [IIS Remove Unwanted Headers](https://techcommunity.microsoft.com/t5/iis-support-blog/remove-unwanted-http-response-headers/ba-p/369710) diff --git a/doc/user/application_security/dast/checks/614.1.md b/doc/user/application_security/dast/checks/614.1.md new file mode 100644 index 00000000000..74ac73935f1 --- /dev/null +++ b/doc/user/application_security/dast/checks/614.1.md @@ -0,0 +1,40 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Sensitive cookie without `Secure` attribute + +## Description + +The {cookie_name} cookie was transmitted in a `Set-Cookie` response without the `Secure` attribute set. +To prevent sensitive cookie values being accidentally transmitted over clear-text HTTP we +recommended that cookies are declared with the `Secure` attribute. + +## Remediation + +Most web application frameworks allow configuring how cookies are sent to user agents. Consult your framework's +documentation for more information on how to enable various security attributes when assigning cookies to clients. + +If the application is assigning cookies via writing to the response headers directly, ensure all responses include +the `Secure` attribute. By enabling this protection, the application will no longer send sensitive cookies over +HTTP. + +Example: + +```http +Set-Cookie: {cookie_name}=<random secure value>; Secure +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 614.1 | false | 614 | Passive | Low | + +## Links + +- [owasp](https://owasp.org/www-community/controls/SecureCookieAttribute) +- [cwe](https://cwe.mitre.org/data/definitions/614.html) +- [Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) diff --git a/doc/user/application_security/dast/checks/693.1.md b/doc/user/application_security/dast/checks/693.1.md new file mode 100644 index 00000000000..07cb368b39a --- /dev/null +++ b/doc/user/application_security/dast/checks/693.1.md @@ -0,0 +1,36 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Missing X-Content-Type-Options: nosniff + +## Description + +The `X-Content-Type-Options` header with the value `nosniff` ensures that user agents do not attempt to +guess the format of the data being received. User Agents such as browsers, commonly attempt to guess +what the resource type being requested is, through a process called MIME type sniffing. + +Without this header being sent, the browser may misinterpret the data, leading to MIME confusion attacks. +If an attacker were able to upload files that are accessible by using a browser, they could upload files +that could be interpreted as HTML and execute Cross-Site Scripting (XSS) attacks. + +## Remediation + +We recommend that the header and value of `X-Content-Type-Options: nosniff` be set server wide. +This ensures any resources that are mistakenly missing a `Content-Type` value are not +misinterpreted. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 693.1 | true | 693 | Passive | Low | + +## Links + +- [owasp](https://owasp.org/www-project-secure-headers/#x-content-type-options) +- [cwe](https://cwe.mitre.org/data/definitions/693.html) +- [Mozilla Blog on MIME Confusion attacks](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) +- [Mozilla MDN on X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md new file mode 100644 index 00000000000..f1a68387eb1 --- /dev/null +++ b/doc/user/application_security/dast/checks/index.md @@ -0,0 +1,20 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# DAST browser-based crawler vulnerability checks **(ULTIMATE)** + +The [DAST browser-based crawler](../browser_based.md) provides a number of vulnerability checks that are used to scan for vulnerabilities in the site under test. + +| ID | Check | Severity | Type | +|:---|:------|:---------|:-----| +| [1004.1](1004.1.md) | Sensitive cookie without `HttpOnly` attribute | Low | Passive | +| [16.1](16.1.md) | Missing Content-Type header | Low | Passive | +| [16.2](16.2.md) | Server header exposes version information | Low | Passive | +| [16.3](16.3.md) | X-Powered-By header exposes version information | Low | Passive | +| [16.4](16.4.md) | X-Backend-Server header exposes server information | Info | Passive | +| [16.5](16.5.md) | AspNet Header(s) exposes version information | Low | Passive | +| [614.1](614.1.md) | Sensitive cookie without `Secure` attribute | Low | Passive | +| [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 09b55e7b395..0d8b55a92a9 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -320,8 +320,8 @@ tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/20 ### API scan -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -> - A new DAST API scanning engine was introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in GitLab 12.10. +> - A new DAST API scanning engine was introduced in GitLab 13.10. Using an API specification as a scan's target is a useful way to seed URLs for scanning an API. Vulnerability rules in an API scan are different than those in a normal website scan. @@ -416,7 +416,7 @@ variables: ### URL scan -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/273141) in GitLab 13.11. A URL scan allows you to specify which parts of a website are scanned by DAST. @@ -492,7 +492,7 @@ Click **View details** to view the web console output which includes the list of ### View details of a vulnerability detected by DAST -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. Vulnerabilities detected by DAST occur in the live web application. Addressing these types of vulnerabilities requires specific information. DAST provides the information required to @@ -954,6 +954,11 @@ An on-demand scan can be run in active or passive mode: minimize the risk of accidental damage, running an active scan requires a [validated site profile](#site-profile-validation). +### View on-demand DAST scans + +To view running and completed on-demand DAST scans for a project, go to +**Security & Compliance > On-demand Scans** in the left sidebar. + ### Run an on-demand DAST scan Prerequisites: @@ -987,6 +992,7 @@ To run an on-demand scan either at a scheduled date or frequency, read 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. +1. Select **New DAST scan**. 1. Complete the **Scan name** and **Description** fields. 1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown. 1. In **Scanner profile**, select a scanner profile from the dropdown. @@ -1017,17 +1023,13 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. - -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 -`dast_on_demand_scans_scheduler`. -On GitLab.com, this feature is available. +> - [Feature flag dast_on_demand_scans_scheduler removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. To schedule a scan: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. Select **New DAST scan**. 1. Complete the **Scan name** and **Description** text boxes. 1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. 1. In the **Scanner profile** section, from the dropdown list, select a scanner profile. diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 39747a5cbe5..86621d73524 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Run DAST in an offline environment +# Run DAST in an offline environment **(ULTIMATE)** For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the DAST job to diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 3b1c91b0be4..f3ab25ccffa 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -681,15 +681,15 @@ Overrides use a JSON document, where each type of override is represented by a J }, "body-form": { "form-param1": "value", - "form-param1": "value", + "form-param2": "value" }, "body-json": { "json-path1": "value", - "json-path2": "value", + "json-path2": "value" }, "body-xml" : { "xpath1": "value", - "xpath2": "value", + "xpath2": "value" } } ``` @@ -968,16 +968,16 @@ Follow these steps to view details of a vulnerability: | Field | Description | |:--------------------|:----------------------------------------------------------------------------------------| - | Description | Description of the vulnerability including what was modified. | + | Description | Description of the vulnerability including what was modified. | | Project | Namespace and project in which the vulnerability was detected. | | Method | HTTP method used to detect the vulnerability. | | URL | URL at which the vulnerability was detected. | - | Request | The HTTP request that caused the vulnerability. | + | Request | The HTTP request that caused the vulnerability. | | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | - | Actual Response | Response received from test request. | - | Evidence | How we determined a vulnerability occurred. | - | Identifiers | The DAST API check used to find this vulnerability. | - | Severity | Severity of the vulnerability. | + | Actual Response | Response received from test request. | + | Evidence | How we determined a vulnerability occurred. | + | Identifiers | The DAST API check used to find this vulnerability. | + | Severity | Severity of the vulnerability. | | Scanner Type | Scanner used to perform testing. | ### Security Dashboard @@ -1105,8 +1105,46 @@ Profiles: - Name: XmlInjectionCheck ``` +## Running DAST API in an offline environment + +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the DAST API testing job to successfully run. + +Steps: + +1. Host the Docker image in a local container registry. +1. Set the `SECURE_ANALYZERS_PREFIX` to the local container registry. + +The Docker image for DAST API must be pulled (downloaded) from the public registry and then pushed (imported) into a local registry. The GitLab container registry can be used to locally host the Docker image. This process can be performed using a special template. See [loading Docker images onto your offline host](../offline_deployments/index.md#loading-docker-images-onto-your-offline-host) for instructions. + +Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-fuzzing:1` results in a valid image location. + +NOTE: +DAST API and API Fuzzing both use the same underlying Docker image `api-fuzzing:1`. + +For example, the below line sets a registry for the image `registry.gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing:1`: + +`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/gitlab-org/security-products/analyzers"` + +NOTE: +Setting `SECURE_ANALYZERS_PREFIX` changes the Docker image registry location for all GitLab Secure templates. + +For more information, see [Offline environments](../offline_deployments/index.md). + ## Troubleshooting +### Error waiting for API Security 'http://127.0.0.1:5000' to become available + +A bug exists in versions of the DAST API analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the DAST API analyzer. + +The version information can be found in the job details for the `dast_api` job. + +If the issue is occuring with versions v1.6.196 or greater, please contact Support and provide the following information: + +1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. +1. The full console output of the job. +1. The `gl-api-security-scanner.log` file available as a job artifact. In the right-hand panel of the job details page, select the **Browse** button. +1. The `dast_api` job definition from your `.gitlab-ci.yml` file. + ### Failed to start scanner session (version header not found) The DAST API engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `dast_api` job. A common cause of this issue is changing the `DAST_API_API` variable from its default. @@ -1114,7 +1152,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti **Error message** - In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/323939), `Failed to start scanner session (version header not found).` -- In GitLab 13.10 and earlier, `API Security version header not found. Are you sure that you are connecting to the API Security server?`. +- In GitLab 13.10 and earlier, `API Security version header not found. Are you sure that you are connecting to the API Security server?`. **Solution** diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index edfd0333d54..b0d8af2606f 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency list **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab Ultimate 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab 12.0. Use the dependency list to review your project's dependencies and key details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. @@ -66,7 +66,7 @@ Dependency paths are supported for the following package managers: ## Licenses -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab 12.3. If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 1f840c96663..3c6db8c3ee9 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -89,12 +89,13 @@ table.supported-languages ul { } </style> +<!-- markdownlint-disable MD044 --> <table class="supported-languages"> <thead> <tr> <th>Language</th> + <th>Language Versions</th> <th>Package Manager</th> - <th>Package Manager Versions</th> <th>Supported files</th> <th>Analyzer</th> <th><a href="#how-multiple-files-are-processed">Processes multiple files?</a></th> @@ -103,8 +104,8 @@ table.supported-languages ul { <tbody> <tr> <td rowspan="2">Ruby</td> + <td rowspan="2">N/A</td> <td rowspan="2"><a href="https://bundler.io/">Bundler</a></td> - <td rowspan="2">Any</td> <td> <ul> <li><code>Gemfile.lock</code></li> @@ -121,16 +122,16 @@ table.supported-languages ul { </tr> <tr> <td>PHP</td> + <td>N/A</td> <td><a href="https://getcomposer.org/">Composer</a></td> - <td>Any</td> <td><code>composer.lock</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> <td>C</td> + <td rowspan="2">N/A</td> <td rowspan="2"><a href="https://conan.io/">Conan</a></td> - <td rowspan="2">Any</td> <td rowspan="2"><a href="https://docs.conan.io/en/latest/versioning/lockfiles.html"><code>conan.lock</code></a></td> <td rowspan="2"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td rowspan="2">Y</td> @@ -140,16 +141,16 @@ table.supported-languages ul { </tr> <tr> <td>Go</td> - <td><a href="https://golang.org/">Golang</a></td> - <td>Any</td> + <td>N/A</td> + <td><a href="https://golang.org/">Go</a></td> <td><code>go.sum</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> <td rowspan="2">Java</td> - <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></td> - <td>Any</td> + <td rowspan="2">8, 11, 13, 14, 15, or 16</td> + <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup></td> <td> <ul> <li><code>build.gradle</code></li> @@ -161,15 +162,14 @@ table.supported-languages ul { </tr> <tr> <td><a href="https://maven.apache.org/">Maven</a></td> - <td>Any</td> <td><code>pom.xml</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> <td rowspan="3">JavaScript</td> + <td rowspan="2">N/A</td> <td rowspan="2"><a href="https://www.npmjs.com/">npm</a></td> - <td rowspan="2">Any</td> <td> <ul> <li><code>package-lock.json</code></li> @@ -185,16 +185,16 @@ table.supported-languages ul { <td>N</td> </tr> <tr> + <td>N/A</td> <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> - <td>1.x</td> <td><code>yarn.lock</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> <td>.NET</td> + <td rowspan="2">N/A</td> <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> - <td rowspan="2">>= 4.9</td> <td rowspan="2"><a href="https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> <td rowspan="2"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td rowspan="2">Y</td> @@ -204,15 +204,14 @@ table.supported-languages ul { </tr> <tr> <td rowspan="3">Python</td> + <td rowspan="3">3.6</td> <td><a href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></td> - <td>Any</td> <td><code>setup.py</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> <td><a href="https://pip.pypa.io/en/stable/">pip</a></td> - <td>Any</td> <td> <ul> <li><code>requirements.txt</code></li> @@ -225,11 +224,10 @@ table.supported-languages ul { </tr> <tr> <td><a href="https://pipenv.pypa.io/en/latest/">Pipenv</a></td> - <td>Any</td> <td> <ul> <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></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-2">2</a></b></sup></li> </ul> </td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -237,8 +235,8 @@ table.supported-languages ul { </tr> <tr> <td>Scala</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">3</a></b></sup></td> - <td>Any</td> + <td>N/A</td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></td> <td><code>build.sbt</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> @@ -246,18 +244,91 @@ table.supported-languages ul { </tbody> </table> -### Notes regarding supported languages and package managers - -1. Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. Please see the backlog issue [Android support for Dependency Scanning (gemnasium-maven)](https://gitlab.com/gitlab-org/gitlab/-/issues/336866) for more details. - -1. The presence of a `Pipfile.lock` file alone will _not_ trigger the analyzer; the presence of a `Pipfile` is still required in order -for the analyzer to be executed. However, if a `Pipfile.lock` file is found, it will be used by `Gemnasium` to scan the exact package -versions listed in this file. - - Support for `Pipfile.lock` files without requiring the presence of a `Pipfile` will be implemented in the following upcoming issue: - [Dependency Scanning of Pipfile.lock without installing project dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/299294). - -1. Support for [sbt](https://www.scala-sbt.org/) 1.3 and above was added in GitLab 13.9. +<ol> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-1"></a> + <p> + Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. + Please see the backlog issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336866">Android support for Dependency + Scanning (gemnasium-maven)</a> for more details. + </p> + </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-2"></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 will be used by + <code>Gemnasium</code> to scan the exact package versions listed in this file. + </p> + <p> + Support for <code>Pipfile.lock</code> files without requiring the presence of a <code>Pipfile</code> is tracked in + issue: <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/299294">Dependency Scanning of Pipfile.lock without + installing project dependencies</a>. + </p> + </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-3"></a> + <p> + Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. + </p> + </li> +</ol> +<!-- markdownlint-enable MD044 --> + +### How analyzers obtain dependency information + +GitLab analyzers obtain dependency information using one of the following two methods: + +1. [Parsing lockfiles directly.](#obtaining-dependendency-information-by-parsing-lockfiles) +1. [Running a package manager or build tool to generate a dependency information file which is then parsed.](#obtaining-dependendency-information-by-running-a-package-manager-to-generate-a-parsable-file) + +#### Obtaining dependendency information by parsing lockfiles + +The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: + +| Package Manager | Supported File Format Versions | Tested Versions | +| ------ | ------ | ------ | +| Bundler | N/A | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| Composer | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/tests/php-composer/-/blob/master/composer.lock) | +| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/c-conan/-/blob/master/conan.lock) | +| Go | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/tests/go-modules/-/blob/master/go.mod) | +| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/tests/csharp-nuget-dotnetcore/-/blob/master/src/web.api/packages.lock.json#L2) | +| npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/master/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/lockfile-v2-FREEZE/package-lock.json#L4) | +| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/js-yarn/-/blob/master/yarn.lock) | + +#### Obtaining dependendency information by running a package manager to generate a parsable file + +To support the following package managers, the GitLab analyzers proceed in two steps: + +1. Execute the package manager or a specific task, to export the dependency information. +1. Parse the exported dependency information. + +| Package Manager | Preinstalled Versions | Tested Versions | +| ------ | ------ | ------ | +| Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| sbt | [1.3.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L263), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L272), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L281), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L290), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L299) | +| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5) | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3) | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | | +| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | +| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | + +<!-- markdownlint-disable MD044 --> +<ol> + <li> + <a id="exported-dependency-information-notes-1"></a> + <p> + The installed version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a> + </p> + </li> + <li> + <a id="exported-dependency-information-notes-2"></a> + <p> + This test confirms that if a <code>Pipfile.lock</code> file is found, it will be used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. + </p> + </li> +</ol> +<!-- markdownlint-enable MD044 --> ### How analyzers are triggered @@ -321,15 +392,16 @@ We execute both analyzers because they use different sources of vulnerability da The analyzer for these languages supports multiple lockfiles. -### Future support for additional languages +### Support for additional languages -Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. -For workarounds, see the [Troubleshooting section](#troubleshooting) +Support for additional languages, dependency managers, and dependency files are tracked in the following issues: | Package Managers | Languages | Supported files | Scan tools | Issue | | ------------------- | --------- | --------------- | ---------- | ----- | | [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | +For workarounds, see the [Troubleshooting section](#troubleshooting). + ## Contribute your scanner The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. @@ -359,8 +431,8 @@ always take the latest dependency scanning artifact available. ### Enable Dependency Scanning via an automatic merge request -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4908) in GitLab 14.1. -> - [Enabled with `sec_dependency_scanning_ui_enable` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/282533) for self-managed GitLab in GitLab 14.1 and is ready for production use. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4908) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md) named `sec_dependency_scanning_ui_enable`. Enabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/282533) in GitLab 14.1. > - [Feature flag sec_dependency_scanning_ui_enable removed](https://gitlab.com/gitlab-org/gitlab/-/issues/326005) in GitLab 14.2. To enable Dependency Scanning in a project, you can create a merge request diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md new file mode 100644 index 00000000000..a58a00a869b --- /dev/null +++ b/doc/user/application_security/iac_scanning/index.md @@ -0,0 +1,98 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Infrastructure as Code (IaC) Scanning + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.5. + +Infrastructure as Code (IaC) Scanning scans your IaC configuration files for known vulnerabilities. + +Currently, IaC scanning supports configuration files for Terraform, Ansible, AWS CloudFormation, and Kubernetes. + +## Requirements + +To run IaC scanning jobs, by default, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. +If you're using the shared runners on GitLab.com, this is enabled by default. + +WARNING: +Our IaC scanning jobs require a Linux container type. Windows containers are not yet supported. + +WARNING: +If you use your own runners, make sure the Docker version installed +is **not** `19.03.0`. See [troubleshooting information](../sast/index.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. + +## Supported languages and frameworks + +GitLab IaC scanning supports a variety of IaC configuration files. Our IaC security scanners also feature automatic language detection which works even for mixed-language projects. If any supported configuration files are detected in project source code we automatically run the appropriate IaC analyzers. + +| Configuration File Type | Scan tool | Introduced in GitLab Version | +|------------------------------------------|----------------------------------|-------------------------------| +| Ansible | [kics](https://kics.io/) | 14.5 | +| AWS CloudFormation | [kics](https://kics.io/) | 14.5 | +| Kubernetes | [kics](https://kics.io/) | 14.5 | +| Terraform | [kics](https://kics.io/) | 14.5 | + +### Making IaC analyzers available to all GitLab tiers + +All open source (OSS) analyzers are availibile with the GitLab Free tier. Future propietary analyzers may be restricted to higher tiers. + +#### Summary of features per tier + +Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), +as shown in the following table: + +| Capability | In Free | In Ultimate | +|:---------------------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure IaC Scanners](#configuration) v | **{check-circle}** | **{check-circle}** | +| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | + +## Contribute your scanner + +The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. + +## Configuration + +To configure IaC Scanning for a project you can: + +- [Configure IaC Scanning manually](#configure-iac-scanning-manually) +- [Enable IaC Scanning via an automatic merge request](#enable-iac-scanning-via-an-automatic-merge-request) + +### Configure IaC Scanning manually + +To enable IaC Scanning you must [include](../../../ci/yaml/index.md#includetemplate) the +[`SAST-IaC.latest.gitlab-ci.yml template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST-IaC.latest.gitlab-ci.yml) provided as part of your GitLab installation. + +The included template creates IaC scanning jobs in your CI/CD pipeline and scans +your project's configuration files for possible vulnerabilities. + +The results are saved as a +[SAST report artifact](../../../ci/yaml/index.md#artifactsreportssast) +that you can download and analyze. + +### Enable IaC Scanning via an automatic merge request + +To enable IaC Scanning in a project, you can create a merge request +from the Security Configuration page: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure via Merge Request**. + +This automatically creates a merge request with the changes necessary to enable IaC Scanning +that you can review and merge to complete the configuration. + +## Reports JSON format + +The IaC tool emits a JSON report file in the existing SAST report format. For more information, see the +[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). diff --git a/doc/user/application_security/img/vulnerability-check_v14_2.png b/doc/user/application_security/img/vulnerability-check_v14_2.png Binary files differdeleted file mode 100644 index 655e43221c7..00000000000 --- a/doc/user/application_security/img/vulnerability-check_v14_2.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 7b95769a81f..d5e801ced9c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -31,19 +31,20 @@ For an overview of GitLab application security, see [Shifting Security Left](htt GitLab uses the following tools to scan and report known vulnerabilities found in your project. -| Secure scanning tool | Description | -|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------| -| [Container Scanning](container_scanning/index.md) **(ULTIMATE)** | Scan Docker containers for known vulnerabilities. | -| [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | -| [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | -| [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [DAST API](dast_api/index.md) **(ULTIMATE)** | Analyze running web APIs for known vulnerabilities. | -| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | -| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | -| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | -| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | -| [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | -| [Cluster Image Scanning](cluster_image_scanning/index.md) **(ULTIMATE)** | Scan Kubernetes clusters for known vulnerabilities. | +| Secure scanning tool | Description | +| :------------------------------------------------------------- | :------------------------------------------------------------------ | +| [Container Scanning](container_scanning/index.md) | Scan Docker containers for known vulnerabilities. | +| [Dependency List](dependency_list/index.md) | View your project's dependencies and their known vulnerabilities. | +| [Dependency Scanning](dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](dast/index.md) | Analyze running web applications for known vulnerabilities. | +| [DAST API](dast_api/index.md) | Analyze running web APIs for known vulnerabilities. | +| [API fuzzing](api_fuzzing/index.md) | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | +| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | +| [Security Dashboard](security_dashboard/index.md) | View vulnerabilities in all your projects and groups. | +| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | +| [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) | Analyze your IaC coniguration files for known vulnerabilities. | +| [Coverage fuzzing](coverage_fuzzing/index.md) | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | +| [Cluster Image Scanning](cluster_image_scanning/index.md) | Scan Kubernetes clusters for known vulnerabilities. | ## Security scanning with Auto DevOps @@ -185,61 +186,51 @@ By default, the vulnerability report does not show vulnerabilities of `dismissed ## Security approvals in merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in GitLab 12.2. -You can implement merge request approvals to require approval by selected users or a group when a -merge request would introduce one of the following security issues: +You can enforce an additional approval for merge requests that would introduce one of the following +security issues: -- A security vulnerability -- A software license compliance violation +- A security vulnerability. For more details, read + [Vulnerability-Check rule](#vulnerability-check-rule). +- A software license compliance violation. For more details, read + [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). -When the Vulnerability-Check merge request rule is enabled, additional merge request approval +### Vulnerability-Check rule + +To prevent a merge request introducing a security vulnerability in a project, enable the +Vulnerability-Check rule. While this rule is enabled, additional merge request approval by +[eligible approvers](../project/merge_requests/approvals/rules.md#eligible-approvers) is required when the latest security report in a merge request: -- Contains vulnerabilities that are not present in the - target branch. Note that approval is still required for dismissed vulnerabilities. +- Contains vulnerabilities with states (for example, `previously detected`, `dismissed`) matching the rule's vulnerability states. Only `newly detected` will be considered if the target branch differs from the project default branch. - Contains vulnerabilities with severity levels (for example, `high`, `critical`, or `unknown`) matching the rule's severity levels. - Contains a vulnerability count higher than the rule allows. -- Is not generated during pipeline execution. +- Is not yet generated (until pipeline completion). An approval is optional when the security report: -- Contains no new vulnerabilities when compared to the target branch. +- Contains only vulnerabilities with states (for example, `newly detected`, `resolved`) **NOT** matching the rule's vulnerability states. - Contains only vulnerabilities with severity levels (for example, `low`, `medium`) **NOT** matching the rule's severity levels. - Contains a vulnerability count equal to or less than what the rule allows. -When the License-Check merge request rule is enabled, additional approval is required if a merge -request contains a denied license. For more details, see [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). - -### Enable the Vulnerability-Check rule - -Prerequisites: - -- Maintainer or Owner [role](../permissions.md#project-members-permissions). +Project members assigned [at least the Maintainer role](../permissions.md#project-members-permissions) can enable or edit +the Vulnerability-Check rule. -For this approval group, you must set the number of approvals required to greater than zero. +#### Enable the Vulnerability-Check rule -Follow these steps to enable `Vulnerability-Check`: +To enable or edit the Vulnerability-Check rule: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Merge request approvals**. -1. Select **Enable** or **Edit**. -1. Set the **Security scanners** that the rule applies to. -1. Select the **Target branch**. -1. Set the **Vulnerabilities allowed** to the number of vulnerabilities allowed before the rule is - triggered. -1. Set the **Severity levels** to the severity levels that the rule applies to. -1. Set the **Approvals required** to the number of approvals that the rule requires. -1. Select the users or groups to provide approval. +1. Select **Activate** or **Edit** of the Vulnerability-Check. +1. Complete the fields. **Approvals required** must be at least 1. 1. Select **Add approval rule**. -Once this group is added to your project, the approval rule is enabled for all merge requests. -Any code changes cause the approvals required to reset. - - +The approval rule is enabled for all merge requests. Any code changes reset the approvals required. ## Using private Maven repositories @@ -270,28 +261,44 @@ under your project's settings: </settings> ``` -## DAST On-Demand Scans +## Using a custom scanning stage -If you don't want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. +When security scanning is enabled by including CI/CD templates as described in the +[Security scanning without Auto DevOps](#security-scanning-without-auto-devops) section, the scanning jobs +use the predefined `test` stage by default. If you specify a custom stage in your `.gitlab-ci.yml` file without +including a `test` stage, an error occurs. -## Security report validation +For example, the following attempts to use a `unit-tests` stage: -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. -> - Schema validation message [added](https://gitlab.com/gitlab-org/gitlab/-/issues/321730) in GitLab 14.0. +```yaml +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml -You can optionally enable validation of the security report artifacts based on the -[report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). -If you enable validation, GitLab validates the report artifacts before ingesting the vulnerabilities. -This prevents ingestion of broken vulnerability data into the database. +stages: + - unit-tests -In GitLab 14.0 and later, the pipeline's **Security** tab lists any report artifacts -that failed validation. Security report validation must first be enabled. +custom job: + stage: unit-tests + script: + - echo "custom job" +``` -### Enable security report validation +The above `.gitlab-ci.yml` causes a linting error: -To enable report artifacts validation, set the `VALIDATE_SCHEMA` environment variable to `"true"` for the jobs in the `.gitlab-ci.yml` file. +```plaintext +Found errors in your .gitlab-ci.yml: +- dependency_scanning job: chosen stage does not exist; available stages are .pre +- unit-tests +- .post +``` + +This error appears because the `test` stage used by the security scanning jobs isn't declared in the `.gitlab-ci.yml` file. +To fix this issue, you can either: -For example, the configuration below enables validation for only the `sast` job: +- Add a `test` stage in your `.gitlab-ci.yml`: ```yaml include: @@ -301,26 +308,98 @@ For example, the configuration below enables validation for only the `sast` job: - template: Security/Secret-Detection.gitlab-ci.yml stages: - - security-scan + - test + - unit-tests + + custom job: + stage: unit-tests + script: + - echo "custom job" + ``` + +- Override the default stage of each security job. For example, to use a pre-defined stage named `unit-tests`: + + ```yaml + include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml + + stages: + - unit-tests dependency_scanning: - stage: security-scan + stage: unit-tests license_scanning: - stage: security-scan + stage: unit-tests sast: - stage: security-scan - variables: - VALIDATE_SCHEMA: "true" + stage: unit-tests .secret-analyzer: - stage: security-scan + stage: unit-tests + + custom job: + stage: unit-tests + script: + - echo "custom job" ``` -## Interacting with findings and vulnerabilities +Learn more on overriding security jobs: + +- [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). +- [Overriding Dependency Scanning jobs](dependency_scanning/index.md#overriding-dependency-scanning-jobs). +- [Overriding Container Scanning jobs](container_scanning/index.md#overriding-the-container-scanning-template). +- [Overriding Secret Detection jobs](secret_detection/index.md#customizing-settings). +- [Overriding DAST jobs](dast/index.md#customize-dast-settings). +- [Overriding License Compliance jobs](../compliance/license_compliance/index.md#overriding-the-template). + +All the security scanning tools define their stage, so this error can occur with all of them. + +## Security report validation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - Schema validation message [added](https://gitlab.com/gitlab-org/gitlab/-/issues/321730) in GitLab 14.0. + +You can enforce validation of the security report artifacts before ingesting the vulnerabilities. +This prevents ingestion of broken vulnerability data into the database. GitLab validates the +artifacts based on the [report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). + +In GitLab 14.0 and later, when artifact validation is enabled, the pipeline's **Security** tab lists +any report artifacts that failed validation. + +### Enable security report validation + +To enable report artifacts validation, set the `VALIDATE_SCHEMA` environment variable to `"true"` +for the desired jobs in the `.gitlab-ci.yml` file. -There are a variety of locations and ways to interact with the results of the security scanning tools: +For example, to enable validation for only the `sast` job: + +```yaml +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml +stages: + - security-scan +dependency_scanning: + stage: security-scan +license_scanning: + stage: security-scan +sast: + stage: security-scan + variables: + VALIDATE_SCHEMA: "true" +.secret-analyzer: + stage: security-scan +``` + +## Interact with findings and vulnerabilities + +You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) - [Project Security Dashboard](security_dashboard/#project-security-dashboard) @@ -331,13 +410,33 @@ There are a variety of locations and ways to interact with the results of the se - [Vulnerability Pages](vulnerabilities/index.md) - [Dependency List](dependency_list/index.md) -For more details about which findings or vulnerabilities you can view in each of those locations, select the respective link. Each page details the ways in which you can interact with the findings and vulnerabilities. As an example, in most cases findings start out as _detected_ status. You have the option to: +For more details about which findings or vulnerabilities you can view in each of those locations, +select the respective link. Each page details the ways in which you can interact with the findings +and vulnerabilities. As an example, in most cases findings start out as _detected_ status. + +You have the option to: - Change the status. - Create an issue. - Link it to an existing issue. - [Resolve the vulnerability](vulnerabilities/index.md#resolve-a-vulnerability), if a solution is known. +## Security scanning configuration tips + +Each GitLab security scanning tool has a default +[CI/CD configuration file](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Security), +also known as a _template_. + +When customizing the configuration: + +- [Include](../../ci/yaml/index.md#include) the scanning tool's CI/CD template. Don't _copy_ the content + of the template. +- Use the [stable](../../development/cicd/templates.md#stable-version) version of each template + for production workflows. The stable version changes less often, and breaking changes are only + made between major GitLab versions. The [latest](../../development/cicd/templates.md#latest-version) + version contains the most recent changes, but may have significant changes between minor GitLab versions. +- Only override values in the template as needed. All other values are inherited from the template. + ## Troubleshooting ### Secure job failing with exit code 1 @@ -352,8 +451,8 @@ variables: ### Outdated security reports -When a security report generated for a merge request becomes outdated, the merge request shows a warning -message in the security widget and prompts you to take an appropriate action. +When a security report generated for a merge request becomes outdated, the merge request shows a +warning message in the security widget and prompts you to take an appropriate action. This can happen in two scenarios: @@ -362,73 +461,28 @@ This can happen in two scenarios: #### Source branch is behind the target branch -This means the most recent common ancestor commit between the target branch and the source branch is -not the most recent commit on the target branch. This is by far the most common situation. +A security report can be out of date when the most recent common ancestor commit between the +target branch and the source branch is not the most recent commit on the target branch. -In this case you must rebase or merge to incorporate the changes from the target branch. +To fix this issue, rebase or merge to incorporate the changes from the target branch.  #### Target branch security report is out of date -This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a -security report is out of date, you must run a new pipeline on the target branch. -You can do it quickly by following the hyperlink given to run a new pipeline. +This can happen for many reasons, including failed jobs or new advisories. When the merge request +shows that a security report is out of date, you must run a new pipeline on the target branch. +Select **new pipeline** to run a new pipeline.  -### Getting error message `sast job: stage parameter should be [some stage name here]` - -When [including](../../ci/yaml/index.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), -the following error may occur, depending on your GitLab CI/CD configuration: - -```plaintext -Found errors in your .gitlab-ci.yml: - -* sast job: stage parameter should be unit-tests -``` - -This error appears when the included job's stage (named `test`) isn't declared in `.gitlab-ci.yml`. -To fix this issue, you can either: - -- Add a `test` stage in your `.gitlab-ci.yml`. -- Override the default stage of each security job. For example, to use a pre-defined stage name `unit-tests`: - - ```yaml - include: - - template: Security/Dependency-Scanning.gitlab-ci.yml - - template: Security/License-Scanning.gitlab-ci.yml - - template: Security/SAST.gitlab-ci.yml - - template: Security/Secret-Detection.gitlab-ci.yml - - stages: - - unit-tests - - dependency_scanning: - stage: unit-tests - - license_scanning: - stage: unit-tests - - sast: - stage: unit-tests - - .secret-analyzer: - stage: unit-tests - ``` - -[Learn more on overriding SAST jobs](sast/index.md#overriding-sast-jobs). -All the security scanning tools define their stage, so this error can occur with all of them. - ### Getting warning messages `… report.json: no matching files` -This is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), -and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Please -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#custom-cicd-variables). -This provides useful information to investigate further. +This message is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.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#custom-cicd-variables). +This provides extra information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` @@ -526,23 +580,24 @@ involve pinning to the previous template versions, for example: ``` Additionally, we provide a dedicated project containing the versioned legacy templates. -This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). +This can be used for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). Instructions are available in the [legacy template project](https://gitlab.com/gitlab-org/auto-devops-v12-10). #### Vulnerabilities are found, but the job succeeds. How can I have a pipeline fail instead? -This is the current default behavior, because the job's status indicates success or failure of the analyzer itself. -Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), -[Merge Request widget](#view-security-scan-information-in-merge-requests) -or [Security Dashboard](security_dashboard/index.md). +In these circumstances, that the job succeeds is the default behavior. The job's status indicates +success or failure of the analyzer itself. Analyzer results are displayed in the +[job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), +[Merge Request widget](#view-security-scan-information-in-merge-requests) or +[Security Dashboard](security_dashboard/index.md). ### Error: job `is used for configuration only, and its script should not be executed` [Changes made in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41260) to the `Security/Dependency-Scanning.gitlab-ci.yml` and `Security/SAST.gitlab-ci.yml` templates mean that if you enable the `sast` or `dependency_scanning` jobs by setting the `rules` attribute, -they will fail with the error `(job) is used for configuration only, and its script should not be executed`. +they fail with the error `(job) is used for configuration only, and its script should not be executed`. The `sast` or `dependency_scanning` stanzas can be used to make changes to all SAST or Dependency Scanning, such as changing `variables` or the `stage`, but they cannot be used to define shared `rules`. diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index cdf54070d69..915e43d0fa5 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -87,7 +87,9 @@ above. You can find more information at each of the pages below: - [Container scanning offline directions](../container_scanning/index.md#running-container-scanning-in-an-offline-environment) - [SAST offline directions](../sast/index.md#running-sast-in-an-offline-environment) +- [Secret Detection offline directions](../secret_detection/#running-secret-detection-in-an-offline-environment) - [DAST offline directions](../dast/run_dast_offline.md#run-dast-in-an-offline-environment) +- [API Fuzzing offline directions](../api_fuzzing/#running-api-fuzzing-in-an-offline-environment) - [License Compliance offline directions](../../compliance/license_compliance/index.md#running-license-compliance-in-an-offline-environment) - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment) diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index e1ddb3167ff..4d8be411dc5 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Policies **(ULTIMATE)** -> - Introduced in GitLab Ultimate 13.10 [with a flag](https://gitlab.com/groups/gitlab-org/-/epics/5329) named `security_orchestration_policies_configuration`. Disabled by default. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab Ultimate 14.3. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in GitLab 13.10 with a flag named `security_orchestration_policies_configuration`. Disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.3. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.4. Policies in GitLab provide security teams a way to require scans of their choice to be run @@ -49,7 +49,7 @@ users must make changes by following the ## Policy editor -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in GitLab Ultimate 13.4. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in GitLab 13.4. You can use the policy editor to create, edit, and delete policies: @@ -79,7 +79,7 @@ mode to fix your policy before Rule mode is available again. ## Container Network Policy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in GitLab Ultimate 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in GitLab 12.9. The **Container Network Policy** section provides packet flow metrics for your application's Kubernetes namespace. This section has the following @@ -118,9 +118,9 @@ examining the Cilium logs: kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor ``` -### Change the enforcement status +### Change the status -To change a network policy's enforcement status: +To change a network policy's status: - Select the network policy you want to update. - Select **Edit policy**. @@ -154,12 +154,12 @@ at the bottom of the editor. ### Configure a Network Policy Alert -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab Ultimate 13.9. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 13.9. > - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. You can use policy alerts to track your policy's impact. Alerts are only available if you've [installed](../../clusters/agent/repository.md) -and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) +and [configured](../../clusters/agent/install/index.md#create-an-agent-record-in-gitlab) a Kubernetes Agent for this project. There are two ways to create policy alerts: diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index d399dcaf4a9..06c57e68121 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SAST Analyzers **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 7ffefd34e40..af8585c6a18 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -7,8 +7,8 @@ type: reference, howto # Static Application Security Testing (SAST) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. -> - All open source (OSS) analyzers were moved to GitLab Free in GitLab 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. +> - All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -16,11 +16,10 @@ explains how 4 of the top 6 attacks were application based. Download it to learn organization. If you're using [GitLab CI/CD](../../../ci/index.md), you can use Static Application Security -Testing (SAST) to check your source code for known vulnerabilities. When a pipeline completes, -the results of the SAST analysis are processed and shown in the pipeline's Security tab. If the -pipeline is associated with a merge request, the SAST analysis is compared with the results of +Testing (SAST) to check your source code for known vulnerabilities. +If the pipeline is associated with a merge request, the SAST analysis is compared with the results of the target branch's analysis (if available). The results of that comparison are shown in the merge -request. **(ULTIMATE)** If the pipeline is running from the default branch, the results of the SAST +request. If the pipeline is running from the default branch, the results of the SAST analysis are available in the [security dashboards](../security_dashboard/index.md).  @@ -197,7 +196,7 @@ Use the method that best meets your needs. - [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings) - [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations) -### Configure SAST in the UI with default settings **(FREE)** +### Configure SAST in the UI with default settings > [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 @@ -217,9 +216,9 @@ successfully, and an error may occur. ### Configure SAST in the UI with customizations **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab Ultimate 13.4. -> - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab Ultimate 13.5. +> - [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. +> - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab 13.5. To enable and configure SAST with customizations: @@ -402,7 +401,7 @@ To create a custom ruleset: ### False Positive Detection **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292686) in GitLab 14.2. +> Introduced in GitLab 14.2. Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. @@ -423,7 +422,7 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m ### Enabling Kubesec analyzer -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab Ultimate 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab 12.6. You need to set `SCAN_KUBERNETES_MANIFESTS` to `"true"` to enable the Kubesec analyzer. In `.gitlab-ci.yml`, define: @@ -569,7 +568,7 @@ Some analyzers can be customized with CI/CD variables. #### Custom CI/CD variables -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab Ultimate 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab 12.5. In addition to the aforementioned SAST configuration CI/CD variables, all [custom variables](../../../ci/variables/index.md#custom-cicd-variables) are propagated diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 5933496ea00..140f660d729 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -7,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Secret Detection **(FREE)** -> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in 13.3. +> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in GitLab 11.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. A recurring problem when developing applications is that developers may unintentionally commit secrets and credentials to their remote repositories. If other people have access to the source, @@ -138,9 +138,9 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. -### Enable Secret Detection via an automatic merge request **(FREE)** +### Enable Secret Detection via an automatic merge request -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, deployed behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1. To enable Secret Detection in a project, you can create a merge request @@ -165,7 +165,7 @@ by using the [`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. To override a job definition, (for example, change properties like `variables` or `dependencies`), -declare a job with the same name as the SAST job to override. Place this new job after the template +declare a job with the same name as the secret detection job to override. Place this new job after the template inclusion and specify any additional keys under it. WARNING: @@ -202,8 +202,9 @@ Secret Detection can be customized by defining available CI/CD variables: | CI/CD variable | Default value | Description | |-----------------------------------|---------------|-------------| -| `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | -| `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | +| `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. Replaced with `SECRET_DETECTION_COMMITS`. | +| `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. Replaced with `SECRET_DETECTION_COMMITS`. | +| `SECRET_DETECTION_COMMITS` | - | The list of commits that Gitleaks should scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. | | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | @@ -348,6 +349,22 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). +### Set Secret Detection CI/CD variables to use the local Secret Detection analyzer container image + +Add the following configuration to your `.gitlab-ci.yml` file. You must replace +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: + +```yaml +include: + - template: Security/Secret-Detection.gitlab-ci.yml + +variables: + SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" +``` + +The Secret Detection job should now use the local copy of the Secret Detection analyzer Docker image to scan your code and generate +security reports without requiring internet access. + #### If support for Custom Certificate Authorities are needed Support for custom certificate authorities was introduced in the following versions. @@ -371,22 +388,6 @@ variables: The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. -### Set Secret Detection CI/CD variables to use local Secret Detection analyzer - -Add the following configuration to your `.gitlab-ci.yml` file. You must replace -`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: - -```yaml -include: - - template: Security/Secret-Detection.gitlab-ci.yml - -variables: - SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" -``` - -The Secret Detection job should now use local copies of the Secret Detection analyzer to scan your code and generate -security reports without requiring internet access. - ## Troubleshooting ### Getting warning message `gl-secret-detection-report.json: no matching files` diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png Binary files differdeleted file mode 100644 index 52249cef343..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png Binary files differnew file mode 100644 index 00000000000..ac123d2b528 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index c78179e9693..87875ec15ba 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -51,7 +51,7 @@ The security dashboard and vulnerability report displays information about vulne At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline ran against. - + Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. @@ -64,11 +64,15 @@ the analyzer outputs an ### Scan details -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/333660) in GitLab 14.2. -The **Scan details** section lists the scans run in the pipeline and the total number of -vulnerabilities per scan. For the DAST scan, select **Download scanned resources** to download a -CSV file containing details of the resources scanned. +The **Scan details** section lists the scans run in the pipeline and the total number of vulnerabilities +per scan. + +You can download the JSON artifacts from each security scan. Select **Download results** then +select the JSON artifact. Additionally for the DAST scan, from the **Download results** dropdown select +**Download scanned resources** to download a CSV file containing details of the resources scanned. ## Project Security Dashboard diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 79f202a6edb..ae5f6ba0fe1 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Threat Monitoring **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in GitLab 12.9. The **Threat Monitoring** page provides alerts and metrics for the GitLab application runtime security features. You can access @@ -20,7 +20,7 @@ GitLab supports statistics for the following security features: ## Container Network Policy Alert list -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in GitLab 13.9. The policy alert list displays your policy's alert activity. You can sort the list by these columns: @@ -44,5 +44,3 @@ Clicking an alert's row opens the alert drawer, which shows more information abo can also create an incident from the alert and update the alert status in the alert drawer. Clicking an alert's name takes the user to the [alert details page](../../../operations/incident_management/alerts.md#alert-details-page). - -For information on work in progress for the alerts dashboard, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5041). diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 9ebecc67704..7bdc8cc8479 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Pages **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in GitLab 13.0. Each vulnerability in a project has a Vulnerability Page. This page contains details of the vulnerability. The details included vary according to the type of vulnerability. Details of each @@ -20,6 +20,9 @@ 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: - [Change the vulnerability's status](#change-vulnerability-status). diff --git a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png Binary files differdeleted file mode 100644 index 44c689eda3e..00000000000 --- a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/img/project_level_vulnerability_report_v14_5.png b/doc/user/application_security/vulnerability_report/img/project_level_vulnerability_report_v14_5.png Binary files differnew file mode 100644 index 00000000000..ac996fa32db --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_level_vulnerability_report_v14_5.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index f5b0194c320..d13647937a2 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -16,7 +16,16 @@ At all levels, the Vulnerability Report contains: - Filters for common vulnerability attributes. - Details of each vulnerability, presented in tabular layout. - +The **Activity** column contains icons to indicate the activity, if any, taken on the vulnerability +in that row: + +- Issues **{issues}**: Links to issues created for the vulnerability. For more details, read + [Create an issue for a vulnerability](../vulnerabilities/index.md#create-an-issue-for-a-vulnerability). +- Wrench **{admin}**: The vulnerability has been remediated. +- False positive **{false-positive}**: The scanner determined this vulnerability to be a false + positive. + + ## Project-level Vulnerability Report @@ -151,7 +160,7 @@ To change the status of vulnerabilities in the table: ### Change status of multiple vulnerabilities -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in GitLab 12.9. You can change the status of multiple vulnerabilities at once: @@ -162,8 +171,8 @@ You can change the status of multiple vulnerabilities at once: ## Export vulnerability details -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in GitLab 13.0. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in GitLab 13.1. You can export details of the vulnerabilities listed in the Vulnerability Report. The export format is CSV (comma separated values). Note that all vulnerabilities are included because filters don't @@ -197,7 +206,7 @@ thousands of vulnerabilities. Don't close the page until the download finishes. ## Dismiss a vulnerability -> The option of adding a dismissal reason was introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> The option of adding a dismissal reason was introduced in GitLab 12.0. You can dismiss a vulnerability for the entire project: diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 6c8b7c95771..0dfdb37dc1f 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -4,15 +4,13 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CI/CD Tunnel **(PREMIUM)** +# CI/CD Tunnel **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. > - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. > - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. - -WARNING: -The CI/CD Tunnel is not supported for GitLab self-managed instances installed via Omnibus. We -plan to [add support for Omnibus](https://gitlab.com/gitlab-org/gitlab/-/issues/324272) in the future. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. +> - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. @@ -21,11 +19,11 @@ Only CI/CD jobs set in the configuration project can access one of the configure ## Prerequisites -- A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server). -- A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file +- A running [`kas` instance](install/index.md#set-up-the-kubernetes-agent-server). +- A [configuration repository](install/index.md#define-a-configuration-repository) with an Agent config file installed (`.gitlab/agents/<agent-name>/config.yaml`). -- An [Agent record](index.md#create-an-agent-record-in-gitlab). -- The Agent [installed in the cluster](index.md#install-the-agent-into-the-cluster). +- An [Agent record](install/index.md#create-an-agent-record-in-gitlab). +- The Agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster). ## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD @@ -37,6 +35,16 @@ there isn't any context selected. Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. To get the list of available contexts, run `kubectl config get-contexts`. +## Share the CI/CD Tunnel provided by an Agent with other projects and groups + +The Agent can be configured to enable access to the CI/CD Tunnel to other projects or all the projects under a given group. This way you can have a single agent serving all the requests for several projects saving on resources and maintenance. + +You can read more on how to [authorize access in the Agent configuration reference](repository.md#authorize-projects-and-groups-to-use-an-agent). + +## Restrict access of authorized projects and groups **(PREMIUM)** + +You can [configure various impersonations](repository.md#use-impersonation-to-restrict-project-and-group-access) to restrict the permissions of a shared CI/CD Tunnel. + ## Example for a `kubectl` command using the CI/CD Tunnel The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 557d389147d..80b9f3f17f5 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,31 +4,58 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Kubernetes Agent **(PREMIUM)** +# GitLab Kubernetes Agent **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6, `grpcs` is supported. +> - Support for `grpcs` [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) in GitLab 13.10, KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. > - Introduced in GitLab 13.11, the GitLab Kubernetes Agent became available to every project on GitLab.com. +> - The GitLab Kubernetes Agent was [moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. -The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) -is an active in-cluster component for solving GitLab and Kubernetes integration -tasks in a secure and cloud-native way. It enables: +The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) ("Agent", for short) +is an active in-cluster component for connecting Kubernetes clusters to GitLab safely to support cloud-native deployment, management, and monitoring. -- GitLab integration with a Kubernetes cluster behind a firewall or NAT - (network address translation). -- Pull-based GitOps deployments. -- [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster. -- Real-time access to API endpoints in a cluster. -- Alert generation based on [Container network policy](../../application_security/policies/index.md#container-network-policy). -- [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. +The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution. -Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) -and [our development documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc). +With GitOps, you can manage containerized clusters and applications from a Git repository that: -## GitLab Agent GitOps workflow +- Is the single source of truth of your system. +- Is the single place where you operate your system. +- Is a single resource to monitor your system. -The GitLab Agent, herein _Agent_, uses multiple GitLab projects to provide a flexible workflow +By combining GitLab, Kubernetes, and GitOps, it results in a robust infrastructure: + +- GitLab as the GitOps operator. +- Kubernetes as the automation and convergence system. +- GitLab CI/CD as the Continuous Integration and Continuous Deployment engine. + +Beyond that, you can use all the features offered by GitLab as +the all-in-one DevOps platform for your product and your team. + +## Agent's features + +By using the GitLab Kubernetes Agent, you can: + +- Connect GitLab with a Kubernetes cluster behind a firewall or a +Network Address Translation (NAT). +- Have real-time access to API endpoints in your cluster from GitLab CI/CD. +- Use GitOps to configure your cluster through the [Agent's repository](repository.md). +- Perform pull-based or push-based GitOps deployments. +- Configure [Network Security Alerts](#kubernetes-network-security-alerts) +based on [Container Network Policies](../../application_security/policies/index.md#container-network-policy). +- Track objects applied to your cluster through [inventory objects](../../infrastructure/clusters/deploy/inventory_object.md). +- Use the [CI/CD Tunnel](ci_cd_tunnel.md) to access Kubernetes clusters +from GitLab CI/CD jobs while keeping the cluster's APIs safe and unexposed +to the internet. +- [Deploy the GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html). + +See the [GitLab Kubernetes Agent roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) to track its development. + +To contribute to the Agent, see the [Agent's development documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc). + +## Agent's GitOps workflow **(PREMIUM)** + +The Agent uses multiple GitLab projects to provide a flexible workflow that can suit various needs. This diagram shows these repositories and the main actors involved in a deployment: @@ -50,365 +77,35 @@ sequenceDiagram end ``` -There are several components that work in concert for the Agent to accomplish GitOps deployments: - -- A properly-configured Kubernetes cluster where the Agent is running. -- A configuration repository that contains a `config.yaml` file, which tells the - Agent the repositories to synchronize with the cluster. -- A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster. - -You can use the same GitLab project or projects for configuration and manifest files, as follows: - -- Single GitLab project (recommended): when you use a single repository to hold both the manifest and the configuration files, these projects can be either private or public, as you prefer. -- Two GitLab projects: when you opt to use two different GitLab projects, one for manifest files, and another for configuration files, the manifests project must be public, while the configuration project can be either private or public. Our backlog contains issues for adding support for -[private manifest repositories outside of the configuration project](https://gitlab.com/gitlab-org/gitlab/-/issues/220912) and -[group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885) in the future. - -For more details, please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. - -## Get started with GitOps and the GitLab Agent - -The setup process involves a few steps to enable GitOps deployments: - -1. [Set up the Kubernetes Agent Server](#set-up-the-kubernetes-agent-server) for your GitLab instance. -1. [Define a configuration repository](#define-a-configuration-repository). -1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). -1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). -1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). -1. [Create manifest files](#create-manifest-files). - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. - -### Upgrades and version compatibility - -As the GitLab Kubernetes Agent is a new product, we are constantly adding new features -to it. As a result, while shipped features are production ready, its internal API is -neither stable nor versioned yet. For this reason, GitLab only guarantees compatibility -between corresponding major.minor (X.Y) versions of GitLab and its cluster side -component, `agentk`. - -Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk` to install follow: - -1. Open the [`GITLAB_KAS_VERSION`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch. -1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION) - -The available `agentk` and `kas` versions can be found in -[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). - -### Set up the Kubernetes Agent Server - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Kubernetes Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. - -To use the KAS: - -- If you are a self-managed user, follow the instructions to [install the Kubernetes Agent Server](../../../administration/clusters/kas.md). -- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. - -### Define a configuration repository - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. -> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. - -To configure an Agent, you need: - -1. A GitLab repository to hold the configuration file. -1. Install the Agent in a cluster. - -After installed, when you update the configuration file, GitLab transmits the -information to the cluster automatically without downtime. - -In your repository, add the Agent configuration file under: - -```plaintext -.gitlab/agents/<agent-name>/config.yaml -``` - -Your `config.yaml` file specifies all configurations of the Agent, such as: - -- The manifest projects to synchronize. -- The groups that can access this Agent via the [CI/CD Tunnel](ci_cd_tunnel.md). -- The address of the `hubble-relay` for the Network Security policy integrations. - -As an example, a minimal Agent configuration that sets up only the manifest -synchronizations is: - -```yaml -gitops: - manifest_projects: - - id: "path-to/your-manifest-project-1" - paths: - - glob: '/**/*.{yaml,yml,json}' -``` - -All the options for the [Kubernetes Agent configuration repository](repository.md) are documented separately. - -### Create an Agent record in GitLab - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI. - -Next, create a GitLab Rails Agent record to associate it with -the configuration repository project. Creating this record also creates a Secret needed to configure -the Agent in subsequent steps. - -In GitLab: - -1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select the **GitLab Agent managed clusters** tab. -1. Select **Integrate with the GitLab Agent**. -1. From the **Select an Agent** dropdown menu, select the Agent you want to connect and select **Next** to access the installation form. -1. The form reveals your registration token. Securely store this secret token as you cannot view it again. -1. Copy the command under **Recommended installation method**. - -In your computer: - -1. Open your local terminal and connect to your cluster. -1. Run the command you copied from the installation form. - -### Install the Agent into the cluster - -To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, -for example, `gitlab-kubernetes-agent`, run: - -```shell -kubectl create namespace gitlab-kubernetes-agent -``` - -To perform a one-liner installation, run the command below. Make sure to replace: - -- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). -- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. -- `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. -- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - -``` - -WARNING: -`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for -testing purposes but for production please make sure to specify a matching version explicitly. - -To find out the various options the above Docker container supports, run: - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help -``` - -#### Advanced installation - -For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). - -Otherwise, follow the manual installation steps described below. - -### Create the Kubernetes secret - -After generating the token, you must apply it to the Kubernetes cluster. - -To create your Secret, run: - -```shell -kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN' -``` - -The following example file contains the -Kubernetes resources required for the Agent to be installed. You can modify this -example [`resources.yml` file](#example-resourcesyml-file) in the following ways: - -- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. -- You can configure `kas-address` (Kubernetes Agent Server) in several ways. - The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. - Select the option appropriate for your cluster configuration and GitLab architecture: - - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. - When using the sub-chart, you must set `wss://kas.host.tld:443` as - `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. - When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as - `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) - to use an unencrypted WebSockets connection. - When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`). - - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. - In this case, you may specify `kas-address` value as - `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas` - is the name of the service created by `gitlab-kas` chart, and `<your-namespace>` - is the namespace where the chart was installed. - - Specify the `grpcs` scheme to use an encrypted gRPC connection. - - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the - `kas-address` for `wss` and `ws` schemes to whatever you need. - Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) - to learn more about it. - - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. -- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your - secret name in the `secretName:` section. - -To apply this file, run the following command: - -```shell -kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml -``` - -To review your configuration, run the following command: - -```shell -$ kubectl get pods -n gitlab-kubernetes-agent - -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s -``` - -#### Example `resources.yml` file - -```yaml ---- -apiVersion: v1 -kind: Namespace -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: gitlab-kubernetes-agent -spec: - replicas: 1 - selector: - matchLabels: - app: gitlab-kubernetes-agent - template: - metadata: - labels: - app: gitlab-kubernetes-agent - spec: - serviceAccountName: gitlab-kubernetes-agent - containers: - - name: agent - # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z - args: - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - volumes: - - name: token-volume - secret: - secretName: gitlab-kubernetes-agent-token - strategy: - type: RollingUpdate - rollingUpdate: - maxSurge: 0 - maxUnavailable: 1 ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-write -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - create - - update - - delete - - patch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-write-binding -roleRef: - name: gitlab-kubernetes-agent-write - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-read -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - get - - list - - watch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-read-binding -roleRef: - name: gitlab-kubernetes-agent-read - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent -``` - -### Create manifest files - -In a previous step, you configured a `config.yaml` to point to the GitLab projects -the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a -templating engine or other means. - -The agent is authorized to download manifests for the configuration -project, and public projects. Support for other private projects is -planned in the issue [Agent authorization for private manifest -projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). - -Each time you push a change to a monitored manifest repository, the Agent logs the change: - -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` +For more details, refer to our [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. -#### Example manifest file +## Install the Agent in your cluster -This file creates a minimal `ConfigMap`: +See how to [install the GitLab Kubernetes Agent in your cluster](install/index.md). -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: demo-map - namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -data: - key: value -``` +## GitOps deployments **(PREMIUM)** -## Example projects +To perform GitOps deployments with the Agent, you need: -The following example projects can help you get started with the Kubernetes Agent. +- A properly-configured Kubernetes cluster where the Agent is running. +- A [configuration repository](repository.md) that contains a +`config.yaml` file, which tells the Agent the repositories to synchronize +with the cluster. +- A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster. -- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) -- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +You can use a single GitLab project or different projects for the Agent +configuration and manifest files, as follows: -### GitLab Runner Deployment with the Agent +- Single GitLab project (recommended): When you use a single repository to hold + both the manifest and the configuration files, these projects can be either + private or public. +- Two GitLab projects: When you use two different GitLab projects (one for + manifest files and another for configuration files), the manifests project must + be public, while the configuration project can be either private or public. -You can use the Kubernetes Agent to -[deploy GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html). +Support for separated private manifest and configuration repositories is tracked in this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). -## Kubernetes Network Security Alerts +## Kubernetes Network Security Alerts **(ULTIMATE)** The GitLab Agent also provides an integration with Cilium. This integration provides a simple way to generate network policy-related alerts and to surface those alerts in GitLab. @@ -426,24 +123,12 @@ There are several components that work in concert for the Agent to generate the - Add the required labels and annotations to existing network policies. - A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) -The setup process follows the same steps as [GitOps](#get-started-with-gitops-and-the-gitlab-agent), +The setup process follows the same [Agent's installation steps](install/index.md), with the following differences: - When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). - You do not need to specify the `gitops` configuration section. -## Management interfaces - -Users with at least the [Developer](../../permissions.md) can access the user interface -for the GitLab Kubernetes agent at **Infrastructure > Kubernetes clusters**, under the -**GitLab Agent managed clusters** tab. This page lists all registered agents for -the current project, and the configuration directory for each agent: - - - -Additional management interfaces are planned for the GitLab Kubernetes Agent. -[Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). - ## Remove the GitLab Kubernetes Agent 1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. @@ -518,7 +203,7 @@ specified the `kas-address` correctly. ``` This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the -`wss` or `ws` URL ends with a training slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` +`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. #### ValidationError(Deployment.metadata) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md new file mode 100644 index 00000000000..fad9d4f08f1 --- /dev/null +++ b/doc/user/clusters/agent/install/index.md @@ -0,0 +1,369 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install the GitLab Kubernetes Agent **(FREE)** + +> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. + +To get started with the GitLab Kubernetes Agent, install it in your cluster. + +Pre-requisites: + +- An existing Kubernetes cluster. +- An account on GitLab. + +## Installation steps + +To install the [GitLab Kubernetes Agent](../index.md) in your cluster: + +1. [Set up the Kubernetes Agent Server](#set-up-the-kubernetes-agent-server) for your GitLab instance. +1. [Define a configuration repository](#define-a-configuration-repository). +1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). +1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). +1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). +1. [Create manifest files](#create-manifest-files). + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. + +### Set up the Kubernetes Agent Server + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Kubernetes Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. + +To use the KAS: + +- If you are a self-managed user, follow the instructions to [install the Kubernetes Agent Server](../../../../administration/clusters/kas.md). +- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. + +### Define a configuration repository + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. +> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + +To configure an Agent, you need: + +1. A GitLab repository to hold the configuration file. +1. Install the Agent in a cluster. + +After installed, when you update the configuration file, GitLab transmits the +information to the cluster automatically without downtime. + +In your repository, add the Agent configuration file under: + +```plaintext +.gitlab/agents/<agent-name>/config.yaml +``` + +Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). + +Your `config.yaml` file specifies all configurations of the Agent, such as: + +- The manifest projects to synchronize. +- The groups that can access this Agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). +- The address of the `hubble-relay` for the Network Security policy integrations. + +As an example, a minimal Agent configuration that sets up only the manifest +synchronizations is: + +```yaml +gitops: + manifest_projects: + # The `id` is the path to the Git repository holding your manifest files + - id: "path/to/your-manifest-project-1" + paths: + - glob: '/**/*.{yaml,yml,json}' +``` + +All the options for the [Kubernetes Agent configuration repository](../repository.md) are documented separately. + +### Create an Agent record in GitLab + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI. + +Next, create a GitLab Rails Agent record to associate it with +the configuration repository project. Creating this record also creates a Secret needed to configure +the Agent in subsequent steps. + +In GitLab: + +1. Ensure that [GitLab CI/CD is enabled in your project](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). +1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Actions**. +1. From the **Select an Agent** dropdown, select the Agent you want to connect and select **Register Agent** to access the installation form. +1. The form reveals your registration token. Securely store this secret token as you cannot view it again. +1. Copy the command under **Recommended installation method**. + +In your computer: + +1. Open your local terminal and connect to your cluster. +1. Run the command you copied from the installation form. + +### Install the Agent into the cluster + +To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, +for example, `gitlab-kubernetes-agent`, run: + +```shell +kubectl create namespace gitlab-kubernetes-agent +``` + +To perform a one-liner installation, run the command below. Make sure to replace: + +- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). +- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. +- `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. +- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. + +```shell +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - +``` + +WARNING: +`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for +testing purposes but for production please make sure to specify a matching version explicitly. + +To find out the various options the above Docker container supports, run: + +```shell +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help +``` + +## Advanced installation + +For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). + +Otherwise, follow the manual installation steps described below. + +### Create the Kubernetes secret + +After generating the token, you must apply it to the Kubernetes cluster. + +To create your Secret, run: + +```shell +kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +``` + +The following example file contains the +Kubernetes resources required for the Agent to be installed. You can modify this +example [`resources.yml` file](#example-resourcesyml-file) in the following ways: + +- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. +- You can configure `kas-address` (Kubernetes Agent Server) in several ways. + The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. + Select the option appropriate for your cluster configuration and GitLab architecture: + - The `wss` scheme (an encrypted WebSockets connection) is specified by default + after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. + When using the sub-chart, you must set `wss://kas.host.tld:443` as + `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. + When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as + `kas-address`, where `GitLab.host.tld` is your GitLab hostname. + - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) + to use an unencrypted WebSockets connection. + When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`). + - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. + In this case, you may specify `kas-address` value as + `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas` + is the name of the service created by `gitlab-kas` chart, and `<your-namespace>` + is the namespace where the chart was installed. + - Specify the `grpcs` scheme to use an encrypted gRPC connection. + - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the + `kas-address` for `wss` and `ws` schemes to whatever you need. + Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) + to learn more about it. + - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. +- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your + secret name in the `secretName:` section. + +To apply this file, run the following command: + +```shell +kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml +``` + +To review your configuration, run the following command: + +```shell +$ kubectl get pods -n gitlab-kubernetes-agent + +NAMESPACE NAME READY STATUS RESTARTS AGE +gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s +``` + +#### Example `resources.yml` file + +```yaml +--- +apiVersion: v1 +kind: Namespace +metadata: + name: gitlab-kubernetes-agent +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: gitlab-kubernetes-agent +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: gitlab-kubernetes-agent +spec: + replicas: 1 + selector: + matchLabels: + app: gitlab-kubernetes-agent + template: + metadata: + labels: + app: gitlab-kubernetes-agent + spec: + serviceAccountName: gitlab-kubernetes-agent + containers: + - name: agent + # Make sure to specify a matching version for production + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z" + args: + - --token-file=/config/token + - --kas-address + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. + volumeMounts: + - name: token-volume + mountPath: /config + volumes: + - name: token-volume + secret: + secretName: gitlab-kubernetes-agent-token + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 0 + maxUnavailable: 1 +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: gitlab-kubernetes-agent-write +rules: +- resources: + - '*' + apiGroups: + - '*' + verbs: + - create + - update + - delete + - patch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: gitlab-kubernetes-agent-write-binding +roleRef: + name: gitlab-kubernetes-agent-write + kind: ClusterRole + apiGroup: rbac.authorization.k8s.io +subjects: +- name: gitlab-kubernetes-agent + kind: ServiceAccount + namespace: gitlab-kubernetes-agent +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: gitlab-kubernetes-agent-read +rules: +- resources: + - '*' + apiGroups: + - '*' + verbs: + - get + - list + - watch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: gitlab-kubernetes-agent-read-binding +roleRef: + name: gitlab-kubernetes-agent-read + kind: ClusterRole + apiGroup: rbac.authorization.k8s.io +subjects: +- name: gitlab-kubernetes-agent + kind: ServiceAccount + namespace: gitlab-kubernetes-agent +``` + +### Create manifest files + +In a previous step, you configured a `config.yaml` to point to the GitLab projects +the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a +templating engine or other means. + +The agent is authorized to download manifests for the configuration +project, and public projects. Support for other private projects is +planned in the issue [Agent authorization for private manifest +projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). + +Each time you push a change to a monitored manifest repository, the Agent logs the change: + +```plaintext +2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea +``` + +#### Example manifest file + +This file creates a minimal `ConfigMap`: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: demo-map + namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. +data: + key: value +``` + +## Example projects + +The following example projects can help you get started with the Kubernetes Agent. + +- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) +- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) + +## View installed Agents + +Users with at least the [Developer](../../../permissions.md) can access the user interface +for the GitLab Kubernetes Agent at **Infrastructure > Kubernetes clusters**, under the +**Agent** tab. This page lists all registered agents for the current project, +and the configuration directory for each agent: + + + +Additional management interfaces are planned for the GitLab Kubernetes Agent. +[Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). + +## Upgrades and version compatibility + +The GitLab Kubernetes Agent is comprised of two major components: `agentk` and `kas`. +As we provide `kas` installers built into the various GitLab installation methods, the required `kas` version corresponds to the GitLab `major.minor` (X.Y) versions. + +At the same time, `agentk` and `kas` can differ by 1 minor version in either direction. For example, +`agentk` 14.4 supports `kas` 14.3, 14.4, and 14.5 (regardless of the patch). + +A feature introduced in a given GitLab minor version might work with other `agentk` or `kas` versions. +To make sure that it works, use at least the same `agentk` and `kas` minor version. For example, +if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2. + +We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to upgrade the `agentk` installations after upgrading GitLab. + +The available `agentk` and `kas` versions can be found in +[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index cbb27a3f343..6ceb2766cc9 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -4,12 +4,13 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Kubernetes Agent configuration repository **(PREMIUM)** +# Kubernetes Agent configuration repository **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. > - The `ci_access` attribute was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +> - The GitLab Kubernetes Agent was [moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -22,17 +23,19 @@ The Agent bootstraps with the GitLab installation URL and an authentication toke and you provide the rest of the configuration in your repository, following Infrastructure as Code (IaaC) best practices. -A minimal repository layout looks like this, with `my_agent_1` as the name +A minimal repository layout looks like this, with `my-agent-1` as the name of your Agent: ```plaintext |- .gitlab |- agents - |- my_agent_1 + |- my-agent-1 |- config.yaml ``` -## Synchronize manifest projects +Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). + +## Synchronize manifest projects **(PREMIUM)** Your `config.yaml` file contains a `gitops` section, which contains a `manifest_projects` section. Each `id` in the `manifest_projects` section is the path to a Git repository @@ -132,7 +135,7 @@ INCORRECT - both globs match `*.yaml` files in the root directory: ```yaml gitops: manifest_projects: - - id: project1 + - id: project1 paths: - glob: '/**/*.yaml' - glob: '/*.yaml' @@ -143,51 +146,140 @@ CORRECT - single globs matches all `*.yaml` files recursively: ```yaml gitops: manifest_projects: - - id: project1 + - id: project1 paths: - glob: '/**/*.yaml' ``` -## Authorize groups to use an Agent +## Authorize projects and groups to use an Agent + +> - Group authorization [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +> - Project authorization [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. + +If you use the same cluster across multiple projects, you can set up the [CI/CD Tunnel](ci_cd_tunnel.md) +to grant access to an Agent from one or more projects or groups. This way, all the authorized +projects can access the same Agent, which facilitates you to save resources and have a scalable setup. + +When you authorize a project to use an agent through the [CI/CD Tunnel](ci_cd_tunnel.md), +the selected Kubernetes context is automatically injected into CI/CD jobs, allowing you to +run Kubernetes commands from your authorized projects' scripts. When you authorize a group, +all the projects that belong to that group can access the selected agent. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +An Agent can only authorize projects or groups in the same group hierarchy as the Agent's configuration +project. You can authorize up to 100 projects and 100 groups per Agent. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the `group_authorized_agents` flag](../../../administration/feature_flags.md). -On GitLab.com, this feature is available. +### Authorize projects to use an Agent -If you use the same cluster across multiple projects, you can set up the CI/CD Tunnel -to grant the Agent access to one or more groups. This way, all the projects that belong -to the authorized groups can access the same Agent. This enables you to save resources and -have a scalable setup. +To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md): -When you authorize a group, the agent's Kubernetes context is automatically injected -into every project of the authorized group, and users can select the connection as -described in the [CI/CD Tunnel documentation](ci_cd_tunnel.md). -To authorize a group to access the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md), -use the `ci_access` attribute in your `config.yaml` configuration file. +1. Go to your Agent's configuration project. +1. Edit the Agent's configuration file (`config.yaml`). +1. Add the `projects` attribute into `ci_access`. +1. Identify the project through its path: -An Agent can only authorize groups in the same group hierarchy as the Agent's configuration project. At most -100 groups can be authorized per Agent. + ```yaml + ci_access: + projects: + - id: path/to/project + ``` -To authorize a group: +### Authorize groups to use an Agent -1. Edit your `config.yaml` file under the `.gitlab/agents/<agent name>` directory. -1. Add the `ci_access` root attribute. +To grant access to all projects within a group: + +1. Go to your Agent's configuration project. +1. Edit the Agent's configuration file (`config.yaml`). 1. Add the `groups` attribute into `ci_access`. -1. Add the group `id` into `groups`, identifying the authorized group through its path. +1. Identify the group or subgroup through its path: + + ```yaml + ci_access: + groups: + - id: path/to/group/subgroup + ``` + +### Use impersonation to restrict project and group access **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. + +By default, the [CI/CD Tunnel](ci_cd_tunnel.md) inherits all the permissions from the service account used to install the +Agent in the cluster. +To restrict access to your cluster, you can use [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). + +To specify impersonations, use the `access_as` attribute in your Agent's configuration file and use Kubernetes RBAC rules to manage impersonated account permissions. + +You can impersonate: + +- The Agent itself (default). +- The CI job that accesses the cluster. +- A specific user or system account defined within the cluster. + +#### Impersonate the Agent -For example: +The Agent is impersonated by default. You don't need to do anything to impersonate it. + +#### Impersonate the CI job that accesses the cluster + +To impersonate the CI job that accesses the cluster, add the `ci_job: {}` key-value +under the `access_as` key. + +When the agent makes the request to the actual Kubernetes API, it sets the +impersonation credentials in the following way: + +- `UserName` is set to `gitlab:ci_job:<job id>`. Example: `gitlab:ci_job:1074499489`. +- `Groups` is set to: + - `gitlab:ci_job` to identify all requests coming from CI jobs. + - The list of IDs of groups the project is in. + - The project ID. + - The slug of the environment this job belongs to. + + Example: for a CI job in `group1/group1-1/project1` where: + + - Group `group1` has ID 23. + - Group `group1/group1-1` has ID 25. + - Project `group1/group1-1/project1` has ID 150. + - Job running in a prod environment. + + Group list would be `[gitlab:ci_job, gitlab:group:23, gitlab:group:25, gitlab:project:150, gitlab:project_env:150:prod]`. + +- `Extra` carries extra information about the request. The following properties are set on the impersonated identity: + +| Property | Description | +| -------- | ----------- | +| `agent.gitlab.com/id` | Contains the agent ID. | +| `agent.gitlab.com/config_project_id` | Contains the agent's configuration project ID. | +| `agent.gitlab.com/project_id` | Contains the CI project ID. | +| `agent.gitlab.com/ci_pipeline_id` | Contains the CI pipeline ID. | +| `agent.gitlab.com/ci_job_id` | Contains the CI job ID. | +| `agent.gitlab.com/username` | Contains the username of the user the CI job is running as. | +| `agent.gitlab.com/environment_slug` | Contains the slug of the environment. Only set if running in an environment. | + +Example to restrict access by the CI job's identity: ```yaml ci_access: - # This agent is accessible from CI jobs in projects in these groups - groups: - - id: group/subgroup + projects: + - id: path/to/project + access_as: + ci_job: {} ``` -## Surface network security alerts from cluster to GitLab +#### Impersonate a static identity + +For the given CI/CD Tunnel connection, you can use a static identity for the impersonation. + +Add the `impersonate` key under the `access_as` key to make the request using the provided identity. + +The identity can be specified with the following keys: + +- `username` (required) +- `uid` +- `groups` +- `extra` + +See the [official Kubernetes documentation for more details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) on the usage of these keys. + +## Surface network security alerts from cluster to GitLab **(ULTIMATE)** The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). To integrate, add a top-level `cilium` section to your `config.yml` file. Currently, the @@ -207,6 +299,90 @@ cilium: hubble_relay_address: "hubble-relay.gitlab-managed-apps.svc.cluster.local:80" ``` +## Scan your container images for vulnerabilities + +You can use [cluster image scanning](../../application_security/cluster_image_scanning/index.md) +to scan container images in your cluster for security vulnerabilities. + +To begin scanning all resources in your cluster, add a `starboard` +configuration block to your agent's `config.yaml` with no `filters`: + +```yaml +starboard: + vulnerability_report: + filters: [] +``` + +The namespaces that are able to be scanned depend on the [Starboard Operator install mode](https://aquasecurity.github.io/starboard/latest/operator/configuration/#install-modes). +By default, the Starboard Operator only scans resources in the `default` namespace. To change this +behavior, edit the `STARBOARD_OPERATOR` environment variable in the `starboard-operator` deployment +definition. + +By adding filters, you can limit scans by: + +- Resource name +- Kind +- Container name +- Namespace + +```yaml +starboard: + vulnerability_report: + filters: + - namespaces: + - staging + - production + kinds: + - Deployment + - DaemonSet + containers: + - ruby + - postgres + - nginx + resources: + - my-app-name + - postgres + - ingress-nginx +``` + +A resource is scanned if the resource matches any of the given names and all of the given filter +types (`namespaces`, `kinds`, `containers`, `resources`). If a filter type is omitted, then all +names are scanned. In this example, a resource isn't scanned unless it has a container named `ruby`, +`postgres`, or `nginx`, and it's a `Deployment`: + +```yaml +starboard: + vulnerability_report: + filters: + - kinds: + - Deployment + containers: + - ruby + - postgres + - nginx +``` + +There is also a global `namespaces` field that applies to all filters: + +```yaml +starboard: + vulnerability_report: + namespaces: + - production + filters: + - kinds: + - Deployment + - kinds: + - DaemonSet + resources: + - log-collector +``` + +In this example, the following resources are scanned: + +- All deployments (`Deployment`) in the `production` namespace +- All daemon sets (`DaemonSet`) named `log-collector` in the `production` namespace + ## Debugging To debug the cluster-side component (`agentk`) of the GitLab Kubernetes Agent, set the log diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 31dd503a0cf..88382648b04 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -20,7 +20,7 @@ methods: "one-click install" and "CI/CD template". Both methods are **deprecated Both methods were limiting as you couldn't fully customize your third-party apps installed through GitLab Managed Apps. Therefore, we decided to deprecate this feature and provide -better [GitOps-driven alternatives](https://about.gitlab.com/direction/configure/kubernetes_management/#gitlab-managed-applications) to our users, such as [cluster integrations](integrations.md#cluster-integrations) and [cluster management project](management_project.md). +better [GitOps-driven alternatives](https://about.gitlab.com/direction/configure/kubernetes_management/#gitlab-managed-applications) to our users, such as [cluster integrations](integrations.md) and [cluster management project](management_project.md). ## Install using GitLab CI/CD (DEPRECATED) diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 26611c26e5e..3ad994ecd7e 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -4,9 +4,13 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster cost management **(ULTIMATE)** +# Cluster cost management (DEPRECATED) **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216737) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216737) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. Cluster cost management provides insights into cluster resource usage. GitLab provides an example [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index 8906d1224b1..e6540e68f71 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -4,7 +4,12 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Crossplane configuration **(FREE)** +# Crossplane configuration (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. After [installing](applications.md#install-crossplane-using-gitlab-cicd) Crossplane, you must configure it for use. The process of configuring Crossplane includes: diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 470f65db61b..72bc7b398dc 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -4,10 +4,14 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster Environments **(PREMIUM)** +# Cluster Environments (DEPRECATED) **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 for group-level clusters. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4 for instance-level clusters. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. Cluster environments provide a consolidated view of which CI [environments](../../ci/environments/index.md) are deployed to the Kubernetes cluster and it: diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png Binary files differdeleted file mode 100644 index 3f9cc41838a..00000000000 --- a/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png +++ /dev/null diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png Binary files differnew file mode 100644 index 00000000000..3463eeb5d93 --- /dev/null +++ b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index 70f940c775b..d04cf64d93a 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -4,14 +4,19 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster integrations **(FREE)** +# Cluster integrations (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. GitLab provides several ways to integrate applications to your Kubernetes cluster. To enable cluster integrations, first add a Kubernetes cluster to a GitLab [project](../project/clusters/add_remove_clusters.md) or -[group](../group/clusters/index.md#group-level-kubernetes-clusters) or +[group](../group/clusters/index.md) or [instance](../instance/clusters/index.md). You can install your applications manually as shown in the following sections, or use the @@ -25,10 +30,22 @@ or [Enable Elastic Stack integration for your cluster](#enable-elastic-stack-int depending on which application you are installing. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/326565) to automate this step. +Prometheus and Elastic Stack cluster integrations can only be enabled for clusters [connected through cluster certificates](../project/clusters/add_existing_cluster.md). + +To enable Prometheus for your cluster connected through the [GitLab Kubernetes Agent](agent/index.md), you can [integrate it manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). + +There is no option to enable Elastic Stack for your cluster if it is connected with the GitLab Kubernetes Agent. +Follow this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300230) for updates. + ## Prometheus cluster integration > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. However, you can **still use** Prometheus +for Kubernetes clusters connected to GitLab through the +[GitLab Kubernetes Agent](agent/index.md) by [enabling Prometheus manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). + You can integrate your Kubernetes cluster with [Prometheus](https://prometheus.io/) for monitoring key metrics of your apps directly from the GitLab UI. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index ca6843f6fde..1332310b850 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -4,9 +4,15 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster management project **(FREE)** +# Cluster management project (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +The cluster management project was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +To manage cluster applications, use the [GitLab Kubernetes Agent](agent/index.md) +with the [Cluster Management Project Template](management_project_template.md). A project can be designated as the management project for a cluster. A management project can be used to run deployment jobs with @@ -37,8 +43,7 @@ Management projects are restricted to the following: To use a cluster management project to manage your cluster: 1. Create a new project to serve as the cluster management project -for your cluster. We recommend that you -[create this project based on the Cluster Management project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template). +for your cluster. 1. [Associate the cluster with the management project](#associate-the-cluster-management-project-with-the-cluster). 1. [Configure your cluster's pipelines](#configuring-your-pipeline). 1. [Set the environment scope](#setting-the-environment-scope). diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 305f66c5ec5..c663246cdd8 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -4,15 +4,17 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster Management project template **(FREE)** +# Manage cluster applications **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. > - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead. +> - [Migrated](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/24) to the GitLab Kubernetes Agent in GitLab 14.5. -With a [cluster management project](management_project.md) you can manage -your cluster's deployment and applications through a repository in GitLab. +Use a repository to install, manage, and deploy clusters applications through code. -The Cluster Management project template provides you a baseline to get +## Cluster Management Project Template + +The Cluster Management Project Template provides you a baseline to get started and flexibility to customize your project to your cluster's needs. For instance, you can: @@ -21,49 +23,78 @@ For instance, you can: - Remove the built-in cluster applications you don't need. - Add other cluster applications using the same structure as the ones already available. -The template contains the following [components](#available-components): +The template contains the following [components](#configure-the-available-components): -- A pre-configured GitLab CI/CD file so that you can configure deployment pipelines. +- A pre-configured GitLab CI/CD file so that you can configure CI/CD pipelines using the [CI/CD Tunnel](agent/ci_cd_tunnel.md). - A pre-configured [Helmfile](https://github.com/roboll/helmfile) so that you can manage cluster applications with [Helm v3](https://helm.sh/). - An `applications` directory with a `helmfile.yaml` configured for each application available in the template. -WARNING: -If you used [GitLab Managed Apps](applications.md) to manage your -cluster from GitLab, see how to [migrate from GitLab Managed Apps](migrating_from_gma_to_project_template.md) to the Cluster Management -project. +## Use the Kubernetes Agent with the Cluster Management Project Template + +To use a new project created from the Cluster Management Project Template +with a cluster connected to GitLab through the [GitLab Kubernetes Agent](agent/index.md), +you have two options: + +- [Use one single project](#single-project) to configure the Agent and manage cluster applications. +- [Use separate projects](#separate-projects) - one to configure the Agent and another to manage cluster applications. + +### Single project + +This setup is particularly useful when you haven't connected your cluster +to GitLab through the Agent yet and you want to use the Cluster Management +Project Template to manage cluster applications. + +To use one single project to configure the Agent and to manage cluster applications: + +1. [Create a new project from the Cluster Management Project Template](#create-a-new-project-based-on-the-cluster-management-template). +1. Configure the new project as the [Agent's configuration repository](agent/repository.md) +(where the Agent is registered and its `config.yaml` is stored). +1. From your project's settings, add a [new environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) `$KUBE_CONTEXT` and set it to `path/to/agent-configuration-project:your-agent-name`. +1. [Configure the components](#configure-the-available-components) inherited from the template. + +### Separate projects + +This setup is particularly useful **when you already have a cluster** connected +to GitLab through the Agent and want to use the Cluster Management +Project Template to manage cluster applications. -## Set up the management project from the Cluster Management project template +To use one project to configure the Agent ("project A") and another project to +manage cluster applications ("project B"), follow the steps below. -To set up your cluster's management project off of the Cluster Management project template: +We assume that you already have a cluster connected through the Agent and +[configured through the Agent's configuration repository](agent/repository.md) +("project A"). -1. [Create a new project based on the Cluster Management template](#create-a-new-project-based-on-the-cluster-management-template). -1. [Associate the cluster management project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster). -1. Use the [available components](#available-components) to manage your cluster. +1. [Create a new project from the Cluster Management Project Template](#create-a-new-project-based-on-the-cluster-management-template). +This new project is "project B". +1. In your "project A", [grant the Agent access to the new project (B) through the CI/CD Tunnel](agent/repository.md#authorize-projects-to-use-an-agent). +1. From the "project's B" settings, add a [new environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) `$KUBE_CONTEXT` and set it to `path/to/agent-configuration-project:your-agent-name`. +1. In "project B", [configure the components](#configure-the-available-components) inherited from the template. -### Create a new project based on the Cluster Management template +## Create a new project based on the Cluster Management Template To get started, create a new project based on the Cluster Management project template to use as a cluster management project. -You can either create the [new project](../project/working_with_projects.md#create-a-project) -from the template or import the project from the URL. Importing -the project is useful if you are using a GitLab self-managed -instance that may not have the latest version of the template. +You can either create the new project from the template or import the +project from the URL. Importing the project is useful if you are using +a GitLab self-managed instance that may not have the latest version of +the template. -To create the new project: +To [create the new project](../project/working_with_projects.md#create-a-project): - From the template: select the **GitLab Cluster Management** project template. - Importing from the URL: use `https://gitlab.com/gitlab-org/project-templates/cluster-management.git`. -## Available components +## Configure the available components -Use the available components to configure your cluster: +Use the available components to configure your cluster applications: -- [A `.gitlab-ci.yml` file](#the-gitlab-ciyml-file). -- [A main `helmfile.yml` file](#the-main-helmfileyml-file). -- [A directory with built-in applications](#built-in-applications). +- [The `.gitlab-ci.yml` file](#the-gitlab-ciyml-file). +- [The main `helmfile.yml` file](#the-main-helmfileyml-file). +- [The directory with built-in applications](#built-in-applications). ### The `.gitlab-ci.yml` file @@ -107,8 +138,8 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp - [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md) - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) -#### How to customize your applications +#### Customize your applications -Each app has an `applications/{app}/values.yaml` file (`applicaton/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the +Each app has an `applications/{app}/values.yaml` file (`applications/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the place where you can define default values for your app's Helm chart. Some apps already have defaults pre-defined by GitLab. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 63dd06bcfdb..d98a0a145f2 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Compliance report **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8 as Compliance Dashboard. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in GitLab 12.8 as Compliance Dashboard. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/299360) to compliance report in GitLab 14.2. Compliance report gives you the ability to see a group's merge request activity. It provides a @@ -53,7 +53,7 @@ request: ## Approval status and separation of duties -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in GitLab 13.3. We support a separation of duties policy between users who create and approve merge requests. The approval status column can help you identify violations of this policy. @@ -75,9 +75,9 @@ This column has four states: If you see a non-success state, review the criteria for the merge request's project to ensure it complies with the separation of duties. -## Chain of Custody report **(ULTIMATE)** +## Chain of Custody report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. The Chain of Custody report allows customers to export a list of merge commits within the group. The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, @@ -90,9 +90,9 @@ To download the Chain of Custody report: 1. On the left sidebar, select **Security & Compliance > Compliance report**. 1. Select **List of all merge commits**. -### Commit-specific Chain of Custody Report **(ULTIMATE)** +### Commit-specific Chain of Custody Report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6. You can generate a commit-specific Chain of Custody report for a given commit SHA. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 5318f4deed1..319c1ca6278 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # License Compliance **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.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 @@ -162,7 +162,7 @@ License Compliance can be configured using CI/CD variables. ### Installing custom dependencies -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. +> Introduced in GitLab 11.4. The `license_finder` image already embeds many auto-detection scripts, languages, and packages. Nevertheless, it's almost impossible to cover all cases for all projects. @@ -188,6 +188,21 @@ variables: In this example, `my-custom-install-script.sh` is a shell script at the root directory of your project. +### Working with Monorepos + +Depending on your language, you may need to specify the path to the individual +projects of a monorepo using the `LICENSE_FINDER_CLI_OPTS` variable. Passing in +the project paths can significantly speed up builds over using the `--recursive` +license_finder option. + +```yaml +include: + - template: Security/License-Scanning.gitlab-ci.yml + +variables: + LICENSE_FINDER_CLI_OPTS: "--aggregate_paths=relative-path/to/sub-project/one relative-path/to/sub-project/two" +``` + ### Overriding the template WARNING: @@ -262,7 +277,7 @@ License Compliance uses Java 8 by default. You can specify a different Java vers ### Selecting the version of Python -> - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - [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. > - In [GitLab 12.7](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/101), Python 3.8 became the default. @@ -695,7 +710,7 @@ Additional configuration may be needed for connecting to private registries for: ### SPDX license list name matching -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212388) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212388) in GitLab 13.3. Prior to GitLab 13.3, offline environments required an exact name match for [project policies](#policies). In GitLab 13.3 and later, GitLab matches the name of [project policies](#policies) @@ -705,7 +720,7 @@ instance's administrator can manually update it with a [Rake task](../../../rake ## License list -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. The License list allows you to see your project's licenses and key details about them. @@ -729,7 +744,7 @@ The licenses are displayed, where: ## Policies -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in GitLab 12.9. Policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` license is newly committed it blocks the merge request and instructs the developer to remove it. @@ -752,7 +767,7 @@ Developers of the project can view the policies configured in a project. ## Enabling License Approvals within a project -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in GitLab 12.3. Prerequisites: diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index aa4e3ce6f49..4d6cff96169 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -10,7 +10,7 @@ type: reference, howto GitLab encourages communication through comments, threads, and [code suggestions](../project/merge_requests/reviews/suggestions.md). -There are two types of comments: +Two types of comments are available: - A standard comment. - A comment in a thread, which can be [resolved](#resolve-a-thread). @@ -119,16 +119,15 @@ Notes are added to the page details. If an issue or merge request is locked and closed, you cannot reopen it. -## Mark a comment as confidential +## Mark a comment as confidential **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. **(FREE SELF)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9 [with a flag](../../administration/feature_flags.md) named `confidential_notes`. Disabled by default. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `confidential_notes`. +On GitLab.com, this feature is not available. +You should not use this feature for production environments. You can make a comment confidential, so that it is visible only to project members who have at least the Reporter role. @@ -142,8 +141,6 @@ You can also make an [entire issue confidential](../project/issues/confidential_ ## Show only comments -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. - For issues and merge requests with many comments, you can filter the page to show comments only. 1. Open a merge request's **Discussion** tab, or epic or issue's **Overview** tab. @@ -171,14 +168,12 @@ You can assign an issue to a user who made a comment. ## Create a thread by replying to a standard comment -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9. - When you reply to a standard comment, you create a thread. Prerequisites: - You must have at least the [Guest role](../permissions.md#project-members-permissions). -- You must be in an issue, merge request, or epic. Commits and snippets threads are not supported. +- You must be in an issue, merge request, or epic. Threads in commits and snippets are not supported. To create a thread by replying to a comment: @@ -186,7 +181,7 @@ To create a thread by replying to a comment:  - The reply area is displayed. + The reply section is displayed. 1. Enter your reply. 1. Select **Comment** or **Add comment now** (depending on where in the UI you are replying). @@ -215,8 +210,7 @@ A threaded comment is created. ## Resolve a thread -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11. -> - Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. +> Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. In a merge request, you can resolve a thread when you want to finish a conversation. @@ -286,22 +280,3 @@ with a new push. Threads are now resolved if a push makes a diff section outdated. Threads on lines that don't change and top-level resolvable threads are not resolved. - -## Enable or disable confidential comments **(FREE SELF)** - -Confidential comments are under development and not ready for production use. The feature is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:confidential_notes) -``` - -To disable it: - -```ruby -Feature.disable(:confidential_notes) -``` diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index e0cc79fe0fb..a3aecff6f73 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -135,11 +135,13 @@ the related documentation. | Scheduled Pipeline Cron | `*/5 * * * *` | `3-59/10 * * * *` | | [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | +| [Max number of pipeline triggers in a project](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers) | `25000` for Free tier, Unlimited for all paid tiers | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | | [Max pipelines per schedule](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | `24` for Free tier, `288` for all paid tiers | Unlimited | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | | [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | Free tier: `50` per-group / `50` per-project <br/> All paid tiers: `1_000` per-group / `1_000` per-project | `1_000` per-group / `1_000` per-project | +| [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables) | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | Unlimited | ## Account and limit settings @@ -158,7 +160,7 @@ If you are near or over the repository size limit, you can either NOTE: `git push` and GitLab project imports are limited to 5 GB per request through Cloudflare. Git LFS and imports other than a file upload are not affected by -this limit. +this limit. Repository limits apply to both public and private projects. ## IP range @@ -198,11 +200,11 @@ The following limits apply for [Webhooks](../project/integrations/webhooks.md): | [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks) | `100` per project, `50` per group | `100` per project, `50` per group | | Maximum payload size | 25 MB | 25 MB | -## Shared Build Cloud runners +## Shared Runner Cloud runners GitLab has shared runners on GitLab.com that you can use to run your CI jobs. -For more information, see [GitLab Build Cloud runners](../../ci/runners/index.md). +For more information, see [GitLab Runner Cloud runners](../../ci/runners/index.md). ## Sidekiq @@ -296,6 +298,7 @@ after the limits change in January, 2021: | **All** traffic (from a given **IP address**) | **600** requests per minute | **2,000** requests per minute | **2,000** requests per minute | | **Issue creation** | | **300** requests per minute | **300** requests per minute | | **Note creation** (on issues and merge requests) | | **300** requests per minute | **60** requests per minute | +| **Advanced, project, and group search** API (for a given **IP address**) | | | **10** requests per minute | More details are available on the rate limits for [protected paths](#protected-paths-throttle) and [raw diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 25eff076d8d..9c95b2b21a4 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -5,9 +5,14 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group-level Kubernetes clusters **(FREE)** +# Group-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, +use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). Similar to [project-level](../../project/clusters/index.md) and [instance-level](../../instance/clusters/index.md) Kubernetes clusters, @@ -28,7 +33,7 @@ installation, such as an Ingress controller. ## RBAC compatibility > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29398) in GitLab 11.4. -> - [Project namespace restriction](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) was introduced in GitLab 11.5. +> - Project namespace restriction was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. For each project under a group with a Kubernetes cluster, GitLab creates a restricted service account with [`edit` privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) @@ -44,7 +49,7 @@ to the project, provided the cluster is not disabled. ## Multiple Kubernetes clusters -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) in GitLab Free 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) in GitLab 13.2. You can associate more than one Kubernetes cluster to your group, and maintain different clusters for different environments, such as development, staging, and production. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index b13dd3f63cb..76a8eb77e72 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. -With Contribution Analytics you can get an overview of the [contribution actions](../../../api/events.md#action-types) in your +With Contribution Analytics, you can get an overview of the [contribution events](../../index.md#user-contribution-events) in your group. - Analyze your team's contributions over a period of time, and offer a bonus for the top diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index a9c56139b4d..9378b3922b5 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Custom group-level project templates **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in GitLab 11.6. [Group owners](../permissions.md#group-members-permissions) can set a subgroup to be the source of project templates that are selectable when a new project is created diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index e3b858aff7d..36ccfc1031f 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -48,7 +48,7 @@ With DevOps Adoption you can: - Identify specific subgroups that are lagging in their adoption of GitLab, so you can help them along in their DevOps journey. - Find the subgroups that have adopted certain features, and can provide guidance to other subgroups on how to use those features. - + Feature adoption is based on usage in the previous calendar month. Data is updated on the first day of each month. If the monthly update fails, it tries again daily until successful. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 68df71d1c5d..65e0f31324b 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -7,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Epics **(PREMIUM)** -> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. -> - Single-level epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. +> - Introduced in GitLab 10.2. +> - Single-level epics were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. When [issues](../../project/issues/index.md) share a theme across projects and milestones, you can manage them by using epics. @@ -39,7 +39,7 @@ graph TD ## Roadmap in epics **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in GitLab 11.10. If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that have a start or due date, a visual diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 1b36d6f03df..72fa9e1e310 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -12,7 +12,7 @@ to them. ## Create an epic -> - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in GitLab 13.2. > - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. > - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty roadmap. @@ -25,10 +25,11 @@ To create an epic in the group you're in: - In an empty [roadmap](../roadmap/index.md), select **New epic**. 1. Enter a title. -1. Optional. Enter a description. -1. Optional. To make the epic confidential, select the [Confidentiality checkbox](#make-an-epic-confidential). -1. Optional. Choose labels. -1. Optional. Select a start and due date, or [inherit](#start-and-due-date-inheritance) them. +1. Complete the fields. + - Enter a description. + - To [make the epic confidential](#make-an-epic-confidential), select the checkbox under **Confidentiality**. + - Choose labels. + - Select a start and due date, or [inherit](#start-and-due-date-inheritance) them. 1. Select **Create epic**. The newly created epic opens. @@ -69,38 +70,41 @@ After you create an epic, you can edit the following details: To edit an epic's title or description: -1. Select the **Edit title and description** **{pencil}** button. +1. Select **Edit title and description** **{pencil}**. 1. Make your changes. 1. Select **Save changes**. To edit an epic's start date, due date, or labels: -1. Select **Edit** next to each section in the epic sidebar. +1. Next to each section in the right sidebar, select **Edit**. 1. Select the dates or labels for your epic. ## Bulk edit epics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in GitLab 12.2. -Users with permission level of [Reporter or higher](../../permissions.md) can manage epics. +Users with at least the [Reporter role](../../permissions.md) can manage epics. When bulk editing epics in a group, you can edit their labels. To update multiple epics at the same time: 1. In a group, go to **Epics > List**. -1. Click **Edit epics**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Check the checkboxes next to each epic you want to edit. +1. Select **Edit epics**. A sidebar on the right appears with editable fields. +1. Select the checkboxes next to each epic you want to edit. 1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. +1. Select **Update all**. ## Delete an epic NOTE: -To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup. +To delete an epic, you must be an [Owner](../../permissions.md#group-members-permissions) of a group +or subgroup. -When editing the description of an epic, select the **Delete** button to delete the epic. -A modal appears to confirm your action. +To delete the epic: + +1. Select **Edit title and description** **{pencil}**. +1. Select **Delete**. A modal appears to confirm your action. Deleting an epic releases all existing issues from their associated epic in the system. @@ -112,38 +116,56 @@ If you delete an epic, all its child epics and their descendants are deleted as Whenever you decide that there is no longer need for that epic, close the epic by: -- Selecting the **Close epic** button. +- Selecting **Close epic**.  -- Using a [quick action](../../project/quick_actions.md). +- Using the `/close` [quick action](../../project/quick_actions.md). ## Reopen a closed epic You can reopen an epic that was closed by: -- Clicking the **Reopen epic** button. +- Selecting **Reopen epic**.  -- Using a [quick action](../../project/quick_actions.md). +- Using the `/reopen` [quick action](../../project/quick_actions.md). ## Go to an epic from an issue -If an issue belongs to an epic, you can navigate to the containing epic with the -link in the issue sidebar. +If an issue belongs to an epic, you can go to the parent epic with the +link in the right sidebar.  +## View epics list + +In a group, the left sidebar displays the total count of open epics. +This number indicates all epics associated with the group and its subgroups, including epics you +might not have permission to view. + +To view epics in a group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Epics**. + +### Cached epic count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299540) in GitLab 13.11 [with a flag](../../../administration/feature_flags.md) named `cached_sidebar_open_epics_count`. Enabled by default. +> - Enabled on self-managed and on GitLab.com in GitLab 14.0. [Feature flag `cached_sidebar_open_epics_count`](https://gitlab.com/gitlab-org/gitlab/-/issues/327320) removed. + +The total count of open epics displayed in the sidebar is cached if higher +than 1000. The cached value is rounded to thousands or millions and updated every 24 hours. + ## Search for an epic from epics list page -> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to the [Premium](https://about.gitlab.com/pricing/) tier in GitLab 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. > - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. > - Sorting by epic titles [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.1. -You can search for an epic from the list of epics using filtered search bar (similar to -that of issues and merge requests) based on following parameters: +You can search for an epic from the list of epics using filtered search bar based on following +parameters: - Title or description - Author name / username @@ -152,10 +174,13 @@ that of issues and merge requests) based on following parameters:  -To search, go to the list of epics and select the field **Search or filter results**. -It displays a dropdown menu, from which you can add an author. You can also enter plain -text to search by epic title or description. When done, press <kbd>Enter</kbd> on your -keyboard to filter the list. +To search: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Epics**. +1. Select the field **Search or filter results**. +1. From the dropdown menu, select the scope or enter plain text to search by epic title or description. +1. Press <kbd>Enter</kbd> on your keyboard. The list is filtered. You can also sort epics list by: @@ -173,22 +198,22 @@ The sort option and order is saved and used wherever you browse epics, including ## Change activity sort order -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in GitLab 13.2. You can reverse the default order and interact with the activity feed sorted by most recent items at the top. Your preference is saved via local storage and automatically applied to every epic and issue you view. -To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest +To change the activity sort order, select the **Oldest first** dropdown menu and select either oldest or newest items to be shown first.  ## Make an epic confidential -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0 behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/224513) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -> - You can [use the Confidentiality option in the epic sidebar](https://gitlab.com/gitlab-org/gitlab/-/issues/197340) in GitLab [Premium](https://about.gitlab.com/pricing/) 13.3 and later. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in GitLab 13.0 behind a feature flag, disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/224513) in GitLab 13.2. +> - You can [use the Confidentiality option in the epic sidebar](https://gitlab.com/gitlab-org/gitlab/-/issues/197340) in GitLab 13.3 and later. If you're working on items that contain private information, you can make an epic confidential. @@ -200,8 +225,8 @@ to learn how to create a confidential merge request. To make an epic confidential: -- **When creating an epic:** select the checkbox **Make this epic confidential**. -- **In an existing epic:** in the epic's sidebar, select **Edit** next to **Confidentiality** then +- **When creating an epic:** select the checkbox under **Confidentiality**. +- **In an existing epic:** on the right sidebar, select **Edit** next to **Confidentiality**, and then select **Turn on**. ## Manage issues assigned to an epic @@ -233,12 +258,12 @@ current parent. To add a new issue to an epic: -1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button. +1. On the epic's page, under **Epics and Issues**, select **Add**. 1. Select **Add an existing issue**. 1. Identify the issue to be added, using either of the following methods: - Paste the link of the issue. - Search for the desired issue by entering part of the issue's title, then selecting the desired - match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). + match ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9126) in GitLab 12.5). If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. @@ -252,7 +277,7 @@ while dividing work into smaller parts. To create an issue from an epic: -1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button. +1. On the epic's page, under **Epics and Issues**, select **Add**. 1. Select **Add a new issue**. 1. Under **Title**, enter the title for the new issue. 1. From the **Project** dropdown, select the project in which the issue should be created. @@ -265,7 +290,7 @@ After you remove an issue from an epic, the issue is no longer associated with t To remove an issue from an epic: -1. Select the **Remove** (**{close}**) button next to the issue you want to remove. +1. Next to the issue you want to remove, select **Remove** (**{close}**). The **Remove issue** warning appears. 1. Select **Remove**. @@ -285,7 +310,7 @@ To reorder issues assigned to an epic: ### Move issues between epics **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. New issues appear at the top of the list in the **Epics and Issues** tab. You can move issues from one epic to another. @@ -297,8 +322,8 @@ To move an issue to another epic: ### Promote an issue to an epic -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. If you have the necessary [permissions](../../permissions.md) to close an issue and create an epic in the immediate parent group, you can promote an issue to an epic with the `/promote` @@ -318,7 +343,7 @@ The following issue metadata is copied to the epic: - Upvotes/downvotes. - Participants. - Group labels that the issue already has. -- Parent epic. **(ULTIMATE)** +- Parent epic. ### Use an epic template for repeating issues @@ -331,8 +356,6 @@ For more on epic templates, see [Epic Templates - Repeatable sets of issues](htt ## Multi-level child epics **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7. - You can add any epic that belongs to a group or subgroup of the parent epic's group. New child epics appear at the top of the list of epics in the **Epics and Issues** tab. @@ -344,19 +367,19 @@ Epics can contain multiple nested child epics, up to a total of seven levels dee To add a child epic to an epic: -1. Select the **Add** dropdown button. +1. Select **Add**. 1. Select **Add a new epic**. 1. Identify the epic to be added, using either of the following methods: - Paste the link of the epic. - Search for the desired issue by entering part of the epic's title, then selecting the desired - match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). + match ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9126) in GitLab 12.5). If there are multiple epics to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. ### Move child epics between epics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. New child epics appear at the top of the list in the **Epics and Issues** tab. You can move child epics from one epic to another. @@ -384,13 +407,6 @@ To reorder child epics assigned to an epic: To remove a child epic from a parent epic: -1. Select the <kbd>x</kbd> button in the parent epic's list of epics. -1. Select **Remove** in the **Remove epic** warning message. - -## Cached epic count - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299540) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327320) in GitLab 14.0. - -In a group, the sidebar displays the total count of open epics and this value is cached if higher -than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. +1. Select **Remove** (**{close}**) in the parent epic's list of epics. + The **Remove epic** warning appears. +1. Select **Remove**. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 1f5de36303e..70406cfe8e8 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -7,9 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Migrate groups from another instance of GitLab **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - Enabled on GitLab.com. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. NOTE: The importer migrates **only** the group data listed on this page. To leave feedback on this @@ -19,23 +18,23 @@ Using GitLab Group Migration, you can migrate existing top-level groups from Git The following resources are migrated to the target instance: -- Groups ([Introduced in 13.7](https://gitlab.com/groups/gitlab-org/-/epics/4374)) +- Groups ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4374) in 13.7) - description - attributes - subgroups - - avatar ([Introduced in 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/322904)) -- Group Labels ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/292429)) + - avatar ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322904) in 14.0) +- Group Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) - title - description - color - - created_at ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300007)) - - updated_at ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300007)) -- Members ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/299415)) + - created_at ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300007) in 13.10) + - updated_at ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300007) in 13.10) +- Members ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299415) in 13.9) Group members are associated with the imported group if: - The user already exists in the target GitLab instance and - The user has a public email in the source GitLab instance that matches a confirmed email in the target GitLab instance -- Epics ([Introduced in 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/250281)) +- Epics ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250281) in 13.7) - title - description - state (open / closed) @@ -43,12 +42,12 @@ The following resources are migrated to the target instance: - due date - epic order on boards - confidentiality - - labels ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/297460)) - - author ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/298745)) - - parent epic ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/297459)) - - emoji award ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/297466)) - - events ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/297465)) -- Milestones ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/292427)) + - labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297460) in 13.9) + - author ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298745) in 13.9) + - parent epic ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297459) in 13.9) + - emoji award ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297466) in 13.9) + - events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297465) in 13.10) +- Milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292427) in 13.10) - title - description - state (active / closed) @@ -56,8 +55,8 @@ The following resources are migrated to the target instance: - due date - created at - updated at - - iid ([Introduced in 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/326157)) -- Iterations ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/292428)) + - iid ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326157) in 13.11) +- Iterations ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292428) in 13.10) - iid - title - description @@ -66,7 +65,7 @@ The following resources are migrated to the target instance: - due date - created at - updated at -- Badges ([Introduced in 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/292431)) +- Badges ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292431) in 13.11) - name - link URL - image URL @@ -77,19 +76,20 @@ Any other items are **not** migrated. ## Enable or disable GitLab Group Migration -GitLab Migration is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it. +GitLab Migration is deployed behind the `bulk_import` feature flag, which is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it. -To enable it: +To disable it: ```ruby -Feature.enable(:bulk_import) +Feature.disable(:bulk_import) ``` -To disable it: +To enable it: ```ruby -Feature.disable(:bulk_import) +Feature.enable(:bulk_import) ``` ## Import your groups into GitLab @@ -130,3 +130,8 @@ Migration importer page. The remote groups you have the Owner role for are liste 1. After a group has been imported, select its GitLab path to open its GitLab URL.  + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](../../project/import/index.md#automate-group-and-project-import). diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 15d2da50012..f0e08301a1b 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -95,10 +95,8 @@ For details about groups, watch [GitLab Namespaces (users, groups and subgroups) You can give a user access to all projects in a group. -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. -1. Find your group and select it. -1. From the left sidebar, select **Group information > Members**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. 1. Fill in the fields. - The role applies to all projects in the group. [Learn more about permissions](../permissions.md). - On the **Access expiration date**, the user can no longer access projects in the group. @@ -107,9 +105,7 @@ You can give a user access to all projects in a group. As a user, you can request to be a member of a group, if an administrator allows it. -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. -1. Find the group and select it. +1. On the top bar, select **Menu > Groups** and find your group. 1. Under the group name, select **Request Access**. As many as ten of the most-recently-active group owners receive an email with your request. @@ -219,10 +215,13 @@ By default, every group inherits the branch protection set at the global level. To change this setting for a specific group: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. +1. Find the group and select it. +1. From the left menu, select **Settings > General**. 1. Expand the **Permissions, LFS, 2FA** section. 1. Select the desired option in the **Default branch protection** dropdown list. -1. Click **Save changes**. +1. Select **Save changes**. To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches). @@ -240,24 +239,26 @@ There are two different ways to add a new project to a group: ### Specify who can add projects to a group -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab Premium 10.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to GitLab Free in 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group. To change this setting for a specific group: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. +1. Find the group and select it. +1. From the left menu, select **Settings > General**. 1. Expand the **Permissions, LFS, 2FA** section. 1. Select the desired option in the **Allowed to create projects** dropdown list. -1. Click **Save changes**. +1. Select **Save changes**. To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). ## Group activity analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as -a [beta feature](https://about.gitlab.com/handbook/product/#beta). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [beta feature](https://about.gitlab.com/handbook/product/#beta). For a group, you can view how many merge requests, issues, and members were created in the last 90 days. @@ -265,6 +266,8 @@ These Group Activity Analytics can be enabled with the `group_activity_analytics  +Changes to [group wikis](../project/wiki/group.md) do not appear in group activity analytics. + ### View group activity You can view the most recent actions taken in a group, either in your browser or in an RSS feed: @@ -307,7 +310,7 @@ All the members of the `Engineering` group are added to the `Frontend` group. > - Enabled on GitLab.com. > - Recommended for production use. > - Replaces the existing form with buttons to open a modal window. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../project/members/index.md#enable-or-disable-modal-window). **(FREE SELF)** +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../project/members/index.md#enable-or-disable-modal-window). WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -327,7 +330,7 @@ Group syncing allows LDAP groups to be mapped to GitLab groups. This provides mo Group links can be created by using either a CN or a filter. To create these group links, go to the group's **Settings > LDAP Synchronization** page. After configuring the link, it may take more than an hour for the users to sync with the GitLab group. -For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync). +For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/ldap_synchronization.md#group-sync). NOTE: When you add LDAP synchronization, if an LDAP user is a group member and they are not part of the LDAP group, they are removed from the group. @@ -410,7 +413,7 @@ because the project cannot be moved. ## Use a custom name for the initial branch -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. When you create a new project in GitLab, a default branch is created with the first push. The group owner can @@ -430,7 +433,7 @@ This action removes the group. It also adds a background job to delete all proje Specifically: -- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [GitLab Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). - In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. @@ -502,6 +505,9 @@ To prevent a project from being shared with other groups: 1. Select **Prevent sharing a project within `<group_name>` with other groups**. 1. Select **Save changes**. +This setting applies to all subgroups unless overridden by a group owner. Groups already +added to a project lose access when the setting is enabled. + ## Prevent members from being added to a group **(PREMIUM)** As a group owner, you can prevent any new project membership for all @@ -522,10 +528,8 @@ API requests to add a new user to a project are not possible. ## Export members as CSV **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the :ff_group_membership_export flag](../../administration/feature_flags.md). On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. You can export a list of members in a group as a CSV. @@ -535,8 +539,8 @@ You can export a list of members in a group as a CSV. ## Restrict group access by IP address **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. To ensure only people from your organization can access particular resources, you can restrict access to groups by IP address. This group-level setting @@ -571,7 +575,7 @@ To restrict group access by IP address: ## Restrict group access by domain **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in GitLab 12.2. > - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. > - Support for restricting access to projects within the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. @@ -614,7 +618,7 @@ To learn how to create templates for issues and merge requests, see [Description templates](../project/description_templates.md). Define project templates at a group level by setting a group as the template source. -[Learn more about group-level project templates](custom_project_templates.md). **(PREMIUM)** +[Learn more about group-level project templates](custom_project_templates.md). ### Enable group file template **(PREMIUM)** @@ -693,7 +697,7 @@ In GitLab 13.11 and above the group setting for delayed project removal is inher > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. By default, projects in a group can be forked. -Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, +Optionally, on [GitLab Premium](https://about.gitlab.com/pricing/) or higher tiers, you can prevent the projects in a group from being forked outside of the current top-level group. Previously, this setting was available only for groups enforcing a @@ -732,19 +736,17 @@ The group's new subgroups have push rules set for them based on either: ## Group approval rules **(PREMIUM)** -> Introduced in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md). -The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `group_merge_request_approval_settings_feature_flag`. On GitLab.com, this feature is available. -Group approval rules are an in-development feature that provides an interface for managing -[project merge request approval rules](../project/merge_requests/approvals/index.md) at the -top-level group level. When rules are configured [at the instance level](../admin_area/merge_requests_approvals.md), -you can't edit locked rules. +Group approval rules manage [project merge request approval rules](../project/merge_requests/approvals/index.md) +at the top-level group level. These rules [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) +that belong to the group. -To view the merge request approval rules UI for a group: +To view the merge request approval rules for a group: 1. Go to the top-level group's **Settings > General** page. 1. Expand the **Merge request approvals** section. @@ -754,20 +756,20 @@ To view the merge request approval rules UI for a group: ## Related topics - [Group wikis](../project/wiki/index.md) -- [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). **(FREE SELF)** -- [Repositories analytics](repositories_analytics/index.md): View overall activity of all projects with code coverage. **(PREMIUM)** +- [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). +- [Repositories analytics](repositories_analytics/index.md): View overall activity of all projects with code coverage. - [Contribution analytics](contribution_analytics/index.md): View the contributions (pushes, merge requests, - and issues) of group members. **(PREMIUM)** -- [Issue analytics](issues_analytics/index.md): View a bar chart of your group's number of issues per month. **(PREMIUM)** + and issues) of group members. +- [Issue analytics](issues_analytics/index.md): View a bar chart of your group's number of issues per month. - Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. -- [Epics](epics/index.md): Track groups of issues that share a theme. **(ULTIMATE)** +- [Epics](epics/index.md): Track groups of issues that share a theme. - [Security Dashboard](../application_security/security_dashboard/index.md): View the vulnerabilities of all - the projects in a group and its subgroups. **(ULTIMATE)** + the projects in a group and its subgroups. - [Insights](insights/index.md): Configure insights like triage hygiene, issues created/closed per a given period, and - average time for merge requests to be merged. **(ULTIMATE)** + average time for merge requests to be merged. - [Webhooks](../project/integrations/webhooks.md). - [Kubernetes cluster integration](clusters/index.md). -- [Audit Events](../../administration/audit_events.md#group-events). **(PREMIUM)** +- [Audit Events](../../administration/audit_events.md#group-events). - [Pipelines quota](../admin_area/settings/continuous_integration.md): Keep track of the pipeline quota for the group. - [Integrations](../admin_area/settings/project_integration_management.md). - [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). @@ -775,7 +777,7 @@ To view the merge request approval rules UI for a group: - [Lock the sharing with group feature](#prevent-a-project-from-being-shared-with-groups). - [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforce-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. -- Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/features.md).. +- Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/features.md). ## Troubleshooting diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 9f841691eb8..b3fdeb0ab41 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Insights **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. Configure the Insights that matter for your groups. Explore data such as triage hygiene, issues created or closed for a given period, average time for merge diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 3d28ef5306d..ac5df6b052f 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 70fa3ba639d..7a1cbe86d58 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Enabled on GitLab.com. > - Can be enabled or disabled per-group. > - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-iterations). **(PREMIUM ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-iterations). > - Moved to GitLab Premium in 13.9. Iterations are a way to track issues over a period of time. This allows teams @@ -38,7 +38,7 @@ In GitLab, iterations are similar to milestones, with a few differences: > - Deployed behind a [feature flag](../../feature_flags.md), disabled by default. > - Disabled on GitLab.com. > - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-iteration-cadences). **(PREMIUM SELF)** +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-iteration-cadences). This in-development feature might not be available for your use. There can be [risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). @@ -144,7 +144,7 @@ To view an iteration report, go to the iterations list page and select an iterat ### Iteration burndown and burnup charts -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in GitLab 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in GitLab 13.7. The iteration report includes [burndown and burnup charts](../../project/milestones/burndown_and_burnup_charts.md), diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 656c40d1915..206f3172170 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -7,11 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Roadmap **(PREMIUM)** -> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5. -> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198062), Roadmaps were moved to the Premium tier. +> - Introduced in GitLab 10.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/198062) from GitLab Ultimate to GitLab Premium in 12.9. > - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/5164) and later, the epic bars show epics' title, progress, and completed weight percentage. > - Milestones appear in roadmaps in [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/6802), and later. -> - Feature flag for milestones visible in roadmaps removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29641). +> - Feature flag for milestones visible in roadmaps [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29641) in GitLab 13.0. > - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/214375) and later, the Roadmap also shows milestones in projects in a group. > - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/212494) and later, milestone bars can be collapsed and expanded. @@ -36,13 +36,10 @@ toggle the list of the milestone bars. ## Sort and filter the Roadmap -> - Filtering roadmaps by milestone [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218621) in GitLab 13.7. -> - Filtering roadmaps by milestone is [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - Filtering roadmaps by milestone is enabled on GitLab.com. -> - Filtering roadmaps by milestone is recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM SELF)** +> - Filtering by milestone [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218621) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `roadmap_daterange_filter`. Enabled by default. > - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.9. > - Filtering by epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218623) in GitLab 13.11. +> - Filtering by milestone [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323917) in GitLab 14.5. WARNING: Filtering roadmaps by milestone might not be available to you. Check the **version history** note above for details. @@ -56,8 +53,6 @@ A dropdown menu lets you show only open or closed epics. By default, all epics a You can sort epics in the Roadmap view by: -- Created date -- Last updated - Start date - Due date @@ -77,40 +72,16 @@ You can also filter epics in the Roadmap view by the epics': Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). -### Enable or disable filtering roadmaps by milestone **(PREMIUM SELF)** - -Filtering roadmaps by milestone is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:async_filtering) -``` - -To disable it: - -```ruby -Feature.disable(:async_filtering) -``` - ## Timeline duration -> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198062), Timelines were moved to the Premium tier. +> - Introduced in GitLab 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/198062) from GitLab Ultimate to GitLab Premium in 12.9. ### Date range presets > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/204994) in GitLab 14.3. [Deployed behind the `roadmap_daterange_filter` flag](../../../administration/feature_flags.md), disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/323917) in GitLab 14.3. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, -ask an administrator to [enable the `roadmap_daterange_filter` flag](../../../administration/feature_flags.md). -On GitLab.com, this feature is available. -The feature is ready for production use. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/323917) in GitLab 14.3. +> - [Feature flag `roadmap_daterange_filter` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72419) in GitLab 14.5. Roadmap provides three date range options, each with predetermined timeline duration: diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 1c894550a14..402007b85b2 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -118,8 +118,9 @@ SSO has the following effects when enabled: - For groups, users can't share a project in the group outside the top-level group, even if the project is forked. -- For a Git activity, users must be signed-in through SSO before they can push to or - pull from a GitLab repository. +- 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. +- Credentials that are not tied to regular users (for example, access tokens and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> @@ -242,11 +243,12 @@ On subsequent visits, you should be able to go [sign in to GitLab.com with SAML] ### Configure user settings from SAML response -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. GitLab allows setting certain user attributes based on values from the SAML response. -This affects users created on first sign-in via Group SAML. Existing users' -attributes are not affected regardless of the values sent in 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. #### Supported user attributes @@ -341,9 +343,8 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o ``` NOTE: +The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools). -Also note that the value for `Groups` or `groups` in the SAML response can be either the group name or -the group ID depending what the IdP sends to GitLab. When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users see a new menu item in group **Settings > SAML Group Links**. You can configure one or more **SAML Group Links** to map @@ -516,6 +517,13 @@ Here are possible causes and solutions: | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user needs to [link their account](#user-access-and-management). | +User accounts are created in one of the following ways: + +- User registration +- Sign in through OAuth +- Sign in through SAML +- SCIM provisioning + ### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" 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. @@ -531,6 +539,16 @@ Alternatively, the SAML response may be missing the `InResponseTo` attribute in The identity provider administrator should ensure that the login is initiated by the service provider and not the identity provider. +### Message: "Login to a GitLab account to link with your SAML identity" + +A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](#linking-saml-to-your-existing-gitlabcom-account). + +To resolve this problem, the user should check they are using the correct GitLab password to log in. They first need to +[reset their password](https://gitlab.com/users/password/new) if both: + +- The account was provisioned by SCIM. +- This is the first time the user has logged in the username and password. + ### Stuck in a login "loop" Ensure that the **GitLab single sign-on URL** has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 5e90501d487..dd4558b4a3e 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SCIM provisioning using SAML SSO for GitLab.com groups **(PREMIUM SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab Premium 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. System for Cross-domain Identity Management (SCIM), is an open standard that enables the automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of @@ -35,9 +35,10 @@ The following identity providers are supported: Once [Group Single Sign-On](index.md) has been configured, we can: -1. Navigate to the group and click **Administration > SAML SSO**. -1. Click on the **Generate a SCIM token** button. -1. Save the token and URL so they can be used in the next step. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > SAML SSO**. +1. Select **Generate a SCIM token**. +1. Save the token and URL for use in the next step.  @@ -50,14 +51,14 @@ Once [Group Single Sign-On](index.md) has been configured, we can: The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) now needs to be set up for SCIM. -1. Set up automatic provisioning and administrative credentials by following the +1. Enable automatic provisioning and administrative credentials by following the [Azure's SCIM setup documentation](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim). During this configuration, note the following: -- The `Tenant URL` and `secret token` are the ones retrieved in the +- The `Tenant URL` and `secret token` are the items retrieved in the [previous step](#gitlab-configuration). -- It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox. +- We recommend setting a notification email and selecting the **Send an email notification when a failure occurs** checkbox. - For mappings, we only leave `Synchronize Azure Active Directory Users to AppName` enabled. `Synchronize Azure Active Directory Groups to AppName` is usually disabled. However, this does not mean Azure AD users cannot be provisioned in groups. Leaving it enabled does not break @@ -113,29 +114,27 @@ Make sure that the Okta setup matches our documentation exactly, especially the configuration. Otherwise, the Okta SCIM app may not work properly. 1. Sign in to Okta. -1. If you see an **Admin** button in the top right, click the button. This will - ensure you are in the Admin area. +1. Ensure you are in the Admin section by selecting the **Admin** button located in the top right. The admin button is not visible from the admin page. NOTE: - If you're using the Developer Console, click **Developer Console** in the top - bar and select **Classic UI**. Otherwise, you may not see the buttons described - in the following steps: + If you're using the Developer Console, select **Developer Console** in the top + bar and then select **Classic UI**. Otherwise, you may not see the buttons described in the following steps: -1. In the **Application** tab, click **Add Application**. -1. Search for **GitLab**, find and click on the 'GitLab' application. -1. On the GitLab application overview page, click **Add**. +1. In the **Application** tab, select **Add Application**. +1. Search for **GitLab**, find and select on the 'GitLab' application. +1. On the GitLab application overview page, select **Add**. 1. Under **Application Visibility** select both checkboxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users. -1. Click **Done** to finish adding the application. -1. In the **Provisioning** tab, click **Configure API integration**. +1. Select **Done** to finish adding the application. +1. In the **Provisioning** tab, select **Configure API integration**. 1. Select **Enable API integration**. - For **Base URL** enter the URL obtained from the GitLab SCIM configuration page - For **API Token** enter the SCIM token obtained from the GitLab SCIM configuration page -1. Click 'Test API Credentials' to verify configuration. -1. Click **Save** to apply the settings. -1. After saving the API integration details, new settings tabs appear on the left. Choose **To App**. -1. Click **Edit**. -1. Check the box to **Enable** for both **Create Users** and **Deactivate Users**. -1. Click **Save**. +1. Select 'Test API Credentials' to verify configuration. +1. Select **Save** to apply the settings. +1. After saving the API integration details, new settings tabs appear on the left. Select **To App**. +1. Select **Edit**. +1. Select the **Enable** checkbox for both **Create Users** and **Deactivate Users**. +1. Select **Save**. 1. Assign users in the **Assignments** tab. Assigned users are created and managed in your GitLab group. @@ -147,8 +146,8 @@ application described above. ### OneLogin -OneLogin provides a "GitLab (SaaS)" app in their catalog, which includes a SCIM integration. -As the app is developed by OneLogin, please reach out to OneLogin if you encounter issues. +As the developers of this app, OneLogin provides a "GitLab (SaaS)" app in their catalog, which includes a SCIM integration. +Please reach out to OneLogin if you encounter issues. ## User access and linking setup @@ -177,8 +176,8 @@ As long as [Group SAML](index.md) has been configured, existing GitLab.com users - By following these steps: 1. Sign in to GitLab.com if needed. - 1. Click on the GitLab app in the identity provider's dashboard or visit the **GitLab single sign-on URL**. - 1. Click on the **Authorize** button. + 1. In the identity provider's dashboard select the GitLab app or visit the **GitLab single sign-on URL**. + 1. Select the **Authorize**. We recommend users do this prior to turning on sync, because while synchronization is active, there may be provisioning errors for existing users. diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 3f9d94f044e..3692a2636ab 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -40,7 +40,7 @@ be imported into the desired group structure. - To preserve the member list and their respective permissions on imported groups, review the users in these groups. Make sure these users exist before importing the desired groups. -### Exported Contents +### Exported contents The following items are exported: @@ -51,8 +51,8 @@ The following items are exported: - Subgroups (including all the aforementioned data) - Epics - Events -- [Wikis](../../project/wiki/index.md#group-wikis) **(PREMIUM SELF)** - (Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247)) +- [Wikis](../../project/wiki/group.md) + ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9) The following items are **not** exported: @@ -109,6 +109,11 @@ The Enterprise Edition retains some group data that isn't part of the Community Your newly imported group page appears after the operation completes. +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](../../project/import/index.md#automate-group-and-project-import). + ## Version history ### 14.0+ diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 49032d0a2ef..acce296da93 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto, concepts --- -# Subgroups +# Subgroups **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2772) in GitLab 9.0. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 5c8393f30ab..a0a13c71d95 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Value Stream Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 for groups. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in GitLab 12.9 for groups. Value Stream Analytics measures the time spent to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) @@ -27,6 +27,7 @@ To view group-level Value Stream Analytics: Value Stream Analytics at the group level includes data for the selected group and its subgroups. +NOTE: [Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available. ## Default stages @@ -77,16 +78,41 @@ Data is shown for workflow items created during the selected date range. To filt 1. Optionally select a project. 1. Select a date range using the available date pickers. +### Upcoming date filter change + +In the [epics](https://gitlab.com/groups/gitlab-org/-/epics/6046), we plan to alter +the date filter behavior to filter the end event time of the currently selected stage. + +The change makes it possible to get a much better picture about the completed items within the +stage and helps uncover long-running items. + +For example, an issue was created a year ago and the current stage was finished in the current month. +If you were to look at the metrics for the last three months, this issue would not be included in the calculation of +the stage metrics. With the new date filter, this item would be included. + +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. + ## How metrics are measured -> DORA API-based deployment metrics [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) -> to Premium in GitLab 14.3 for group-level Value Stream Analytics. +> DORA API-based deployment metrics for group-level Value Stream Analytics were +> [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. The "Time" metrics near the top of the page are measured as follows: - **Lead time**: median time from issue created to issue closed. - **Cycle time**: median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../../project/issues/crosslinking_issues.md#from-commit-messages).) +- **Lead Time for Changes**: median time between when a merge request is merged and deployed to a +production environment for all merge requests deployed in the given time period. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. + +- **Lead Time for Changes**: median duration between merge request merge and deployment to a production environment for all MRs deployed in the given time period. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. The "Recent Activity" metrics near the top of the page are measured as follows: @@ -391,8 +417,8 @@ To delete a custom value stream: ## Days to completion chart > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. -> - [Chart median line removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. -> - [Totals replaced with averages](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) in GitLab 13.12. +> - Chart median line [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. +> - Totals [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) with averages in GitLab 13.12. This chart visually depicts the average number of days it takes for cycles to be completed. @@ -404,7 +430,7 @@ The chart data is limited to the last 500 items. ## Type of work - Tasks by type chart -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in GitLab 12.10. This chart shows a cumulative count of issues and merge requests per day. diff --git a/doc/user/index.md b/doc/user/index.md index c9f20af9668..a3b7cfc4b3c 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -85,6 +85,7 @@ There are several types of users in GitLab: ## User activity +GitLab tracks user contribution activity. You can follow or unfollow other users from their [user profiles](profile/index.md#access-your-user-profile). To view a user's activity in a top-level Activity view: @@ -92,6 +93,55 @@ To view a user's activity in a top-level Activity view: 1. In the GitLab menu, select **Activity**. 1. Select the **Followed users** tab. +### User contribution events + +Each of these contribution events is tracked: + +- `approved` + - Merge request +- `closed` + - [Epic](group/epics/index.md) + - Issue + - Merge request + - Milestone +- `commented` on any `Noteable` record. + - Alert + - Commit + - Design + - Issue + - Merge request + - Snippet +- `created` + - Design + - [Epic](group/epics/index.md) + - Issue + - Merge request + - Milestone + - Project + - Wiki page +- `destroyed` + - Design + - Milestone + - Wiki page +- `expired` + - Project membership +- `joined` + - Project membership +- `left` + - Project membership +- `merged` + - Merge request +- `pushed` commits to (or deleted commits from) a repository, individually or in bulk. + - Project +- `reopened` + - [Epic](group/epics/index.md) + - Issue + - Merge request + - Milestone +- `updated` + - Design + - Wiki page + ## Projects In GitLab, you can create [projects](project/index.md) to host diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 636cb1bb457..21387998a17 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -6,62 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Connect a cluster to GitLab **(FREE)** -You can create new or connect existing clusters to GitLab through different [levels](#cluster-levels), -using different [methods](#methods-to-connect-a-cluster-to-gitlab). +The [certificate-based Kubernetes integration with GitLab](../index.md) +was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) +in GitLab 14.5. To connect your clusters, use the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). -Before getting started: - -1. Check the [supported Kubernetes cluster versions](#supported-cluster-versions). -1. Define the [cluster level](#cluster-levels) according to your case. - -After that: - -1. Choose the [method](#methods-to-connect-a-cluster-to-gitlab) -to connect your cluster according to your case. -1. [View your clusters](#view-your-clusters) connected to GitLab. - -## Methods to connect a cluster to GitLab - -GitLab offers three methods to connect existing and create new clusters: - -- **GitLab Kubernetes Agent**: the best solution to -[connect existing clusters](#connect-existing-clusters-to-gitlab). -- **Infrastructure as Code**: it's a broader infrastructure management -toolset that includes managing your cluster. It's the recommended -solution to [create a new cluster](#create-new-clusters-from-gitlab) -from GitLab. -- **Certificate-based method**: our first and legacy solution uses -cluster certificates to connect your cluster to GitLab. It is no longer -recommended for [security implications](#security-implications-for-clusters-connected-with-certificates). - -### Connect existing clusters to GitLab - -To safely connect and configure an existing cluster on the **project level**, -we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). -We are working to support [the Agent for connecting a cluster at the group level](https://gitlab.com/groups/gitlab-org/-/epics/5784). - -Alternatively, you can use [cluster certificates](../../../project/clusters/add_existing_cluster.md) -to connect clusters in all levels (projects, group, instance). However, -for [security implications](#security-implications-for-clusters-connected-with-certificates), -we don't recommend using this method. - -### Create new clusters from GitLab - -To safely create new clusters from GitLab, use -[Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). - -The [certificate-based method to create a new cluster](../../../project/clusters/add_remove_clusters.md) -is still available through the GitLab UI but was **deprecated** in GitLab 14.0. -If possible, we don't recommend using this method. - -### Connect multiple clusters to a single project - -To connect multiple clusters to a single project in GitLab, -we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). - -You can also use the [certificate-based method](../../../project/clusters/multiple_kubernetes_clusters.md), -but, for [security implications](#security-implications-for-clusters-connected-with-certificates), -we don't recommend using this method. +<!-- TBA: (We need to resolve https://gitlab.com/gitlab-org/gitlab/-/issues/343660 before adding this line) +If you don't have a cluster yet, create one and connect it to GitLab through the Agent. +You can also create a new cluster from GitLab using [Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). +--> ## Supported cluster versions @@ -85,7 +37,13 @@ Kubernetes version to any supported version at any time: Some GitLab features may support versions outside the range provided here. -## Cluster levels +## Cluster levels (DEPRECATED) + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +The [concept of cluster levels was deprecated](../index.md#cluster-levels) +in GitLab 14.5. Choose your cluster's level according to its purpose: @@ -118,6 +76,8 @@ your cluster's level. ## Security implications for clusters connected with certificates +> Connecting clusters to GitLab through cluster certificates was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + WARNING: The whole cluster security is based on a model where [developers](../../../permissions.md) are trusted, so **only trusted users should be allowed to control your clusters**. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 3c934b72886..d1e3bd47b89 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -4,7 +4,16 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# New GKE cluster through IaC +# New GKE cluster through IaC (DEPRECATED) + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +The process described on this page uses cluster certificates to connect the +new cluster to GitLab, [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +You can still create a cluster and then connect it to GitLab through the [Agent](../index.md). +[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/343660) +to migrate this functionality to the [Agent](../index.md). Learn how to create a new cluster on Google Kubernetes Engine (GKE) through [Infrastructure as Code (IaC)](../../index.md). diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index 16ca6d02865..06a77912876 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -6,61 +6,68 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes clusters **(FREE)** -> - Project-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. -> - Group-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. -> - Instance-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. - -Kubernetes is a container orchestration platform to deploy applications -in a cluster without downtime and that scales as you need. - -With the GitLab integration with Kubernetes, you can: - -1. [Connect your cluster](#connect-your-cluster-to-gitlab). -1. [Manage your cluster](#manage-your-cluster). -1. [Deploy your cluster](#deploy-to-your-cluster). - -See the [Kubernetes clusters versions supported by GitLab](connect/index.md#supported-cluster-versions). - -## Connect your cluster to GitLab - -Learn how to [create new and connect existing clusters to GitLab](connect/index.md). - -## Manage your cluster - -- [Cluster Management Project](../../clusters/management_project.md): -create a project to manage your cluster's shared resources requiring -`cluster-admin` privileges such as an Ingress controller. - - [Cluster Management Project Template](../../clusters/management_project_template.md): start a cluster management project directly from a template. - - [Migrate to Cluster Management Project](../../clusters/migrating_from_gma_to_project_template.md): migrate from the deprecated GitLab Managed Apps to Cluster Management Projects. - - [GitLab Managed Apps](../../clusters/applications.md) (deprecated in favor of Cluster Management Projects): configure applications in your cluster directly from GitLab. -- [Cluster integrations](../../clusters/integrations.md): install -third-party applications into your cluster and manage them from GitLab. -- [GitLab-managed clusters](../../project/clusters/gitlab_managed_clusters.md): -enable GitLab to automatically create resources for your clusters. -- [Cost management](../../clusters/cost_management.md): see insights into your cluster's resource usage. -- [Crossplane integration](../../clusters/crossplane.md): manage your cluster's resources and cloud infrastructure with Crossplane. - -### Monitor your cluster - -- [Prometheus monitoring](../../project/integrations/prometheus_library/kubernetes.md): detect and monitor Kubernetes metrics with Prometheus. -- [NGINX monitoring](../../project/integrations/prometheus_library/nginx.md): automatically monitor NGINX Ingress. -- [Clusters health](manage/clusters_health.md): monitor your cluster's health, such as CPU and memory usage. - -### Secure your cluster - -- [Container Host Security](../../project/clusters/protect/container_host_security/index.md): monitor and block activity inside a container and enforce security policies across the cluster. -- [Container Network security](../../project/clusters/protect/container_network_security/index.md): filter traffic going in and out of the cluster and traffic between pods through a firewall with Cilium NetworkPolicies. - -## Deploy to your cluster - -- [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md): use the CI/CD Tunnel to run Kubernetes commands from different projects. -- [Inventory object](deploy/inventory_object.md): track objects applied to a cluster configured with the Kubernetes Agent. -- [Auto DevOps](../../../topics/autodevops/index.md): enable Auto DevOps -to allow GitLab automatically detect, build, test, and deploy applications. -- [Cluster environments](../../clusters/environments.md): view CI/CD environments deployed to Kubernetes clusters. -- [Canary Deployments](../../project/canary_deployments.md): deploy app updates to a small portion of the fleet with this Continuous Delivery strategy. -- [Deploy to your cluster](../../project/clusters/deploy_to_cluster.md): -deploy applications into your cluster using cluster certificates. -- [Deploy Boards](../../project/deploy_boards.md): view the current health and status of each CI/CD environment running on your cluster, and the status of deployment pods. -- [Pod logs](../../project/clusters/kubernetes_pod_logs.md): view the logs of your cluster's running pods. -- [Serverless](../../project/clusters/serverless/index.md) (deprecated): deploy Serverless applications in Kubernetes environments and cloud Function as a Service (FaaS) environments. +To connect clusters to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). + +## Certificate-based Kubernetes integration (DEPRECATED) + +WARNING: +In GitLab 14.5, the certificate-based method to connect Kubernetes clusters +to GitLab was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8), +as well as its related [features](#deprecated-features). + +The certificate-based Kubernetes integration with GitLab is deprecated. +It had the following issues: + +- There were security issues as it required direct access to the Kube API by GitLab. +- The configuration options weren't flexible. +- The integration was flaky. +- Users were constantly reporting issues with features based on this model. + +For this reason, we started to build features based on a new model, the +[GitLab Kubernetes Agent](../../clusters/agent/index.md). +Maintaining both methods in parallel caused a lot of confusion +and significantly increased the complexity to use, develop, maintain, and +document them. For this reason, we decided to deprecate them to focus on the +new model. + +Certificate-based features will continue to receive security and critical +fixes, and features built on top of it will continue to work with the supported +Kubernetes versions. The removal of these features from GitLab is not +scheduled yet. +Follow this [epic](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) +for updates. + +You can find technical information about why we moved away from cluster certificates into +the Kubernetes Agent model on the [Agent's blueprint documentation](../../../architecture/blueprints/gitlab_to_kubernetes_communication/index.md). + +## Deprecated features + +- [Create a new cluster through cluster certificates](../../project/clusters/add_remove_clusters.md) +- [Connect an existing cluster through cluster certificates](../../project/clusters/add_existing_cluster.md) +- [Access controls](../../project/clusters/cluster_access.md) +- [GitLab-managed clusters](../../project/clusters/gitlab_managed_clusters.md) +- [GitLab Managed Apps](../../clusters/applications.md) +- [Deploy applications through certificate-based connection](../../project/clusters/deploy_to_cluster.md) +- [Cluster Management Project](../../clusters/management_project.md) +- [Cluster integrations](../../clusters/integrations.md) +- [Cluster cost management](../../clusters/cost_management.md) +- [Cluster environments](../../clusters/environments.md) +- [Canary Deployments](../../project/canary_deployments.md) +- [Serverless](../../project/clusters/serverless/index.md) +- [Deploy Boards](../../project/deploy_boards.md) +- [Pod logs](../../project/clusters/kubernetes_pod_logs.md) +- [Clusters health](manage/clusters_health.md) +- [Crossplane integration](../../clusters/crossplane.md) +- [Auto Deploy](../../../topics/autodevops/stages.md#auto-deploy) +- [Web terminals](../../../administration/integration/terminal.md) + +### Cluster levels + +The concept of [project-level](../../project/clusters/index.md), +[group-level](../../group/clusters/index.md), and +[instance-level](../../instance/clusters/index.md) clusters becomes +extinct in the new model, although the functionality remains to some extent. + +The Agent is always configured in a single GitLab project, but you can use the CI/CD Tunnel to +[authorize other projects and groups to use the same Agent](../../clusters/agent/repository.md#authorize-projects-and-groups-to-use-an-agent). +By doing so, you are granting these projects and groups access to the same cluster, which is similar to group-level clusters' use case. diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md index 009945589ad..eeb931f392f 100644 --- a/doc/user/infrastructure/clusters/manage/clusters_health.md +++ b/doc/user/infrastructure/clusters/manage/clusters_health.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Clusters health **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in GitLab 10.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) from GitLab Ultimate to GitLab Free in 13.2. When [the Prometheus cluster integration is enabled](../../../clusters/integrations.md#prometheus-cluster-integration), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/apparmor.md b/doc/user/infrastructure/clusters/manage/management_project_applications/apparmor.md index 7fbbbac866c..ae335a180e8 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/apparmor.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/apparmor.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install AppArmor with a cluster management project +# Install AppArmor with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index 9ef7bd0f3ff..12f99af8d8d 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install cert-manager with a cluster management project +# Install cert-manager with a cluster management project **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. > - Support for cert-manager v1.4 was [introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/69405) in GitLab 14.3. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md index c19bfbfb1b1..b5959624954 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Cilium with a cluster management project +# Install Cilium with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md index dbde9bd90b0..3bd675b7439 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md @@ -4,7 +4,7 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Elastic Stack with a cluster management project +# Install Elastic Stack with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md index 7bd2a4a5133..50401e9a391 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Falco with a cluster management project +# Install Falco with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md index c5de0511c2f..ea3a3503f9b 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Fluentd with a cluster management project +# Install Fluentd with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md index 5ee26db754e..503f077df14 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Ingress with a cluster management project +# Install Ingress with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md index 3420f340c94..fd2eed25997 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md @@ -4,7 +4,7 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Prometheus with a cluster management project +# Install Prometheus with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md index 300350010af..9e5d7860a67 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md @@ -4,7 +4,7 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Sentry with a cluster management project +# Install Sentry with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index d6b4eb5c157..4618a95f986 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -1,10 +1,10 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install Vault with a cluster management project +# Install Vault with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 853a39a59a8..e92b2d919ae 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -16,7 +16,7 @@ enabling you to see statistics about the resources that Terraform creates, modifies, or destroys. WARNING: -Like any other job artifact, Terraform Plan data is [viewable by anyone with Guest access](../../permissions.md) to the repository. +Like any other job artifact, Terraform Plan data is viewable by anyone with the Guest [role](../../permissions.md) on the repository. Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform Plan includes sensitive data such as passwords, access tokens, or certificates, we strongly recommend encrypting plan output or modifying the project visibility settings. @@ -77,8 +77,7 @@ To manually configure a GitLab Terraform Report artifact: terraform: $PLAN_JSON ``` - For a full example using the pre-built image, see [Example `.gitlab-ci.yml` - file](#example-gitlab-ciyml-file). + For a full example using the pre-built image, see [Example `.gitlab-ci.yml` file](#example-gitlab-ciyml-file). For an example displaying multiple reports, see [`.gitlab-ci.yml` multiple reports file](#multiple-terraform-plan-reports). diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index fb051c7fa14..84d1edbe2f7 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -205,7 +205,7 @@ and the CI YAML file: The output from the above `terraform` commands should be viewable in the job logs. WARNING: -Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../../permissions.md) to the repository. +Like any other job artifact, Terraform plan data is viewable by anyone with the Guest [role](../../permissions.md) on the repository. Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly recommends encrypting plan output or modifying the project visibility settings. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index e99dc691774..3bb518596cc 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -29,13 +29,12 @@ Learn more about how GitLab can help you run [Infrastructure as Code](iac/index. ## Integrated Kubernetes management -GitLab has special integrations with Kubernetes to help you deploy, manage and troubleshoot -third-party or custom applications in Kubernetes clusters. Auto DevOps provides a full -DevSecOps pipeline by default targeted at Kubernetes based deployments. To support -all the GitLab features, GitLab offers a cluster management project for easy onboarding. -The deploy boards provide quick insights into your cluster, including pod logs tailing. +The GitLab integration with Kubernetes helps you to install, configure, manage, deploy, and troubleshoot +cluster applications. With the GitLab Kubernetes Agent, you can connect clusters behind a firewall, +have real-time access to API endpoints, perform pull-based or push-based deployments for production +and non-production environments, and much more. -Learn more about the [GitLab integration with Kubernetes](clusters/index.md). +Learn more about the [GitLab Kubernetes Agent](../clusters/agent/index.md). ## Runbooks in GitLab diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index de09cd4845e..4bbd82d01a8 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -4,9 +4,14 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Instance-level Kubernetes clusters **(FREE SELF)** +# Instance-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, +use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). Similar to [project-level](../../project/clusters/index.md) and [group-level](../../group/clusters/index.md) Kubernetes clusters, diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 5e600b6e0d1..d20e9c7a30e 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -125,8 +125,6 @@ You can also use [Kroki](https://kroki.io) to create a wide variety of diagrams. #### Mermaid -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in GitLab 10.3. - Visit the [official page](https://mermaidjs.github.io/) for more details. The [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) helps you learn Mermaid and debug issues in your Mermaid code. Use it to identify and resolve @@ -211,20 +209,20 @@ Sometimes you want to :monkey: around a bit and add some :star2: to your :speech 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 :fearful:. You can join the emoji :family:. All you need to do is to 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.emojicopy.com) for a list of all supported emoji codes. :thumbsup: ``` -Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you: +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: -<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/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/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> +<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"> -You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that. +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. -If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/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/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. All you need to do is to look up one of the supported codes. +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. -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/app/assets/images/emoji/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. <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"> #### Emojis and your operating system @@ -236,7 +234,7 @@ emojis where there is no support. <!-- vale gitlab.Spelling = NO --> -On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) +On Linux, you can download [Noto Color Emoji](https://github.com/googlefonts/noto-emoji) to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has this font installed by default. @@ -244,8 +242,6 @@ this font installed by default. ### Front matter -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) in GitLab 11.6. - Front matter is metadata included at the beginning of a Markdown document, preceding the content. This data can be used by static site generators like [Jekyll](https://jekyllrb.com/docs/front-matter/), [Hugo](https://gohugo.io/content-management/front-matter/), and many other applications. @@ -356,18 +352,18 @@ in a [code block](#code-spans-and-blocks) with the language declared as `math` i on a separate line: ````markdown -This math is inline $`a^2+b^2=c^2`$. +This math is inline: $`a^2+b^2=c^2`$. -This is on a separate line: +This math is on a separate line: ```math a^2+b^2=c^2 ``` ```` -This math is inline $`a^2+b^2=c^2`$. +This math is inline: $`a^2+b^2=c^2`$. -This is on a separate line +This math is on a separate line: ```math a^2+b^2=c^2 @@ -408,16 +404,17 @@ To create a task list, follow the format of an ordered or unordered list: ### Table of contents A table of contents is an unordered list that links to subheadings in the document. - -To add a table of contents to a Markdown file, wiki page, issue request, or merge request -description, add either the `[[_TOC_]]` or `[TOC]` tag on its own line. - -NOTE: You can add a table of contents to issues and merge requests, but you can't add one -to notes or comments. +to notes or comments. Add either the `[[_TOC_]]` or `[TOC]` tag on its own line +to the **Description** field of any of the supported content types: + +- Markdown files. +- Wiki pages. +- Issues. +- Merge requests. ```markdown -This is an intro sentence to my Wiki page. +This sentence introduces my wiki page. [[_TOC_]] @@ -579,7 +576,7 @@ by starting the lines of the blockquote with `>`: Quote break. -> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. +> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. ``` > Blockquotes help you emulate reply text. @@ -587,7 +584,7 @@ Quote break. Quote break. -> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. +> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. #### Multiline blockquote @@ -706,7 +703,7 @@ puts markdown.to_html ``` No language indicated, so no syntax highlighting. -s = "There is no highlighting for this." +s = "No highlighting is shown for this line." But let's throw in a <b>tag</b>. ``` ```` @@ -733,13 +730,13 @@ puts markdown.to_html ```plaintext No language indicated, so no syntax highlighting. -s = "There is no highlighting for this." +s = "No highlighting is shown for this line." But let's throw in a <b>tag</b>. ``` ### Emphasis -There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough, +In Markdown, you can emphasize text in multiple ways. You can italicize, bold, strikethrough, and combine these emphasis styles together. Strikethrough is not part of the core Markdown standard, but is part of GitLab Flavored Markdown. @@ -811,10 +808,6 @@ the note content. Regardless of the tag names, the relative order of the reference tags determines the rendered numbering. -Reference tags can use letters and other characters. Avoid using lowercase `w` or an underscore -(`_`) in footnote tag names until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/24423) is -resolved. - <!-- Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test. --> @@ -823,9 +816,9 @@ Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLink This reference tag is a mix of letters and numbers. [^footnote-42] -[^1]: This is the text inside a footnote. +[^1]: This text is inside a footnote. -[^footnote-42]: This is another footnote. +[^footnote-42]: This text is another footnote. </code></pre> A footnote reference tag looks like this:[^1] @@ -837,9 +830,9 @@ Do not delete the single space before the [^1] and [^footnotes] references below These are used to force the Vale ReferenceLinks check to skip these examples. --> - [^1]: This is the text inside a footnote. + [^1]: This text is inside a footnote. - [^footnote-42]: This is another footnote. + [^footnote-42]: This text is another footnote. ### Headers @@ -897,8 +890,8 @@ Would generate the following link IDs: 1. `this-header-has-spaces-in-it-2` 1. `this-header-has-3-5-in-it-and-parentheses` -Note that the emoji processing happens before the header IDs are generated, so the -emoji is converted to an image which is then removed from the ID. +Emoji processing happens before the header IDs are generated. The +emoji is converted to an image, which is then removed from the ID. ### Horizontal Rule @@ -938,7 +931,7 @@ Reference-style (hover to see title text): </code></pre> <!-- -DO NOT change the name of markdown_logo.png. This is used for a test in +DO NOT change the name of markdown_logo.png. This file is used for a test in spec/controllers/help_controller_spec.rb. --> @@ -955,7 +948,7 @@ Do not change to a reference style link.  -In the rare case where you need to set a specific height or width for an image, +In the rare case where you must set a specific height or width for an image, you can use the `img` HTML tag instead of Markdown and set its `height` and `width` parameters. @@ -1133,8 +1126,8 @@ These details <em>remain</em> <b>hidden</b> until expanded. ### Line breaks A line break is inserted (a new paragraph starts) if the previous text is -ended with two newlines, like when you hit <kbd>Enter</kbd> twice in a row. If you only -use one newline (hit <kbd>Enter</kbd> once), the next sentence remains part of the +ended with two newlines, like when you press <kbd>Enter</kbd> twice in a row. If you only +use one newline (select <kbd>Enter</kbd> once), the next sentence remains part of the same paragraph. Use this approach if you want to keep long lines from wrapping, and keep them editable: @@ -1160,7 +1153,8 @@ in the *same paragraph*. #### Newlines -GitLab Flavored Markdown adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/). +GitLab Flavored Markdown adheres to the Markdown specification for handling +[paragraphs and line breaks](https://spec.commonmark.org/current/). A paragraph is one or more consecutive lines of text, separated by one or more blank lines (two newlines at the end of the first paragraph), as [explained above](#line-breaks). @@ -1182,25 +1176,25 @@ A new line due to the previous backslash. ### Links -There are two ways to create links, inline-style and reference-style: +You can create links two ways: inline-style and reference-style. For example: <!-- Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test. --> -<pre class="highlight"><code>- This is an [inline-style link](https://www.google.com) -- This is a [link to a repository file in the same directory](index.md) -- This is a [relative link to a readme one directory higher](../index.md) -- This is a [link that also has title text](https://www.google.com "This link takes you to Google!") +<pre class="highlight"><code>- This line shows an [inline-style link](https://www.google.com) +- This line shows a [link to a repository file in the same directory](index.md) +- This line shows a [relative link to a readme one directory higher](../index.md) +- This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!") Using header ID anchors: -- This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview) -- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) +- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview) +- This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) Using references: -- This is a [reference-style link, see below][Arbitrary case-insensitive reference text] +- This line shows a [reference-style link, see below][Arbitrary case-insensitive reference text] - You can [use numbers for reference-style link definitions, see below][1] - Or leave it empty and use the [link text itself][], see below. @@ -1211,15 +1205,15 @@ Some text to show that the reference links can follow later. [link text itself]: https://www.reddit.com </code></pre> -- This is an [inline-style link](https://www.google.com) -- This is a [link to a repository file in the same directory](index.md) -- This is a [relative link to a README one directory higher](../index.md) -- This is a [link that also has title text](https://www.google.com "This link takes you to Google!") +- This line shows an [inline-style link](https://www.google.com) +- This line shows a [link to a repository file in the same directory](index.md) +- This line shows a [relative link to a README one directory higher](../index.md) +- This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!") Using header ID anchors: -- This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview) -- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) +- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview) +- This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) Using references: @@ -1228,7 +1222,7 @@ The example below uses in-line links to pass the Vale ReferenceLinks test. Do not change to reference style links. --> -- This is a [reference-style link, see below](https://www.mozilla.org/en-US/) +- This line is a [reference-style link, see below](https://www.mozilla.org/en-US/) - You can [use numbers for reference-style link definitions, see below](https://slashdot.org) - Or leave it empty and use the [link text itself](https://www.reddit.com), see below. @@ -1236,7 +1230,7 @@ Some text to show that the reference links can follow later. NOTE: Relative links do not allow the referencing of project files in a wiki -page, or a wiki page in a project file. The reason for this is that a wiki is always +page, or a wiki page in a project file. The reason: a wiki is always in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` points the link to `wikis/style` only when the link is inside of a wiki Markdown file. @@ -1265,14 +1259,14 @@ GitLab Flavored Markdown auto-links almost any URL you put into your text: <!-- vale gitlab.Spelling = YES --> ### Lists -Ordered and unordered lists can be created. +You can create ordered and unordered lists. For an ordered list, add the number you want the list to start with, like `1.`, followed by a space, at the start of each line for ordered lists. -After the first number, it does not matter what number you use, ordered lists are +After the first number, it does not matter what number you use. Ordered lists are numbered automatically by vertical order, so repeating `1.` for all items in the same list is common. If you start with a number other than `1.`, it uses that as the first -number, and count up from there. +number, and counts up from there. Examples: @@ -1364,10 +1358,9 @@ Example: --- -If the paragraph of the first item is not indented with the proper number of spaces, +If the first item's paragraph isn't indented with the proper number of spaces, the paragraph appears outside the list, instead of properly indented under the list item. - -Example: +For example: ```markdown 1. First ordered list item @@ -1459,13 +1452,13 @@ use `<br>` tags to force a cell to have multiple lines: ```markdown | Name | Details | | --- | --- | -| Item1 | This is on one line | +| Item1 | This text is on one line | | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | ``` | Name | Details | | --- | --- | -| Item1 | This is on one line | +| Item1 | This text is on one line | | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | You can use HTML formatting in GitLab itself to add [task lists](#task-lists) with checkboxes, diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 6e3af45df17..7861258e23f 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Composer packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab Premium 13.2. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -> - Support for Composer 2.0 [added](https://gitlab.com/gitlab-org/gitlab/-/issues/259840) in GitLab Free 13.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> - Support for Composer 2.0 [added](https://gitlab.com/gitlab-org/gitlab/-/issues/259840) in GitLab 13.10. WARNING: The Composer package registry for GitLab is under development and isn't ready for production use due to @@ -149,7 +149,7 @@ Do not save unless you want to overwrite the existing CI/CD file. When you publish: - The same package with different data, it overwrites the existing package. -- The same package with the same data, a `404 Bad request` error occurs. +- The same package with the same data, a `400 Bad request` error occurs. ## Install a Composer package diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 33c48478921..0f32f68d250 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Conan packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab Premium 12.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. WARNING: The Conan package registry for GitLab is under development and isn't ready for production use due to @@ -265,7 +265,8 @@ conan upload Hello/0.1@mycompany/beta --all ## Publish a Conan package by using CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in GitLab 12.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. To work with Conan commands in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index c39552c1edb..c9cdc8643f4 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -157,7 +157,7 @@ To use CI/CD to authenticate, you can use: - A [CI job token](../../../ci/jobs/ci_job_token.md). ```shell - docker login -u $CI_JOB_USER -p $CI_JOB_TOKEN $CI_REGISTRY + docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY ``` - A [deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) with the minimum scope of: @@ -309,7 +309,7 @@ in addition to the steps in the [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section: 1. Update the `image` and `service` to point to your registry. -1. Add a service [alias](../../../ci/yaml/index.md#servicesalias). +1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). Below is an example of what your `.gitlab-ci.yml` should look like: @@ -339,7 +339,7 @@ in addition to the steps in the [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section: 1. Update the `image` and `service` to point to your registry. -1. Add a service [alias](../../../ci/yaml/index.md#servicesalias). +1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). Below is an example of what your `.gitlab-ci.yml` should look like: diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 36d85d94161..89427174dcd 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -79,10 +79,10 @@ packages on the group level, create a distribution with the same `codename`. To create a project-level distribution: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=unstable" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=<codename>" ``` -Example response: +Example response with `codename=unstable`: ```json { @@ -146,10 +146,23 @@ To install a package: | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf ``` + Download your distribution key: + + ```shell + sudo mkdir -p /usr/local/share/keyrings + curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions/<codename>/key.asc" \ + | \ + gpg --dearmor \ + | \ + sudo tee /usr/local/share/keyrings/<codename>-archive-keyring.gpg \ + > /dev/null + ``` + Add your project as a source: ```shell - echo 'deb [trusted=yes] https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian <codename> <component1> <component2>' \ + echo 'deb [ signed-by=/usr/local/share/keyrings/<codename>-archive-keyring.gpg ] https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian <codename> <component1> <component2>' \ | sudo tee /etc/apt/sources.list.d/gitlab_project.list sudo apt-get update ``` diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 5d482a15460..fbd1cb84580 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -6,11 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Proxy **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to GitLab Free in GitLab 13.6. -> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab Free 13.7. -> - Anonymous access to images in public groups is no longer available starting in GitLab Free 13.7. -> - [Support for pull-by-digest and Docker version 20.x](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) in GitLab Free 13.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in GitLab 11.11. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) support for private groups in GitLab 13.7. +> - Anonymous access to images in public groups is no longer available starting in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) support for pull-by-digest and Docker version 20.x in GitLab 13.10. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -59,7 +59,7 @@ Prerequisites: ### Authenticate with the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab Free 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab 13.7. > - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. > - It's enabled on GitLab.com. > - It's recommended for production use. @@ -98,7 +98,7 @@ Proxy. #### Authenticate within CI/CD > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. -> - Automatic runner authentication [added](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27302) in GitLab 13.9. +> - Automatic runner authentication, when using the Dependency Proxy to pull the image for the job, was [added](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27302) in GitLab 13.9. > - The prefix for group names containing uppercase letters was [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54559) in GitLab 13.10. Runners log in to the Dependency Proxy automatically. To pull through @@ -134,6 +134,32 @@ Proxy manually without including the port: docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest ``` +Example when using the Dependency Proxy to build an image: + +```plaintext +# Dockerfile +FROM gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest +``` + +```yaml +# .gitlab-ci.yml +image: docker:19.03.12 + +variables: + DOCKER_HOST: tcp://docker:2375 + DOCKER_TLS_CERTDIR: "" + +services: + - docker:19.03.12-dind + +build: + image: docker:19.03.12 + before_script: + - docker login -u $CI_DEPENDENCY_PROXY_USER -p $CI_DEPENDENCY_PROXY_PASSWORD $CI_DEPENDENCY_PROXY_SERVER + script: + - docker build -t test . +``` + You can also use [custom CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) to store and access your personal access token or deploy token. ### Store a Docker image in Dependency Proxy cache @@ -189,7 +215,7 @@ If you clear the cache, the next time a pipeline runs it must pull an image or t ### Cleanup policies -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab Free 14.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab 14.4. The cleanup policy is a scheduled job you can use to clear cached images that are no longer used, freeing up additional storage space. The policies use time-to-live (TTL) logic: @@ -229,7 +255,7 @@ files are ignored and new files are downloaded and cached from the external regi ## Docker Hub rate limits and the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in GitLab Free 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in GitLab 13.7. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](https://youtu.be/Nc4nUo7Pq08). diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 6d35273ae6f..5b7316a495e 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -35,7 +35,10 @@ When you publish a package file, if the package does not exist, it is created. Prerequisites: -- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. +- You must [authenticate with the API](../../../api/index.md#authentication). + If authenticating with a deploy token, it must be configured with the `write_package_registry` + scope. If authenticating with a personal access token or project access token, it must be + configured with the `api` scope. ```plaintext PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?status=:status @@ -48,6 +51,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?sta | `package_version` | string | yes | The package version. The following regex validates this: `\A(\.?[\w\+-]+\.?)+\z`. You can test your version strings on [Rubular](https://rubular.com/r/aNCV0wG5K14uq8). | `file_name` | string | yes | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). | `status` | string | no | The package status. It can be `default` (default) or `hidden`. Hidden packages do not appear in the UI or [package API list endpoints](../../../api/packages.md). +| `select` | string | no | The response payload. By default, the response is empty. Valid values are: `package_file`. `package_file` returns details of the package file record created by this request. Provide the file context in the request body. @@ -59,7 +63,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" ``` -Example response: +Example response without attribute `select`: ```json { @@ -67,6 +71,34 @@ Example response: } ``` +Example response with attribute `select = package_file`: + +```json +{ + "id": 1, + "package_id": 1, + "created_at": "2021-10-12T12:05:23.387Z", + "updated_at": "2021-10-12T12:05:23.387Z", + "size": 0, + "file_store": 1, + "file_md5": null, + "file_sha1": null, + "file_name": "file.txt", + "file": { + "url": "/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b/packages/26/files/36/file.txt" + }, + "file_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "verification_retry_at": null, + "verified_at": null, + "verification_failure": null, + "verification_retry_count": null, + "verification_checksum": null, + "verification_state": 0, + "verification_started_at": null, + "new_file_path": null +} +``` + ### Publishing a package with the same name or version When you publish a package with the same name and version as an existing package, the new package @@ -76,7 +108,7 @@ API or the UI. #### Do not allow duplicate Generic packages -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293755) in GitLab Free 13.12. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293755) in GitLab 13.12. To prevent users from publishing duplicate generic packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index f17910cd46d..1cf3132489a 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -6,11 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Go proxy for GitLab **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab Premium 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab 13.1. > - It's deployed behind a feature flag, disabled by default. > - It's disabled for GitLab.com. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. WARNING: The Go package registry for GitLab is under development and isn't ready for production use due to diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index a8f1b1998ae..86cfa8986bb 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -10,56 +10,6 @@ The GitLab [Package Registry](package_registry/index.md) acts as a private or pu for a variety of common package managers. You can publish and share packages, which can be easily consumed as a dependency in downstream projects. -WARNING: -Not all package manager formats are ready for production use. To view each format's status, see the -table's **Status** column. - -The Package Registry supports the following formats: - -| Package type | GitLab version | Status | -| ------------ | -------------- |------- | -| [Maven](maven_repository/index.md) | 11.3+ | Stable | -| [npm](npm_registry/index.md) | 11.7+ | Stable | -| [NuGet](nuget_repository/index.md) | 12.8+ | Stable | -| [PyPI](pypi_repository/index.md) | 12.10+ | Stable | -| [Generic packages](generic_packages/index.md) | 13.5+ | Stable | -| [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) | - -Status: - -- Alpha: behind a feature flag and not officially supported. -- Beta: several known issues that may prevent expected use. -- Stable: ready for production use. - -You can also use the [API](../../api/packages.md) to administer the Package Registry. - -## Accepting contributions - -The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) -guides you through the process. - -<!-- vale gitlab.Spelling = NO --> - -| Format | Status | -| ------ | ------ | -| Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | -| CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | -| Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | -| CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | -| Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | -| P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | -| Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | -| RPM | [#5932](https://gitlab.com/groups/gitlab-org/-/epics/5128) | -| SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | -| Swift | [#12233](https://gitlab.com/gitlab-org/gitlab/-/issues/12233) | -| Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | - -<!-- vale gitlab.Spelling = YES --> ## Container Registry The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index 86b85d0c9f5..47f563fd7e7 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -82,7 +82,7 @@ The Infrastructure Registry is automatically enabled. For self-managed instances, a GitLab administrator can [disable](../../../administration/packages/index.md) **Packages & Registries**, -which removes this menu item from the sidebar. **(FREE SELF)** +which removes this menu item from the sidebar. You can also remove the Infrastructure Registry for a specific project: diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 17571047353..1ca4bb2759d 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Maven packages in the Package Repository **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab Premium 11.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab 11.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -222,8 +222,8 @@ The `name` must be `Private-Token`. ### Authenticate with a deploy token in Maven -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in GitLab 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. To use a deploy token, add this section to your [`settings.xml`](https://maven.apache.org/settings.html) file. @@ -418,8 +418,8 @@ repositories { ### Group-level Maven endpoint -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in GitLab 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the group-level endpoint for @@ -476,8 +476,8 @@ repositories { ### Instance-level Maven endpoint -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in GitLab 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the instance-level endpoint for @@ -619,7 +619,7 @@ To delete these older package versions, consider using the Packages API or the U #### Do not allow duplicate Maven packages -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296895) in GitLab Free 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296895) in GitLab 13.9. To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index b07ae72e273..03209da7ac8 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # npm packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in GitLab Premium 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in GitLab 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. Publish npm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -164,8 +164,8 @@ If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view ### Authenticate with a CI job token -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab 12.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. If you're using npm with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. @@ -208,6 +208,15 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD. - **GitLab CI/CD:** Set an `NPM_TOKEN` [CI/CD variable](../../../ci/variables/index.md) under your project's **Settings > CI/CD > Variables**. +## Working with private registries + +When working with private repositories, you may want to configure additional settings to ensure a secure communication channel: + +```shell +# Force npm to always require authentication when accessing the registry, even for GET requests. +npm config set always-auth true +``` + ## Package naming convention When you use the [instance-level endpoint](#use-the-gitlab-endpoint-for-npm-packages), only the packages with names in the format of `@scope/package-name` are available. @@ -363,6 +372,10 @@ This rule has a different impact depending on the package name: This aligns with npmjs.org's behavior. However, npmjs.org does not ever let you publish the same version more than once, even if it has been deleted. +## `package.json` limitations + +You can't publish a package if its `package.json` file exceeds 20,000 characters. + ## Install a package npm packages are commonly-installed by using the `npm` or `yarn` commands @@ -427,27 +440,34 @@ and use your organization's URL. The name is case-sensitive and must match the n //gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" ``` -### npm dependencies metadata - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. - -In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the npm client: - -- name -- version -- dist-tags -- dependencies - - dependencies - - devDependencies - - bundleDependencies - - peerDependencies - - deprecated +### npm metadata + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/330929) in GitLab 14.5. + +The GitLab Package Registry exposes the following attributes to the npm client. +These are similar to the [abbreviated metadata format](https://github.com/npm/registry/blob/9e368cf6aaca608da5b2c378c0d53f475298b916/docs/responses/package-metadata.md#abbreviated-metadata-format): + +- `name` +- `versions` + - `name` + - `version` + - `deprecated` + - `dependencies` + - `devDependencies` + - `bundleDependencies` + - `peerDependencies` + - `bin` + - `directories` + - `dist` + - `engines` + - `_hasShrinkwrap` ## Add npm distribution tags -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag/) to newly-published packages. Tags are optional and can be assigned to only one package at a time. @@ -549,6 +569,8 @@ NPM_TOKEN=<your_token> npm install If you get this error, ensure that: +- The Package Registry is enabled in your project settings. Although the Package Registry is enabled + by default, it's possible to [disable it](../package_registry/#disable-the-package-registry). - Your token is not expired and has appropriate permissions. - A package with the same name or version doesn't already exist within the given scope. - Your NPM package name does not contain a dot `.`. This is a [known issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/10248) @@ -577,6 +599,10 @@ root namespace and therefore cannot be published again using the same name. This is also true even if the prior published package shares the same name, but not the version. +#### Package JSON file is too large + +Make sure that your `package.json` file does not [exceed `20,000` characters](#packagejson-limitations). + ### `npm publish` returns `npm ERR! 500 Internal Server Error - PUT` This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 2af6dc60078..98cccd72425 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # NuGet packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab Premium 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. > - Symbol package support [added](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) in GitLab 14.1. Publish NuGet packages in your project's Package Registry. Then, install the diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index cb4e677687e..3204ac07d6a 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -6,11 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Package Registry **(FREE)** -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. -With the GitLab Package Registry, you can use GitLab as a private or public registry -for a variety of common package managers. You can publish and share -packages, which can be easily consumed as a dependency in downstream projects. +With the GitLab Package Registry, you can use GitLab as a private or public registry for a variety +of [supported package managers](#supported-package-managers). +You can publish and share packages, which can be consumed as a dependency in downstream projects. ## View packages @@ -48,8 +48,8 @@ Learn more about using the GitLab Package Registry with CI/CD: - [Maven](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) - [npm](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) - [NuGet](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) -- [PyPI](../pypi_repository/#authenticate-with-a-ci-job-token) -- [RubyGems](../rubygems_registry/#authenticate-with-a-ci-job-token) +- [PyPI](../pypi_repository/index.md#authenticate-with-a-ci-job-token) +- [RubyGems](../rubygems_registry/index.md#authenticate-with-a-ci-job-token) If you use CI/CD to build a package, extended activity information is displayed when you view the package details: @@ -124,3 +124,57 @@ Learn how to use the GitLab Package Registry to build your own custom package wo to publish all of your packages to one project. - Publish multiple different packages from one [monorepo project](../workflows/working_with_monorepos.md). + +## Supported package managers + +WARNING: +Not all package manager formats are ready for production use. To view each format's status, see the +table's **Status** column. + +The Package Registry supports the following formats: + +| 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) | + +[Status](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga): + +- 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. + +You can also use the [API](../../../api/packages.md) to administer the Package Registry. + +## Accepting contributions + +This table lists unsupported package manager formats that we are accepting contributions for. +Consider contributing to GitLab. This [development documentation](../../../development/packages.md) +guides you through the process. + +<!-- vale gitlab.Spelling = NO --> + +| Format | Status | +| ------ | ------ | +| Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | +| CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | +| Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | +| CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | +| Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | +| P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | +| Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | +| RPM | [#5932](https://gitlab.com/groups/gitlab-org/-/epics/5128) | +| SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | +| Swift | [#12233](https://gitlab.com/gitlab-org/gitlab/-/issues/12233) | +| Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 2d54cfc5f7d..4151346ec98 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # PyPI packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab Premium 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. Publish PyPI packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index e31bd8bd0bf..05113d0bc10 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Ruby gems in the Package Registry **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in [GitLab Free](https://about.gitlab.com/pricing/) 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in GitLab 13.10. WARNING: The Ruby gems package registry for GitLab is under development and isn't ready for production use due to diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md index 4e431b036de..ab10e746302 100644 --- a/doc/user/packages/workflows/working_with_monorepos.md +++ b/doc/user/packages/workflows/working_with_monorepos.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Monorepo package management workflows +# Monorepo package management workflows **(FREE)** One project or Git repository can contain multiple different subprojects or submodules that are all packaged and published individually. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 10147e7f69c..eb79d5099eb 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -33,8 +33,13 @@ usernames. A GitLab administrator can configure the GitLab instance to ## Project members permissions -The Owner role is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. -While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, or an instance administrator, who receives all permissions. +A user's role determines what permissions they have on a project. The Owner role provides all permissions but is +available only: + +- For group owners. The role is inherited for a group's projects. +- For Administrators. + +Personal namespace owners have the same permissions as an Owner, but are displayed with the Maintainer role on projects created in their personal namespace. For more information, see [projects members documentation](project/members/index.md). The following table lists project permissions available for each role: @@ -70,7 +75,7 @@ The following table lists project permissions available for each role: | [CI/CD](../ci/index.md):<br>Manage job triggers | | | | ✓ | ✓ | | [CI/CD](../ci/index.md):<br>Manage runners | | | | ✓ | ✓ | | [CI/CD](../ci/index.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals) | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | ✓ | ✓ | | [CI/CD](../ci/index.md):<br>Delete pipelines | | | | | ✓ | | [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | | [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | @@ -81,6 +86,15 @@ The following table lists project permissions available for each role: | [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓| ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓| ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*17*) | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓| ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md)| | | | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Add Labels | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Assign | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -140,7 +154,7 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (14) | ✓ | | [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | @@ -169,7 +183,7 @@ The following table lists project permissions available for each role: | [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to protected branches | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches (*5*) | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | | [Repository](project/repository/index.md):<br>Force push to protected branches (*4*) | | | | | | @@ -202,7 +216,7 @@ The following table lists project permissions available for each role: 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. 1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 1. If the [branch is protected](project/protected_branches.md), this depends on the access Developers and Maintainers are given. -1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits. +1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see [repository information like commits and release evidence](project/releases/index.md#view-a-release-and-download-assets). 1. Actions are limited only to records owned (referenced) by user. 1. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) is enabled the project can't be shared with other groups. It does not affect group with group sharing. 1. For information on eligible approvers for merge requests, see @@ -216,7 +230,9 @@ The following table lists project permissions available for each role: [project visibility](../public_access/public_access.md) is set to private. 1. Attached design files are moved together with the issue even if the user doesn't have the Developer role. -1. Guest users can set metadata (for example, labels, assignees, or milestones) when creating an issue. +1. Guest users can only set metadata (for example, labels, assignees, or milestones) + when creating an issue. They cannot change the metadata on existing issues. +1. In GitLab 14.5 or later, Guests are not allowed to [create incidents](../operations/incident_management/incidents.md#incident-creation). ## Project features permissions @@ -305,7 +321,7 @@ The following table lists group permissions available for each role: | Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Create subgroup | | | | ✓ (1) | ✓ | -| Delete group wiki pages **(PREMIUM)** | | | | ✓ | ✓ | +| Delete group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Edit epic comments (posted by any user) **(ULTIMATE)** | | | | ✓ (2) | ✓ (2) | | List group deploy tokens | | | | ✓ | ✓ | | Manage [group push rules](group/index.md#group-push-rules) **(PREMIUM)** | | | | ✓ | ✓ | @@ -384,8 +400,10 @@ An administrator can flag a user as external by either of the following methods: 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. There, you can find the option to flag the user as external. -Additionally users can be set as external users using [SAML groups](../integration/saml.md#external-groups) -and [LDAP groups](../administration/auth/ldap/index.md#external-groups). +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). ### Setting new users to external @@ -416,7 +434,7 @@ Be aware that this regex could lead to a ## Free Guest users **(ULTIMATE)** -When a user is given Guest permissions on a project, group, or both, and holds no +When a user is given the Guest role on a project, group, or both, and holds no higher permission level on any other project or group on the GitLab instance, the user is considered a guest user by GitLab and does not consume a license seat. There is no other specific "guest" designation for newly created users. @@ -466,22 +484,20 @@ subscriptions. Project features like wiki and issues can be hidden from users depending on which visibility level you select on project settings. -- Disabled: disabled for everyone -- Only team members: only team members will see even if your project is public or internal -- Everyone with access: everyone can see depending on your project visibility level -- Everyone: enabled for everyone (only available for GitLab Pages) +- Disabled: disabled for everyone. +- Only team members: only team members can see, even if your project is public or internal. +- Everyone with access: everyone can see depending on your project visibility level. +- Everyone: enabled for everyone (only available for GitLab Pages). ## GitLab CI/CD permissions -GitLab CI/CD permissions rely on the role the user has in GitLab. There are four -roles: +GitLab CI/CD permissions rely on the role the user has in GitLab: -- Administrator - Maintainer - Developer - Guest/Reporter -The Administrator role can perform any action on GitLab CI/CD in scope of the GitLab +GitLab administrators can perform any action on GitLab CI/CD in scope of the GitLab instance and project. | Action | Guest, Reporter | Developer |Maintainer| Administrator | diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 6fe4b457fac..e4e7e7b9c1a 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -61,7 +61,7 @@ To enable 2FA: - [Authenticator](https://mattrubin.me/authenticator/) - [andOTP](https://github.com/andOTP/andOTP) - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en) - - [Microsoft Authenticator](https://www.microsoft.com/en-us/account/authenticator) + - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app) - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp) 1. In the application, add a new entry in one of two ways: - Scan the code presented in GitLab with your device's camera to add the @@ -238,6 +238,9 @@ GitLab officially only supports [YubiKey](https://www.yubico.com/products/) U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/) or [Google Titan Security Key](https://cloud.google.com/titan-security-key). +NOTE: +2FA must be configured before U2F. + The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers: diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 7f16c4e244e..d9f10b58c3f 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -49,7 +49,7 @@ Prerequisites: - Your namespace cannot contain a project with [Container Registry](../packages/container_registry/index.md) tags. - Your namespace cannot have a project that hosts [GitLab Pages](../project/pages/index.md). For more information, - see [this procedure in the GitLab Team Handbook](https://about.gitlab.com/handbook/tools-and-tips/#how-to-change-your-username-at-gitlabcom). + see [this procedure in the GitLab Team Handbook](https://about.gitlab.com/handbook/tools-and-tips/#change-your-username-at-gitlabcom). To change your username: @@ -100,6 +100,18 @@ When visiting the public page of a user, you can only see the projects which you If the [public level is restricted](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels), user profiles are only visible to signed-in users. +## User profile README + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232157) in GitLab 14.5. + +You can add a README section to your profile that can include more information and [formatting](../markdown.md) than +your profile's bio. + +To add a README to your profile: + +1. Create a new public project with the same name as your GitLab username. +1. Create a README file inside this project. The file can be any valid [README or index file](../project/repository/index.md#readme-and-index-files). + ## Add external accounts to your user profile page You can add links to certain other external accounts you might have, like Skype and Twitter. @@ -117,7 +129,7 @@ To add links to other accounts: ## Show private contributions on your user profile page -In the user contribution calendar graph and recent activity list, you can see your [contribution actions](../../api/events.md#action-types) to private projects. +In the user contribution calendar graph and recent activity list, you can see your [contribution actions](../index.md#user-contribution-events) to private projects. To show private contributions: @@ -219,6 +231,12 @@ To set the busy status indicator, either: ## Set your time zone +You can set your local time zone to: + +- Display your local time on your profile, and in places where hovering over your name shows information about you. +- Align your contribution calendar with your local time to better reflect when your contributions were made + ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335343) in GitLab 14.5). + To set your time zone: 1. On the top bar, in the top-right corner, select your avatar. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 6de09f5538f..9faa4b78f8c 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -24,6 +24,7 @@ You might receive notifications for one of the following reasons: or edit, or someone mentions you. - You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). - You've configured notifications for the [project](#change-level-of-project-notifications) or [group](#group-notifications). +- You're subscribed to group or project pipeline notifications via the pipeline emails [integration](../project/integrations/overview.md). NOTE: Administrators can block notifications, preventing them from being sent. @@ -353,3 +354,19 @@ For example, an alert notification email can have one of Expanding the list of events included in the `X-GitLab-NotificationReason` header is tracked in [issue 20689](https://gitlab.com/gitlab-org/gitlab/-/issues/20689). + +## Troubleshooting + +### Pull a list of recipients for notifications + +If you want to pull a list of recipients to receive notifications from a project +(mainly used for troubleshooting custom notifications), +in a Rails console, run `sudo gitlab-rails c` and be sure to update the project name: + +```plaintext +project = Project.find_by_full_path '<project_name>' +merge_request = project.merge_requests.find_by(iid: 1) +current_user = User.first +recipients = NotificationRecipients::BuildService.build_recipients(merge_request, current_user, action: "push_to"); recipients.count +recipients.each { |notify| puts notify.user.username } +``` diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index bdd49b00a15..197ba4647b2 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -62,6 +62,10 @@ to the URL. For example: https://gitlab.example.com/-/profile/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry ``` +WARNING: +Personal access tokens must be treated carefully. Read our [token security considerations](../../security/token_overview.md#security-considerations) +for guidance on managing personal access tokens (for example, setting a short expiry and using minimal scopes). + ## Revoke a personal access token At any time, you can revoke a personal access token. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index d54edc7e6d3..9ca11d43864 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -56,11 +56,18 @@ To add this badge to a project: ## Group badges -Badges can be added to a group and are visible on every project's -overview page that's under that group. In this case, they cannot be edited or -deleted on the project level. If you need to have individual badges for each -project, consider adding them on the [project level](#project-badges) or use -[placeholders](#placeholders). +By adding a badge to a group, you add and enforce a project-level badge +for all projects in the group. The group badge is visible on the **Overview** +page of any project that belongs to the group. + +NOTE: +While these badges appear as project-level badges in the codebase, they +cannot be edited or deleted at the project level. + +If you need individual badges for each project, either: + +- Add the badge at the [project level](#project-badges). +- Use [placeholders](#placeholders). To add a new badge to a group: diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 6d1fb0f6755..77cf04cc7eb 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -69,10 +69,14 @@ can easily notice them.  -### Advanced traffic control with Canary Ingress +### Advanced traffic control with Canary Ingress (DEPRECATED) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Free in GitLab 13.8. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), which is an advanced traffic routing service that controls incoming HTTP diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 0db0f14b633..e03e5b10236 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,12 +4,13 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Connect EKS clusters through cluster certificates **(FREE)** +# Connect EKS clusters through cluster certificates (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -Use [Infrastrucure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +This feature was deprecated in GitLab 14.5. Use [Infrastrucure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) to create new clusters. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic @@ -20,18 +21,10 @@ Kubernetes Service (EKS). If you already have an EKS cluster and want to connect it to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). -Alternatively, you can [connect them with cluster certificates](add_existing_cluster.md), -although this method is not recommended for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - ## Create a new EKS cluster To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). -Alternatively, you can [create new EKS clusters using cluster certificates](#how-to-create-a-new-cluster-on-eks-through-cluster-certificates-deprecated). -Although still available on the GitLab UI, this method was deprecated -in GitLab 14.0 and is scheduled for removal in GitLab 15.0. -It also has [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - ### How to create a new cluster on EKS through cluster certificates (DEPRECATED) > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 3347ef9a437..fcf2583d3ab 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,16 +4,17 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Connect existing clusters through cluster certificates +# Connect existing clusters through cluster certificates **(DEPRECATED)** -If you have an existing Kubernetes cluster, you can add it to a project, group, -or instance and benefit from the integration with GitLab. +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -The process described on this page uses cluster certificates to connect your cluster -to GitLab. Although this method still works, it is **no longer recommended**. -To connect your cluster to GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) -instead. **(PREMIUM)** +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +instead. + +If you have an existing Kubernetes cluster, you can add it to a project, group, +or instance and benefit from the integration with GitLab. ## Prerequisites diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 0d35e89a560..30be319f2df 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,9 +4,12 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Connect GKE clusters through cluster certificates **(FREE)** +# Connect GKE clusters through cluster certificates (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. Use [Infrastrucure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md) to create a cluster hosted on Google Kubernetes Engine (GKE). @@ -18,21 +21,13 @@ hosted on Google Kubernetes Engine (GKE). If you already have a GKE cluster and want to connect it to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). -Alternatively, you can [connect them with cluster certificates](add_existing_cluster.md), -altough this method is not recommended for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - ## Create a new GKE cluster from GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25925) in GitLab 12.4, all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). To create a new GKE cluster from GitLab, use [Infrastructure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md). -Alternatively, you can [create new GKE clusters using cluster certificates](#create-a-new-cluster-on-gke-through-cluster-certificates-deprecated). -Although still available in the GitLab UI, this method was deprecated -in GitLab 14.0 and is scheduled for removal in GitLab 15.0. -It also has [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - -## Create a new cluster on GKE through cluster certificates (DEPRECATED) +## Create a new cluster on GKE through cluster certificates > [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 4f2bc5526e0..49708e3b6aa 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -9,9 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Creating a new cluster through cluster certificates -is deprecated and no longer recommended. To create a new cluster use -[Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. +To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). NOTE: Every new Google Cloud Platform (GCP) account receives diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 452f5727620..510aad821cf 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -4,9 +4,15 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster access controls (RBAC or ABAC) +# Access controls with cluster certificates (RBAC or ABAC) (DEPRECATED) **(FREE)** -> Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. +> - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +instead. When creating a cluster in GitLab, you are asked if you would like to create either: diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 54141fe1103..c3a71ec8585 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -4,13 +4,14 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy to a Kubernetes cluster with cluster certificates +# Deploy to a Kubernetes cluster with cluster certificates (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -The process described on this page uses cluster certificates to deploy to your cluster -from GitLab. Although this method still works, it is **no longer recommended**. -To deploy to your cluster from GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) -instead. **(PREMIUM)** +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +To deploy with the Agent, use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md). A Kubernetes cluster can be the destination for a deployment job. If @@ -77,7 +78,7 @@ You can customize the deployment namespace in a few ways: - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, but the user is responsible for ensuring its existence. You can fully customize this value using - [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments) + [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments-deprecated) in `.gitlab-ci.yml`. When you customize the namespace, existing environments remain linked to their current @@ -100,7 +101,7 @@ combined with *one* of the following: > Introduced in GitLab 8.15. -The Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) +The Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals-deprecated) support to your [environments](../../../ci/environments/index.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new shell session in your existing containers. To use this integration, you diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 77921ec1dff..ad378be2d9a 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -4,10 +4,16 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab-managed clusters +# GitLab-managed clusters (DEPRECATED) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../../user/clusters/agent/index.md). +To manage applications, use the [Cluster Project Management Template](../../../user/clusters/management_project_template.md). You can choose to allow GitLab to manage your cluster for you. If your cluster is managed by GitLab, resources for your projects are automatically created. See diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index ac59f874244..c16c6446acd 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,19 +4,22 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project-level Kubernetes clusters **(FREE)** +# Project-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -[Project-level Kubernetes clusters](../../infrastructure/clusters/connect/index.md#cluster-levels) +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) +in GitLab 14.5. To connect clusters to GitLab, use the +[GitLab Kubernetes Agent](../../clusters/agent/index.md). + +[Project-level](../../infrastructure/clusters/connect/index.md#cluster-levels-deprecated) Kubernetes clusters allow you to connect a Kubernetes cluster to a project in GitLab. You can also [connect multiple clusters](multiple_kubernetes_clusters.md) to a single project. -After connecting a cluster to GitLab, you can benefit from the large number of -[GitLab features available for Kubernetes clusters](../../infrastructure/clusters/index.md) to manage and deploy to your cluster. - ## View your project-level clusters To view project-level Kubernetes clusters: diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index eb0e8d0e91c..19166a1ff8c 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -4,10 +4,14 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Kubernetes Logs **(FREE)** +# Kubernetes Logs (DEPRECATED) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Free](https://about.gitlab.com/pricing/) 12.9. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index e2eae011b8c..540907bf915 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -4,10 +4,16 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Multiple Kubernetes clusters for a single project +# Multiple clusters per project with cluster certificates (DEPRECATED) **(FREE)** > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +Using multiple Kubernetes clusters for a single project **with cluster +certificates** was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +To connect clusters to GitLab, use the [GitLab Kubernetes Agent](../../../user/clusters/agent/index.md). You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index 5e4df6009f0..c005ce64bb5 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -6,6 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Host Security **(FREE)** +NOTE: +In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). +You can continue using Container Host Security, even though it relies on this certificate-based +method. The work to allow all aspects of Container Host Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350). + Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can monitor and (optionally) block activity inside the containers themselves. This is done by leveraging an integration with Falco to provide the monitoring capabilities and an integration with Pod diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index 3daa48e1811..eb15675da19 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -6,6 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Network Security **(FREE)** +NOTE: +In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). +You can continue using Container Network Security, even though it relies on this certificate-based +method. The work to allow all aspects of Container Network Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350) and [this GitLab Epic](https://gitlab.com/groups/gitlab-org/-/epics/7057). + Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods inside the cluster. Container Network Security can be used to enforce L3, L4, and L7 policies and diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 6eafb4530d3..06fa18d80c9 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -434,11 +434,11 @@ To test the application you deployed, please go to the build log and follow the 1. Click on "Show complete raw" on the upper right-hand corner: -  +  1. Look for HelloWorldApi – API Gateway endpoint similar to shown below: -  +  1. Use curl to test the API. For example: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 7d51fb59793..c138dc64d19 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -84,6 +84,10 @@ so that their members also become eligible Code Owners. If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval of the merge request becomes optional. +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. + ### Add a group as a Code Owner To set a group as a Code Owner: diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 6e2635b89f0..15490ab0b94 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy boards **(FREE)** +# Deploy boards (DEPRECATED) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. @@ -15,6 +15,12 @@ type: howto, reference > - In GitLab 13.11 and earlier, environments in folders do not show deploy boards. > This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in > GitLab 13.12. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. +[An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/2493) +to add this functionality to the [Agent](../index.md). GitLab deploy boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 61dccf1cb1b..c5950347ae9 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -81,10 +81,11 @@ help you access a repository, but there are some notables differences between th [Project maintainers and owners](../../permissions.md#project-members-permissions) can add or enable a deploy key for a project repository: -1. Navigate to the project's **Settings > Repository** page. -1. Expand the **Deploy keys** section. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy keys**. 1. Specify a title for the new deploy key and paste your public SSH key. -1. (Optional) Check **Grant write permissions to this key** to allow `read-write` access. Leave it unchecked for `read-only` access. +1. Optional. To allow `read-write` access, select the **Grant write permissions to this key** checkbox. Leave it unchecked for `read-only` access. There are three lists of project deploy keys: @@ -164,9 +165,10 @@ configuration. [Project maintainers and owners](../../permissions.md#project-members-permissions) can remove or disable a deploy key for a project repository: -1. Navigate to the project's **Settings > Repository** page. -1. Expand the **Deploy keys** section. -1. Select the **{remove}** or **{cancel}** button. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy keys**. +1. Select **Disable** (**{cancel}**). NOTE: Any service that relies on a deploy key stops working after that key is removed. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 483de3b21bd..c840f6c8698 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -29,14 +29,15 @@ You can create as many deploy tokens as you need from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). 1. Sign in to your GitLab account. -1. Go to the project (or group) you want to create deploy tokens for. -1. Go to **Settings > Repository**. -1. Expand the **Deploy tokens** section. -1. Choose a name, expiry date (optional), and username (optional) for the token. +1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy tokens**. +1. Choose a name, and optionally, an expiration date and username for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Select **Create deploy token**. -1. Save the deploy token somewhere safe. After you leave or refresh - the page, **you can't access it again**. + +Save the deploy token somewhere safe. After you leave or refresh +the page, **you can't access it again**.  @@ -46,8 +47,12 @@ Deploy tokens expire at midnight UTC on the date you define. ## Revoking a deploy token -To revoke a deploy token, under the **Active deploy tokens** area, -select the respective **Revoke** button. +To revoke a deploy token: + +1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy tokens**. +1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. ## Limiting scopes of a deploy token diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index db8c6f24063..10dcbddac17 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -212,20 +212,21 @@ requests that modify locked files. Unlock the file to allow changes. To lock a file: 1. Open the file or directory in GitLab. -1. Click the **Lock** button, located near the Web IDE button. +1. On the top right, above the file, select **Lock**. +1. On the confirmation dialog box, select **OK**. -  +If you do not have permission to lock the file, the button is not enabled. -An **Unlock** button is displayed if the file is already locked, and -is disabled if you do not have permission to unlock the file. - -If you did not lock the file, hovering your cursor over the button shows -who locked the file. +To view the user who locked the file (if it was not you), hover over the button. ### View and remove existing locks -The **Locked Files**, accessed from **Project > Repository** left menu, lists -all file and directory locks. Locks can be removed by their author, or any user -with the [Maintainer role](../permissions.md) and above. +To view and remove file locks: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Locked Files**. This list shows all the files locked either through LFS or GitLab UI. + +Locks can be removed by their author, or any user +with at least the [Maintainer role](../permissions.md). diff --git a/doc/user/project/img/file_lock.png b/doc/user/project/img/file_lock.png Binary files differdeleted file mode 100644 index e881442630b..00000000000 --- a/doc/user/project/img/file_lock.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index cda018a0c37..0c50fc77e33 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -52,20 +52,18 @@ namespace that started the import process. ## Import your Bitbucket repositories -1. Sign in to GitLab and go to your dashboard. -1. Click on **New project**. - -1. Click on the "Bitbucket Cloud" button. - -  - -1. Grant GitLab access to your Bitbucket account +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **Bitbucket Cloud**. +1. Log in to Bitbucket and grant GitLab access to your Bitbucket account.  -1. Click on the projects that you'd like to import or **Import all projects**. - You can also filter projects by name and select the namespace under which - each project will be imported. +1. Select the projects that you'd like to import or import all projects. + You can filter projects by name and select the namespace + each project will be imported for.  diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 2715804b37a..81e7d159a06 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -78,10 +78,7 @@ the author's: - `slug` - `displayName` -If the user is not found by any of these properties, the search falls back to the author's -`email` address. - -Alternatively, if there is also no email address, the project creator is set as the author. +If the user is not found by any of these properties, the project creator is set as the author. ##### Enable or disable User assignment by username @@ -104,22 +101,27 @@ Feature.disable(:bitbucket_server_user_mapping_by_username) ## Import your Bitbucket repositories -1. Sign in to GitLab and go to your dashboard. -1. Click on **New project**. -1. Click on the "Bitbucket Server" button. If the button is not present, enable the importer in - **Admin > Application Settings > Visibility and access controls > Import sources**. +Prerequisite: -  +- An administrator must have enabled the importer in + **Admin > Application Settings > Visibility and access controls > Import sources**. -1. Enter your Bitbucket Server credentials. +To import your Bitbucket repositories: -  +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **Bitbucket Server**. +1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. +1. Select the projects that you'd like to import or import all projects. + You can filter projects by name and select the namespace + each project will be imported for. -1. Click on the projects that you'd like to import or **Import all projects**. - You can also filter projects by name and select the namespace under which each project is - imported. +## Automate group and project import **(PREMIUM)** -  +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). ## Troubleshooting diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 982bc6d90e8..3458c7fe4a7 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -16,15 +16,16 @@ users. To import your project from FogBugz: -1. From your GitLab dashboard, select **New project**. -1. Select the **FogBugz** button. -  +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **FogBugz**. 1. Enter your FogBugz URL, email address, and password. -  1. Create a mapping from FogBugz users to GitLab users.  -1. Select **Import** for the projects you want to import. +1. For the projects you want to import, select **Import**.  -1. After the import finishes, click the link to go to the project +1. After the import finishes, select the link to go to the project dashboard. Follow the directions to push your existing repository.  diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 3bbc70b4337..db55330f806 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -38,8 +38,6 @@ that started the import process. The importer page is visible when you create a new project. - - Select the **Gitea** link to start the import authorization process.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index eff733b0b3d..e1a81ae1bba 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -25,6 +25,7 @@ The following aspects of a project are imported: - Pull request "merged by" information (GitLab.com & 13.7+) - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) +- Pull request comments replies in discussions ([GitLab.com & 14.5+](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)) References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility @@ -67,7 +68,7 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) that matches their GitLab account's email address. NOTE: @@ -240,3 +241,8 @@ To disable the feature, run this command: # Disable Feature.disable(:github_importer_lower_per_page_limit, group) ``` + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index f25b29317a7..bcbc6e09f1b 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -26,3 +26,8 @@ for permission to access your projects. After accepting, you are automatically r To import a project, click "Import". The importer imports your repository and issues. Once the importer is done, a new GitLab project is created with your imported data. + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/img/bitbucket_server_import_credentials.png b/doc/user/project/import/img/bitbucket_server_import_credentials.png Binary files differdeleted file mode 100644 index 25bcc3ab6e6..00000000000 --- a/doc/user/project/import/img/bitbucket_server_import_credentials.png +++ /dev/null diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png Binary files differdeleted file mode 100644 index 3f94dd83dd6..00000000000 --- a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png +++ /dev/null diff --git a/doc/user/project/import/img/fogbugz_import_login.png b/doc/user/project/import/img/fogbugz_import_login.png Binary files differdeleted file mode 100644 index 6ba4d443f1a..00000000000 --- a/doc/user/project/import/img/fogbugz_import_login.png +++ /dev/null diff --git a/doc/user/project/import/img/fogbugz_import_select_fogbogz.png b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png Binary files differdeleted file mode 100644 index d207646a6f2..00000000000 --- a/doc/user/project/import/img/fogbugz_import_select_fogbogz.png +++ /dev/null diff --git a/doc/user/project/import/img/import_projects_from_new_project_page.png b/doc/user/project/import/img/import_projects_from_new_project_page.png Binary files differdeleted file mode 100644 index 7c32d3555d1..00000000000 --- a/doc/user/project/import/img/import_projects_from_new_project_page.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 887eb546148..6e02a9bf5ab 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -102,3 +102,18 @@ After an administrator creates an alias for a project, you can use the alias to repository. For example, if an administrator creates the alias `gitlab` for the project `https://gitlab.com/gitlab-org/gitlab`, you can clone the project with `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`. + +## Automate group and project import **(PREMIUM)** + +The GitLab Professional Services team uses [Congregate](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate) +to orchestrate user, group, and project import API calls. With Congregate, you can migrate data to +GitLab from: + +- Other GitLab instances +- GitHub Enterprise +- GitHub.com +- Bitbucket Server +- Bitbucket Data Center + +See the [Quick Start Guide](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start) +to learn how to use this approach for migrating users, groups, and projects at scale. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index f3843396b79..aa256e07b30 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -61,3 +61,7 @@ creating small and efficient Git pack files. So it might be a good idea to spend time and CPU to properly repack your repository before sending it for the first time to your GitLab server. See [this StackOverflow question](https://stackoverflow.com/questions/28720151/git-gc-aggressive-vs-git-repack/). + +## Related topics + +- [Mirror with Perforce Helix with Git Fusion](../repository/mirror/bidirectional.md#mirror-with-perforce-helix-with-git-fusion) diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index e504f3678a7..0b96238006e 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -23,3 +23,8 @@ You can import your existing repositories by providing the Git URL: <!-- vale gitlab.SubstitutionWarning = YES -->  + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index f3173736e9b..78cd2f8fb79 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -47,7 +47,7 @@ Projects include the following [features](https://about.gitlab.com/features/): strategy and get reviewed by your team. - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before implementing a change. - - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): View Git diffs from the GitLab UI. + - [Fix merge conflicts from the UI](merge_requests/conflicts.md): View Git diffs from the GitLab UI. - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results of the changes proposed in a merge request. - [Labels](labels.md): Organize issues and merge requests by labels. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index eaab1933b79..d155f91e40b 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,31 +4,40 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Custom issue tracker service **(FREE)** +# Custom issue tracker **(FREE)** -Use a custom issue tracker that is not in the integration list. +You can integrate an [external issue tracker](../../../integration/external-issue-tracker.md) +with GitLab. If your preferred issue tracker is not listed in the +[integrations list](../../../integration/external-issue-tracker.md#integration), +you can enable a custom issue tracker. + +After you enable the custom issue tracker, a link to the issue tracker displays +on the left sidebar in your project. + + + +## Enable a custom issue tracker To enable a custom issue tracker in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: - **Project URL**: The URL to view all the issues in the custom issue tracker. - **Issue URL**: The URL to view an issue in the custom issue tracker. The URL must contain `:id`. - GitLab replaces `:id` with the issue number (for example, - `https://customissuetracker.com/project-name/:id`, which becomes `https://customissuetracker.com/project-name/123`). + GitLab replaces `:id` with the issue number (for example, + `https://customissuetracker.com/project-name/:id`, which becomes + `https://customissuetracker.com/project-name/123`). - **New issue URL**: <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 --> - **This URL is not used and removal is planned in a future release.** - Enter any URL here. - For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). - -1. Select **Save changes** or optionally select **Test settings**. + **This URL is not used and an [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/327503) to remove it.** + Enter any URL. -After you configure and enable the custom issue tracker service, a link appears on the GitLab -project pages. This link takes you to the custom issue tracker. +1. Optional. Select **Test settings**. +1. Select **Save changes**. ## Reference issues in a custom issue tracker diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 3177aaefb75..47a81594ca9 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -37,20 +37,20 @@ Complete these steps in GitLab: 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated on GitHub. 1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`. -1. (Optional) To disable static status check names, clear the **Static status check names** checkbox. +1. (Optional) To disable static status check names, clear the **Enable static status check names** checkbox. 1. Select **Save changes** or optionally select **Test settings**. After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. -### Static / dynamic status check names +### Static or dynamic status check names > - Introduced in GitLab 11.5: using static status check names as opt-in option. > - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. This makes it possible to mark these status checks as **Required** on GitHub. -When **Static status check names** is enabled on the integration page, your +When **Enable static status check names** is checked on the integration page, your GitLab instance host name is appended to a status check name. -When disabled, it uses dynamic status check names and appends the branch name. +When unchecked, it uses dynamic status check names and appends the branch name. diff --git a/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png b/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png Binary files differnew file mode 100644 index 00000000000..e316a2acc39 --- /dev/null +++ b/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png diff --git a/doc/user/project/integrations/img/zentao_product_id.png b/doc/user/project/integrations/img/zentao_product_id.png Binary files differnew file mode 100644 index 00000000000..a91b4c3f82d --- /dev/null +++ b/doc/user/project/integrations/img/zentao_product_id.png diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 92e5feefb73..119f219499c 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -54,7 +54,7 @@ Then fill in the integration configuration: To change the bot's username, provide a value. - **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want notifications about failed pipelines only. -- **Branches to be notified**: The branches to send notifications for. +- **Branches for which notifications are to be sent**: The branches to send notifications for. - **Labels to be notified**: (Optional) Labels required for the issue or merge request to trigger a notification. Leave blank to notify for all issues and merge requests. - **Labels to be notified behavior**: When you use the **Labels to be notified** filter, diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index fac26f8e70c..6679bab745b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -18,8 +18,8 @@ in Microsoft Teams. To integrate the services, you must: To configure Microsoft Teams to listen for notifications from GitLab: -1. In Microsoft Teams, search for "incoming webhook" in the search bar, and select the - **Incoming Webhook** item: +1. In Microsoft Teams, type `incoming webhook` in the search bar, and select + **Incoming Webhook**:  @@ -34,11 +34,12 @@ To configure Microsoft Teams to listen for notifications from GitLab: After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: -1. Sign in to GitLab as a user with [Administrator](../../permissions.md) and go - to your project's page. -1. Go to **Settings > Integrations** and select **Microsoft Teams Notification**. -1. Select **Active** to enable the integration. -1. Select the checkbox next to each **Trigger** to enable: +1. Sign in to GitLab as an administrator. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Microsoft Teams notifications**. +1. To enable the integration, select **Active**. +1. In the **Trigger** section, select the checkbox next to each event to enable it: - Push - Issue - Confidential issue @@ -46,15 +47,15 @@ GitLab to send the notifications: - Note - Confidential note - Tag push - - Pipeline - If you enable this trigger, you can also select **Notify only broken pipelines** to be notified only about failed pipelines. + - Pipeline - Wiki page 1. In **Webhook**, paste the URL you copied when you [configured Microsoft Teams](#configure-microsoft-teams). -1. (Optional) If you enabled the pipeline trigger, you can select the +1. Optional. If you enable the pipeline trigger, select the **Notify only broken pipelines** checkbox to push notifications only when pipelines break. 1. Select the branches you want to send notifications for. -1. Click **Save changes**. +1. Select **Save changes**. -## Resources +## Related topics - [Setting up an incoming webhook on Microsoft Teams](https://docs.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/overview.md b/doc/user/project/integrations/overview.md index 2c154467115..819c17c12fd 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -62,6 +62,7 @@ Click on the service links to see further configuration instructions and details | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | +| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index a38d2157699..d399c7f2901 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -45,7 +45,7 @@ to control GitLab from Slack. Slash commands are configured separately. 1. (Optional) In **Username**, enter the username of the Slack bot that sends the notifications. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. -1. In the **Branches to be notified** dropdown, select which types of branches +1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches to send notifications for. 1. Leave the **Labels to be notified** field blank to get all notifications, or add labels that the issue or merge request must have to trigger a diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 814c64d8140..daab24a8ab9 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -21,7 +21,7 @@ In GitLab: 1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. -1. In the **Branches to be notified** dropdown, select which types of branches to send notifications for. +1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches to send notifications for. 1. Select `Save changes` or optionally select **Test settings**. Your Unify Circuit conversation now starts receiving GitLab event notifications. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 9b07e6322bc..ab70a2d43f4 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -9,31 +9,50 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can configure a [webhook](webhooks.md) in your project that triggers when an event occurs. The following events are supported. +Event type | Trigger +---------------------------------------------|----------------------------------------------------------------------------- +[Push event](#push-events) | A push is made to the repository. +[Tag event](#tag-events) | Tags are created or deleted in the repository. +[Issue event](#issue-events) | A new issue is created or an existing issue is updated, closed, or reopened. +[Comment event](#comment-events) | A new comment is made on commits, merge requests, issues, and code snippets. +[Merge request event](#merge-request-events) | A merge request is created, updated, merged, or closed, or a commit is added in the source branch. +[Wiki page event](#wiki-page-events) | A wiki page is created, updated, or deleted. +[Pipeline event](#pipeline-events) | A pipeline status changes. +[Job event](#job-events) | A job status changes. +[Deployment event](#deployment-events) | A deployment starts, succeeds, fails, or is canceled. +[Group member event](#group-member-events) | A user is added or removed from a group, or a user's access level or access expiration date changes. +[Subgroup event](#subgroup-events) | A subgroup is created or removed from a group. +[Feature flag event](#feature-flag-events) | A feature flag is turned on or off. +[Release event](#release-events) | A release is created or updated. + +NOTE: +If an author has no public email listed in their +[GitLab profile](https://gitlab.com/-/profile), the `email` attribute in the +webhook payload displays a value of `[REDACTED]`. + ## Push events -Triggered when you push to the repository except when pushing tags. +Push events are triggered when you push to the repository, except when: -NOTE: -When more than 20 commits are pushed at once, the `commits` webhook -attribute only contains the newest 20 for performance reasons. Loading -detailed commit data is expensive. Note that despite only 20 commits being -present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. +- You push tags. +- A single push includes changes for more than three branches by default + (depending on the [`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)). -NOTE: -If a branch creation push event is generated without new commits being introduced, the -`commits` attribute in the payload is empty. +If you push more than 20 commits at once, the `commits` +attribute in the payload contains information about the newest 20 commits only. +Loading detailed commit data is expensive, so this restriction exists for performance reasons. +The `total_commits_count` attribute contains the actual number of commits. -Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -branches, this hook isn't executed. +If you create and push a branch without any new commits, the +`commits` attribute in the payload is empty. -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Push Hook ``` -**Payload example:** +Payload example: ```json { @@ -111,20 +130,19 @@ X-Gitlab-Event: Push Hook ## Tag events -Triggered when you create (or delete) tags to the repository. +Tag events are triggered when you create or delete tags in the repository. -NOTE: -If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -tags, this hook is not executed. +This hook is not executed if a single push includes changes for more than three +tags by default (depending on the +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)). -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Tag Push Hook ``` -**Payload example:** +Payload example: ```json { @@ -171,22 +189,26 @@ X-Gitlab-Event: Tag Push Hook ## Issue events -Triggered when a new issue is created or an existing issue was updated/closed/reopened. +Issue events are triggered when a new issue is created or +an existing issue is updated, closed, or reopened. -**Request header**: - -```plaintext -X-Gitlab-Event: Issue Hook -``` - -**Available `object_attributes.action`:** +The available values for `object_attributes.action` in the payload are: - `open` - `close` - `reopen` - `update` -**Payload example:** +The `assignee` and `assignee_id` keys are deprecated +and contain the first assignee only. + +Request header: + +```plaintext +X-Gitlab-Event: Issue Hook +``` + +Payload example: ```json { @@ -329,31 +351,31 @@ X-Gitlab-Event: Issue Hook } ``` -NOTE: -`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. - ## Comment events -Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The -payload also includes information about the target of the comment. For example, -a comment on an issue includes the specific issue information under the `issue` key. -Valid target types: +Comment events are triggered when a new comment is made on commits, +merge requests, issues, and code snippets. + +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). +The payload includes information about the target of the comment. For example, +a comment on an issue includes specific issue information under the `issue` key. + +The valid target types are: - `commit` - `merge_request` - `issue` - `snippet` -### Comment on commit +### Comment on a commit -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -428,15 +450,15 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on merge request +### Comment on a merge request -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -558,15 +580,18 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on issue +### Comment on an issue + +- The `assignee_id` field is deprecated and shows the first assignee only. +- The `event_type` is set to `confidential_note` for confidential issues. -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -664,21 +689,15 @@ X-Gitlab-Event: Note Hook } ``` -NOTE: -`assignee_id` field is deprecated and now shows the first assignee only. - -NOTE: -`event_type` is set to `confidential_note` for confidential issues. - -### Comment on code snippet +### Comment on a code snippet -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -749,15 +768,13 @@ X-Gitlab-Event: Note Hook ## Merge request events -Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch. +Merge request events are triggered when: -**Request header**: +- A new merge request is created. +- An existing merge request is updated, approved, unapproved, merged, or closed. +- A commit is added in the source branch. -```plaintext -X-Gitlab-Event: Merge Request Hook -``` - -**Available `object_attributes.action`:** +The available values for `object_attributes.action` in the payload are: - `open` - `close` @@ -767,7 +784,13 @@ X-Gitlab-Event: Merge Request Hook - `unapproved` - `merge` -**Payload example:** +Request header: + +```plaintext +X-Gitlab-Event: Merge Request Hook +``` + +Payload example: ```json { @@ -921,17 +944,17 @@ X-Gitlab-Event: Merge Request Hook } ``` -## Wiki Page events +## Wiki page events -Triggered when a wiki page is created, updated or deleted. +Wiki page events are triggered when a wiki page is created, updated, or deleted. -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Wiki Page Hook ``` -**Payload example**: +Payload example: ```json { @@ -981,18 +1004,18 @@ X-Gitlab-Event: Wiki Page Hook ## Pipeline events +Pipeline events are triggered when the status of a pipeline changes. + In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) and later, the pipeline webhook returns only the latest jobs. -Triggered on status change of Pipeline. - -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Pipeline Hook ``` -**Payload example**: +Payload example: ```json { @@ -1233,15 +1256,17 @@ X-Gitlab-Event: Pipeline Hook ## Job events -Triggered on status change of a job. +Job events are triggered when the status of a job changes. + +The `commit.id` in the payload is the ID of the pipeline, not the ID of the commit. -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Job Hook ``` -**Payload example**: +Payload example: ```json { @@ -1303,24 +1328,24 @@ X-Gitlab-Event: Job Hook } ``` -Note that `commit.id` is the ID of the pipeline, not the ID of the commit. - ## Deployment events -Triggered when a deployment: +Deployment events are triggered when a deployment: -- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) +- Starts ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5) - Succeeds - Fails - Is cancelled -**Request Header**: +The `deployable_id` in the payload is the ID of the CI/CD job. + +Request header: ```plaintext X-Gitlab-Event: Deployment Hook ``` -**Payload example**: +Payload example: ```json { @@ -1363,28 +1388,26 @@ X-Gitlab-Event: Deployment Hook } ``` -Note that `deployable_id` is the ID of the CI job. - ## Group member events **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. Member events are triggered when: -- A user is added as a group member -- The access level of a user has changed -- The expiration date for user access has been updated -- A user has been removed from the group +- A user is added as a group member. +- The access level of a user changes. +- The expiration date for user access is updated. +- A user is removed from the group. ### Add member to group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1406,13 +1429,13 @@ X-Gitlab-Event: Member Hook ### Update member access level or expiration date -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1434,13 +1457,13 @@ X-Gitlab-Event: Member Hook ### Remove member from group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1466,18 +1489,18 @@ X-Gitlab-Event: Member Hook Subgroup events are triggered when: -- A [subgroup is created in a group](#subgroup-created-in-a-group) -- A [subgroup is removed from a group](#subgroup-removed-from-a-group) +- A [subgroup is created in a group](#create-a-subgroup-in-a-group). +- A [subgroup is removed from a group](#remove-a-subgroup-from-a-group). -### Subgroup created in a group +### Create a subgroup in a group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Subgroup Hook ``` -**Payload example**: +Payload example: ```json { @@ -1497,15 +1520,17 @@ X-Gitlab-Event: Subgroup Hook } ``` -### Subgroup removed from a group +### Remove a subgroup from a group -**Request Header**: +This webhook is not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group). + +Request header: ```plaintext X-Gitlab-Event: Subgroup Hook ``` -**Payload example**: +Payload example: ```json { @@ -1525,20 +1550,17 @@ X-Gitlab-Event: Subgroup Hook } ``` -NOTE: -Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group) +## Feature flag events -## Feature Flag events +Feature flag events are triggered when a feature flag is turned on or off. -Triggered when a feature flag is turned on or off. - -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Feature Flag Hook ``` -**Payload example**: +Payload example: ```json { @@ -1580,20 +1602,20 @@ X-Gitlab-Event: Feature Flag Hook ## Release events -Triggered when a release is created or updated. +Release events are triggered when a release is created or updated. -**Request Header**: +The available values for `object_attributes.action` in the payload are: + +- `create` +- `update` + +Request header: ```plaintext X-Gitlab-Event: Release Hook ``` -**Available `object_attributes.action`:** - -- `create` -- `update` - -**Payload example**: +Payload example: ```json { diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 0891d48c038..e0405955d3d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -40,8 +40,14 @@ including: ## Group webhooks **(PREMIUM)** -You can configure a webhook for a group to ensure all projects in the group -receive the same webhook settings. +You can configure a group webhook, which is triggered by events +that occur across all projects in the group. + +Group webhooks can also be configured to listen for events that are +specific to a group, including: + +- [Group member events](webhook_events.md#group-member-events) +- [Subgroup events](webhook_events.md#subgroup-events) ## Configure a webhook diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md new file mode 100644 index 00000000000..67125c3ebbf --- /dev/null +++ b/doc/user/project/integrations/zentao.md @@ -0,0 +1,42 @@ +--- +stage: Ecosystem +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# ZenTao product integration **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. + +[ZenTao](https://www.zentao.net/) is a web-based project management platform. + +## Configure ZenTao + +This integration requires a ZenTao API secret key. + +Complete these steps in ZenTao: + +1. Go to your **Admin** page and select **Develop > Application**. +1. Select **Add Application**. +1. Under **Name** and **Code**, enter a name and a code for the new secret key. +1. Under **Account**, select an existing account name. +1. Select **Save**. +1. Copy the generated key to use in GitLab. + +## Configure GitLab + +Complete these steps in GitLab: + +1. Go to your project and select **Settings > Integrations**. +1. Select **ZenTao**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the ZenTao configuration information: + - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). + - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. + - **ZenTao API token**: Use the key you generated when you [configured ZenTao](#configure-zentao). + - **ZenTao Product ID**: To display issues from a single ZenTao product in a given GitLab project. The Product ID can be found in the ZenTao product page under **Settings > Overview**. + +  + +1. To verify the ZenTao connection is working, select **Test settings**. +1. Select **Save changes**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 8a599608f71..4c35f007fc7 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -197,21 +197,22 @@ card includes: Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the issue board feature to create or delete lists. They can also drag issues from one list to another. -## How GitLab orders issues in a list - -When visiting a board, issues appear ordered in any list. You're able to change -that order by dragging the issues. The changed order is saved, so that anybody who visits the same -board later sees the reordering, with some exceptions. +## Ordering issues in a list 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 it appears in. +When you visit a board, issues appear ordered in any list. You're able to change +that order by dragging the issues. The changed order is saved, so that anybody who visits the same +board later sees the reordering, with some exceptions. + Any time you drag and reorder the issue, its relative order value changes accordingly. Then, any time that issue appears in any board, the ordering is done according to the updated relative order value. If a user in your GitLab instance drags issue `A` above issue `B`, the ordering is maintained when these two issues are subsequently -loaded in any board in the same instance. This could be a different project board or a different group +loaded in any board in the same instance. +This could be a different project board or a different group board, for example. This ordering also affects [issue lists](issues/sorting_issue_lists.md). @@ -593,7 +594,7 @@ You can move issues and lists by dragging them. Prerequisites: -- A minimum of [Reporter](../permissions.md#project-members-permissions) access to a project in GitLab. +- You must have at least the Reporter [role](../permissions.md#project-members-permissions) for a project in GitLab. To move an issue, select the issue card and drag it to another position in its current list or into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists). diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index e020bdee737..aba8c45699c 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -25,7 +25,7 @@ In an issue, leave a comment using the `/zoom` quick action followed by a valid /zoom https://zoom.us/j/123456789 ``` -If the Zoom meeting URL is valid and you have at least [Reporter permissions](../../permissions.md), +If the Zoom meeting URL is valid and you have at least the Reporter [role](../../permissions.md), a system alert notifies you of its successful addition. The issue's description is automatically edited to include the Zoom link, and a button appears right under the issue's title. @@ -44,5 +44,5 @@ Similarly to adding a Zoom meeting, you can remove it with a quick action: /remove_zoom ``` -If you have at least [Reporter permissions](../../permissions.md), +If you have at least the Reporter [role](../../permissions.md), a system alert notifies you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 136e8ee2ebb..b8a01f7ccd6 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -77,14 +77,14 @@ that prevent leaks of private data. 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 [Reporter access](../../permissions.md#project-members-permissions). However, a guest user can also create +least the Reporter [role](../../permissions.md#project-members-permissions). However, a guest user can also create confidential issues, but can only view the ones that they created themselves. Confidential issues are also hidden in search results for unprivileged users. -For example, here's what a user with the [Maintainer role](../../permissions.md) and Guest access +For example, here's what a user with the [Maintainer role](../../permissions.md) and the Guest role sees in the project's search results respectively. -| Maintainer role | Guest access | +| Maintainer role | Guest role | |:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| |  |  | diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 94a5fdc3f0f..2c20ccdcee0 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Due dates **(FREE)** Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are -shipped on time. Users need at least [Reporter permissions](../../permissions.md) +shipped on time. Users need at least the Reporter [role](../../permissions.md) to be able to edit the due date. All users with permission to view the issue can view the due date. diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 9842b0820e6..64838b261ce 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -49,3 +49,4 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) - [Parts of an issue](issue_data_and_actions.md) +- [Tasks](../../tasks.md) diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a2fa044be6b..6b3d5d6563a 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -380,12 +380,18 @@ You can also use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a comment or description field. -## Real-time sidebar **(FREE SELF)** +## Real-time sidebar -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/3413) in GitLab 13.9. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.5. -Assignees in the sidebar are updated in real time. This feature is **disabled by default**. -To enable it, you need to enable [Action Cable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to +[disable the feature flags](../../../administration/feature_flags.md) named `real_time_issue_sidebar` and `broadcast_issue_updates`. +On GitLab.com, this feature is available. + +Assignees in the sidebar are updated in real time. ## Similar issues diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index aed346fb504..ebfc723280f 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -8,34 +8,59 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can sort a list of issues several ways, including by: -- Blocking **(PREMIUM)** -- Created date -- Due date -- Label priority -- Last updated -- Milestone due date -- Popularity -- Priority -- Title ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67234) in GitLab 14.3) -- Weight +- [Blocking issues](#sorting-by-blocking-issues) +- [Created date](#sorting-by-created-date) +- [Due date](#sorting-by-due-date) +- [Label priority](#sorting-by-label-priority) +- [Last updated](#sorting-by-last-updated) +- [Manual sorting](#manual-sorting) +- [Milestone due date](#sorting-by-milestone-due-date) +- [Popularity](#sorting-by-popularity) +- [Priority](#sorting-by-priority) +- [Title](#sorting-by-title) +- [Weight](#sorting-by-weight) The available sorting options can change based on the context of the list. -For sorting by issue priority, see [Label Priority](../labels.md#label-priority). -In group and project issue lists, it is also possible to order issues manually, -similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). +## Sorting by blocking issues **(PREMIUM)** -## Sorting by popularity +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. -When you select sorting by **Popularity**, the issue order changes to sort descending by the -number of upvotes ([awarded](../../award_emojis.md) "thumbs up" emoji) -on each issue. You can use this to identify issues that are in high demand. +When you sort by **Blocking**, the issue list changes to sort descending by the +number of issues each issue is blocking. + +## Sorting by created date + +When you sort by **Created date**, the issue list changes to sort descending by the issue +creation date. Issues created most recently are first. + +## Sorting by due date + +When you sort by **Due date**, the issue list changes to sort ascending by the issue +[due date](issue_data_and_actions.md#due-date). Issues with the earliest due date are first, +and issues without a due date are last. + +## Sorting by label priority + +When you sort by **Label priority**, the issue list changes to sort descending. +Issues with the highest priority label are first, then all other issues. + +Ties are broken arbitrarily. Only the highest prioritized label is checked, +and labels with a lower priority are ignored. +For more information, see [issue 14523](https://gitlab.com/gitlab-org/gitlab/-/issues/14523). + +To learn more about priority labels, read the [Labels](../labels.md#label-priority) documentation. + +## Sorting by last updated + +When you sort by **Last updated**, the issue list changes to sort by the time of a last +update. Issues changed the most recently are first. ## Manual sorting > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. -When you select **Manual** sorting, you can change +When you sort by **Manual** order, you can change the order by dragging and dropping the issues. The changed order persists, and everyone who visits the same list sees the updated issue order, with some exceptions. @@ -48,13 +73,47 @@ the updated relative order value is used for the ordering. So, if anyone drags issue `A` above issue `B` in your GitLab instance, this ordering is maintained whenever they appear together in any list. -This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). +This ordering also affects [issue boards](../issue_board.md#ordering-issues-in-a-list). Changing the order in an issue list changes the ordering in an issue board, -and vice versa. +and the other way around. -## Sorting by blocking issues **(PREMIUM)** +## Sorting by milestone due date -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. +When you sort by **Milestone due date**, the issue list changes to sort ascending by the +assigned milestone due date. Issues with milestones with the earliest due date are first, +then issues with a milestone without a due date. + +## Sorting by popularity + +When you sort by **Popularity**, the issue order changes to sort descending by the +number of upvotes ([awarded](../../award_emojis.md) a "thumbs up" emoji) +on each issue. You can use this to identify issues that are in high demand. + +## Sorting by priority + +When you sort by **Priority**, the issue order changes to sort in this order: + +1. Issues with milestones that have due dates, where the soonest assigned milestone is listed first. +1. Issues with milestones with no due dates. +1. Issues with a higher priority label. +1. Issues without a prioritized label. + +To learn more about priority, read the [Labels](../labels.md#label-priority) documentation. + +## Sorting by title + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67234) in GitLab 14.3. + +When you sort by **Title**, the issue order changes to sort alphabetically by the issue +title in this order: + +- Emoji +- Special characters +- Numbers +- Letters: first Latin, then accented (for example, `ö`) + +## Sorting by weight -When you select to sort by **Blocking**, the issue list changes to sort descending by the -number of issues each issue is blocking. You can use this to determine the critical path for your backlog. +When you sort by **Weight**, the issue list changes to sort ascending by the +[issue weight](issue_weight.md). +Issues with lowest weight are first, and issues without a weight are last. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index f9788ef18ec..adf0a115c6e 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -120,8 +120,8 @@ To remove a member from a project: 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. 1. To prevent leaks of sensitive information from private projects, verify the - user has not forked the private repository. Existing forks continue to receive - changes from the upstream project. You may also want to configure your project + user has not forked the private repository or created webhooks. Existing forks continue to receive + changes from the upstream project, and webhooks continue to receive updates. You may also want to configure your project to prevent projects in a group [from being forked outside their group](../../group/index.md#prevent-project-forking-outside-group). 1. Select **Remove member**. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 2bc6d5bb148..8f803f9207c 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -21,6 +21,9 @@ measuring the accessibility of web sites, and has built a simple This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called `accessibility`. +From [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), the version of `pa11y` uses +[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1), which may report more issues. + ## Accessibility merge request widget > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index aff55419a88..d873f715557 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -3,7 +3,7 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html' +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/approvals/index.html' --- # Merge request approvals **(FREE)** diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index b422982c0e7..1249aa826fa 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -167,7 +167,7 @@ for protected branches. **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. -You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions), +You may have to grant users with the Reporter [role](../../../permissions.md#project-members-permissions) permission to approve merge requests before they can merge to a protected branch. Some users (like managers) may not need permission to push or merge code, but still need oversight on proposed work. To enable approval permissions for these users without diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 1c56e91ed6b..56e93741c1a 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -39,7 +39,7 @@ By default, the author of a merge request cannot approve it. To change this sett 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Clear the **Prevent MR approval by the author** checkbox. +1. Clear the **Prevent approval by author** checkbox. 1. Select **Save changes**. Authors can edit the approval rule in an individual merge request and override @@ -64,14 +64,20 @@ their own. To do this: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent MR approvals from users who make commits to the MR** checkbox. +1. Select the **Prevent approvals by users who add commits** checkbox. If this checkbox is cleared, an administrator has disabled it [at the instance level](../../../admin_area/merge_requests_approvals.md), and it can't be changed at the project level. 1. Select **Save changes**. -Even with this configuration, [code owners](../../code_owners.md) who contribute -to a merge request can approve merge requests that affect files they own. +Depending on your version of GitLab, [code owners](../../code_owners.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 + 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 + to a merge request cannot approve it, when the merge request affects files they own. To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), read the official Git documentation for an explanation. @@ -84,7 +90,7 @@ on merge requests, you can disable this setting: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox. +1. Select the **Prevent editing approval rules in merge requests** checkbox. 1. Select **Save changes**. This change affects all open merge requests. @@ -102,7 +108,7 @@ permission enables an electronic signature for approvals, such as the one define [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Require user password for approvals** checkbox. +1. Select the **Require user password to approve** checkbox. 1. Select **Save changes**. ## Remove all approvals when commits are added to the source branch @@ -113,7 +119,7 @@ when more changes are added to it: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Require new approvals when new commits are added to an MR** checkbox. +1. Select the **Remove all approvals when commits are added to the source branch** checkbox. 1. Select **Save changes**. Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) @@ -133,21 +139,23 @@ coverage. To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). -## Merge request approval settings cascading +## 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md). On GitLab.com, this feature is not available. -You should not use this feature for production environments +On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `group_merge_request_approval_settings_feature_flag`. On GitLab.com, this feature is available. You can also enforce merge request approval settings: -- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all - projects. -- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups and projects. +- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups + on an instance and, therefore, all projects. +- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups + and projects. -If the settings are inherited by a group or project, they cannot be overridden by the group or project that inherited them. +If the settings are inherited by a group or project, they cannot be changed in the group or project +that inherited them. ## Related links diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 339f67f828f..4ae59a76a9a 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -40,7 +40,7 @@ protected branch. ## Forking workflow With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular -developers get Reporter access to the authoritative repository, which prohibits +developers get the Reporter role on the authoritative repository, which prohibits them from pushing any changes to it. Developers create forks of the authoritative project and push their feature diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index e9f1874eb96..9bfbbd8fc6f 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -343,8 +343,7 @@ It's possible to have a custom tool provide Code Quality reports in GitLab. To do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the - [Code Quality report - artifact](../../../ci/yaml/index.md#artifactsreportscodequality). + [Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md new file mode 100644 index 00000000000..b615c86288c --- /dev/null +++ b/doc/user/project/merge_requests/commit_templates.md @@ -0,0 +1,51 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, howto +--- + +# Commit message templates **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. + +## Merge commit message template + +As a project maintainer, you're able to configure merge commit message template. It will be used during merge to +create commit message. Template uses similar syntax to +[review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). + +Default merge commit message can be recreated using following template: + +```plaintext +Merge branch '%{source_branch}' into '%{target_branch}' + +%{title} + +%{issues} + +See merge request %{reference} +``` + +This commit message can be customized to follow any guidelines you might have. +To do so, expand the **Merge requests** tab within your project's **General** +settings and change the **Merge commit message template** text: + + + +You can use static text and following variables: + +| Variable | Description | Output example | +|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| `%{source_branch}` | The name of the branch that is being merged. | `my-feature-branch` | +| `%{target_branch}` | The name of the branch that the changes are applied to. | `master` | +| `%{title}` | Title of the merge request. | Fix stuff | +| `%{issues}` | String with phrase "Closes <issue numbers>" with all issues mentioned in the MR description matching [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). It will be empty when no issues were mentioned. | `Closes #465, #190 and #400` | +| `%{description}` | Description of the merge request. | Merge request description.<br>Can be multiline. | +| `%{reference}` | Reference to the merge request. | group-name/project-name!72359 | + +NOTE: +Empty variables that are the only word in a line will be removed along with all newline characters preceding it. + +Merge commit template field has a limit of 500 characters. This limit only applies to the template +itself. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md new file mode 100644 index 00000000000..dc128f89fcd --- /dev/null +++ b/doc/user/project/merge_requests/conflicts.md @@ -0,0 +1,177 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, concepts +--- + +# Merge conflicts **(FREE)** + +_Merge conflicts_ happen when the two branches in a merge request (the source and target) each have different +changes, and you must decide which change to accept. In a merge request, Git compares +the two versions of the files line by line. In most cases, GitLab can merge changes +together. However, if two branches both change the same lines, GitLab blocks the merge, +and you must choose which change you want to keep. + +A merge request cannot merge until you either: + +- Create a merge commit. +- Resolve the conflict through a rebase. + + + +## Conflicts you can resolve in the user interface + +If your merge conflict meets all of the following conditions, you can resolve the +merge conflict in the GitLab user interface: + +- The file is text, not binary. +- The file is in a UTF-8 compatible encoding. +- The file does not already contain conflict markers. +- The file, with conflict markers added, is less than 200 KB in size. +- The file exists under the same path in both branches. + +If any file in your merge request contains conflicts, but can't meet all of these +criteria, you must resolve the conflict manually. + +## Conflicts GitLab can't detect + +GitLab does not detect conflicts when both branches rename a file to different names. +For example, these changes don't create a conflict: + +1. On branch `a`, doing `git mv example.txt example1.txt` +1. On branch `b`, doing `git mv example1.txt example3.txt`. + +When these branches merge, both `example1.txt` and `example3.txt` are present. + +## Methods of resolving conflicts + +GitLab shows [conflicts available for resolution](#conflicts-you-can-resolve-in-the-user-interface) +in the user interface, and you can also resolve conflicts locally through the command line: + +- [Interactive mode](#resolve-conflicts-in-interactive-mode): UI method best for + conflicts that only require you to select which version of a line to keep, without edits. +- [Inline editor](#resolve-conflicts-in-the-inline-editor): UI method best for more complex conflicts that require you to + edit lines and manually blend changes together. +- [Command line](#resolve-conflicts-from-the-command-line): provides complete control over the most complex conflicts. + +## Resolve conflicts in interactive mode + +To resolve less-complex conflicts from the GitLab user interface: + +1. Go to your merge request. +1. Select **Overview**, and scroll to the merge request reports section. +1. Find the merge conflicts message, and select **Resolve conflicts**. + GitLab shows a list of files with merge conflicts. The conflicts are + highlighted: + +  +1. For each conflict, select **Use ours** or **Use theirs** to mark the version + of the conflicted lines you want to keep. This decision is known as + "resolving the conflict." +1. Enter a **Commit message**. +1. Select **Commit to source branch**. + +Resolving conflicts merges the target branch of the merge request into the +source branch, using the version of the text you chose. If the source branch is +`feature` and the target branch is `main`, these actions are similar to running +`git checkout feature; git merge main` locally. + +## Resolve conflicts in the inline editor + +Some merge conflicts are more complex, requiring you to manually modify lines to +resolve their conflicts. Use the merge conflict resolution editor to resolve complex +conflicts in the GitLab interface: + +1. Go to your merge request. +1. Select **Overview**, and scroll to the merge request reports section. +1. Find the merge conflicts message, and select **Resolve conflicts**. + GitLab shows a list of files with merge conflicts. +1. Select **Edit inline** to open the editor: +  +1. After you resolve the conflict, enter a **Commit message**. +1. Select **Commit to source branch**. + +## Resolve conflicts from the command line + +While most conflicts can be resolved through the GitLab user interface, some are too complex. +Complex conflicts are best fixed locally, from the command line, to give you the +most control over each change: + +1. Open the terminal and check out your feature branch. For example, `my-feature-branch`: + + ```shell + git checkout my-feature-branch + ``` + +1. [Rebase your branch](../../../topics/git/git_rebase.md#regular-rebase) against the + target branch (here, `main`) so Git prompts you with the conflicts: + + ```shell + git fetch + git rebase origin/main + ``` + +1. Open the conflicting file in your preferred code editor. +1. Find the conflict block: + - It begins with the marker: `<<<<<<< HEAD`. + - Next, it displays your changes. + - The marker `=======` indicates the end of your changes. + - Next, it displays the latest changes in the target branch. + - The marker `>>>>>>>` indicates the end of the conflict. +1. Edit the file: + 1. Choose which version (before or after `=======`) you want to keep. + 1. Delete the version you don't want to keep. + 1. Delete the conflict markers. +1. Save the file. +1. Repeat the process for each file that contains conflicts. +1. Stage your changes in Git: + + ```shell + git add . + ``` + +1. Commit your changes: + + ```shell + git commit -m "Fix merge conflicts" + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + + WARNING: + Up to this point, you can run `git rebase --abort` to stop the process. + Git aborts the rebase and rolls back the branch to the state you had before + running `git rebase`. + After you run `git rebase --continue`, you cannot abort the rebase. + +1. [Force-push](../../../topics/git/git_rebase.md#force-push) the changes to your + remote branch. + +## Merge commit strategy + +GitLab resolves conflicts by creating a merge commit in the source branch, but +does not merge it into the target branch. You can then review and test the +merge commit. Verify it contains no unintended changes and doesn't break your build. + +## Related topics + +- [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md). +- [Git GUI apps](https://git-scm.com/downloads/guis) to help you visualize the + differences between branches and resolve them. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 7edc379399b..078f8048900 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -38,6 +38,8 @@ Now, when you visit the merge request page, you can accept it If a fast-forward merge is not possible but a conflict free rebase is possible, a rebase button is offered. +The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). +  If the target branch is ahead of the source branch and a conflict free rebase is diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index cee4df1f61e..006e6d4a8aa 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -172,11 +172,6 @@ is set for deletion, the merge request widget displays the > - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) GitLab 13.10. -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to -[disable the `retarget_merge_requests` flag](../../../administration/feature_flags.md). - In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is open. Merge requests are often chained in this manner, with one merge request diff --git a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png Binary files differnew file mode 100644 index 00000000000..f18ca640d38 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png diff --git a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png b/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png Binary files differdeleted file mode 100644 index 52c715840f1..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differdeleted file mode 100644 index 625d47b1142..00000000000 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2c062c2c592..54b97eb5732 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -17,75 +17,50 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. -To get started, read the [introduction to merge requests](getting_started.md). +Read more about [how to get started](getting_started.md). -## Merge request tabs +## View merge requests -Merge requests contain tabs at the top of the page to help you navigate to -important parts of the merge request: +You can view merge requests for your project, group, or yourself. - +### View merge requests for a project -- **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolve-a-thread) - and [code suggestions](reviews/suggestions.md). The right sidebar provides fields - to add assignees, reviewers, labels, and a milestone to your work, and the - [merge request widgets area](widgets.md) reports results from pipelines and tests. -- **Commits**: Contains a list of commits added to this merge request. For more - information, read [Commits tab in merge requests](commits.md). -- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/index.md) - pipelines and their status. -- **Changes**: Contains the diffs of files changed by this merge request. You can - [configure the display](changes.md). +To view all merge requests for a project: -## View merge requests +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. + +Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. + +### View merge requests for all projects in a group -To view a list of merge requests: +To view merge requests for all projects in a group: -- **Merge requests for a project**: Go to your project and select **Merge requests**, or use - the <kbd>g</kbd> + <kbd>m</kbd> [keyboard shortcut](../../shortcuts.md) from a page in your project. -- **All projects in a group**: Go to your group and select **Merge requests**. - If your group contains subgroups, this view also displays merge requests from the subgroup projects. - GitLab displays a count of open merge requests in the left sidebar, but - [caches the value](reviews/index.md#cached-merge-request-count) for groups with a large number of - open merge requests. -- **Merge requests assigned to you**: On any GitLab page, select **Merge requests** - in the top bar, or use the <kbd>Shift</kbd> + <kbd>m</kbd> - [global keyboard shortcut](../../shortcuts.md). +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Merge requests**. -GitLab displays open merge requests, with tabs to filter the list by open and closed status: +If your group contains subgroups, this view also displays merge requests from the subgroup projects. - +## View all merge requests assigned to you + +To view all merge requests assigned to you: + +1. On the top bar, put your cursor in the **Search** box. +1. From the dropdown list, select **Merge requests assigned to me**. + +Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. You can [search and filter](../../search/index.md#filter-issue-and-merge-request-lists), the results, or select a merge request to begin a review. -## Merge request sidebar - -The **Overview** tab of a merge request displays a sidebar. In this sidebar, you -can assign, categorize, and track progress on a merge request: - -- [**Assignee**](getting_started.md#assignee): Designate the directly responsible - individual (DRI) for a merge request. With - [multiple assignees](getting_started.md#multiple-assignees), you can assign a - merge request to more than one person at a time. -- [**Reviewer**](reviews/index.md): Designate a team member to review a merge request. - Higher tiers can assign multiple reviewers, and [require approvals](approvals/index.md) - from these reviewers. -- [**Milestone**](../milestones/index.md): Track time-sensitive changes. -- [**Time tracking**](../time_tracking.md): Time spent on a merge request. -- [**Labels**](../labels.md): Categorize a merge request and display it on - appropriate [issue boards](../issue_board.md). -- **Participants**: A list of users participating or watching a merge request. -- [**Notifications**](../../profile/notifications.md): A toggle to select whether - or not to receive notifications for updates to a merge request. - ## Add changes to a merge request If you have permission to add changes to a merge request, you can add your changes -to an existing merge request in several ways, depending on the complexity of your change and whether you need access to a development environment: +to an existing merge request in several ways, depending on the complexity of your +change and whether you need access to a development environment: -- [Edit changes in the Web IDE](../web_ide/index.md) in your browser. Use this +- [Edit changes in the Web IDE](../web_ide/index.md) in your browser with the + <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md). Use this browser-based method to edit multiple files, or if you are not comfortable with Git commands. You cannot run tests from the Web IDE. - [Edit changes in Gitpod](../../../integration/gitpod.md#launch-gitpod-in-gitlab), if you @@ -158,3 +133,7 @@ For a web developer writing a webpage for your company's website: - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) - [GitLab keyboard shortcuts](../../shortcuts.md) +- [Comments and threads](../../discussions/index.md) +- [Suggest code changes](reviews/suggestions.md) +- [Commits](commits.md) +- [CI/CD pipelines](../../../ci/index.md) 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 d7c9c0f73ee..256dde4fa17 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -101,7 +101,7 @@ for details on avoiding two pipelines for a single merge request. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/index.md#skip-pipeline) prevent +When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent merge requests from being merged. To change this behavior: 1. Navigate to your project's **Settings > General** page. diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 4681ef09388..611f37a949b 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,85 +1,9 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts +redirect_to: 'conflicts.md' +remove_date: '2022-01-26' --- -# Merge request conflict resolution **(FREE)** +This document was moved to [another location](conflicts.md). -Merge conflicts occur when two branches have different changes that cannot be -merged automatically. - -Git can merge changes between branches in most cases, but -occasionally Git requires your assistance to resolve the -conflicts manually. Typically, this is necessary when people change the same -parts of the same files. - -GitLab prevents merge requests from being merged until all conflicts are -resolved. Conflicts can be resolved locally, or in many cases in GitLab -(see [conflicts available for resolution](#conflicts-available-for-resolution) -for information on when this is available). - - - -NOTE: -GitLab resolves conflicts by creating a merge commit in the source branch that -is not automatically merged into the target branch. The merge -commit can be reviewed and tested before the changes are merged. This prevents -unintended changes entering the target branch without review or breaking the -build. - -## Resolve conflicts: interactive mode - -Clicking **Resolve Conflicts** displays a list of files with conflicts, with conflict sections -highlighted: - - - -After all conflicts have been marked as using 'ours' or 'theirs', the conflict -can be resolved. Resolving conflicts merges the target branch of the merge -request into the source branch, using the options -chosen. If the source branch is `feature` and the target branch is `main`, -this is similar to performing `git checkout feature; git merge main` locally. - -## Resolve conflicts: inline editor - -Some merge conflicts are more complex, requiring you to manually modify a file to -resolve them. Use the merge conflict resolution editor to resolve complex -conflicts in the GitLab interface. Click **Edit inline** to open the editor. -After you're sure about your changes, click **Commit to source branch**. - - - -## Conflicts available for resolution - -GitLab allows resolving conflicts in a file where all of the below are true: - -- The file is text, not binary -- The file is in a UTF-8 compatible encoding -- The file does not already contain conflict markers -- The file, with conflict markers added, is not over 200 KB in size -- The file exists under the same path in both branches - -If any file in your merge request containing conflicts can't meet all of these -criteria, you can't resolve the merge conflict in the UI. - -Additionally, GitLab does not detect conflicts in renames away from a path. For -example, this does not create a conflict: - -1. On branch `a`, doing `git mv file1 file2` -1. On branch `b`, doing `git mv file1 file3`. - -Instead, both files are present in the branch after the merge request is merged. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <2022-01-26>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e6f84f1c357..597dcb3dfb9 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -17,6 +17,10 @@ your merge request, and makes [code suggestions](suggestions.md) you can accept from the user interface. When your work is reviewed, your team members can choose to accept or reject it. +You can review merge requests from the GitLab interface. If you install the +[GitLab Workflow VS Code extension](../../repository/vscode.md), you can also +review merge requests in Visual Studio Code. + ## Review a merge request > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. @@ -207,7 +211,7 @@ These features are associated with merge requests: When viewing the commit details page, GitLab links to the merge request(s) containing that commit. - [Merge requests versions](../versions.md): Select and compare the different versions of merge request diffs -- [Resolve conflicts](../resolve_conflicts.md): +- [Resolve conflicts](../conflicts.md): GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. - [Revert changes](../revert_changes.md): Revert changes from any commit from a merge request. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index ac1cd57fb99..7bfb8e52279 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -7,14 +7,13 @@ type: index, reference # Suggest changes **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. -> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request diff threads. Then, the merge request author (or other users with appropriate -[permission](../../../permissions.md)) is able to apply these suggestions with a click, -which generates a commit in the merge request authored by the user that suggested the changes. +[permission](../../../permissions.md)) can apply these suggestions with a click. +This action generates a commit in the merge request, authored by the user that suggested the changes. 1. Choose a line of code to be changed, add a new comment, then select the **Insert suggestion** icon in the toolbar: @@ -38,14 +37,15 @@ which generates a commit in the merge request authored by the user that suggeste  -After the author applies a suggestion, it's marked with the **Applied** label, -the thread is automatically resolved, and GitLab creates a new commit -and pushes the suggested change directly into the codebase in the merge request's -branch. The [Developer role](../../../permissions.md) is required to do so. +After the author applies a suggestion: -## Multi-line suggestions +1. The suggestion is marked as **Applied**. +1. The thread is resolved. +1. GitLab creates a new commit with the changes. +1. If the user has the [Developer role](../../../permissions.md), GitLab pushes + the suggested change directly into the codebase in the merge request's branch. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. +## Multi-line suggestions Reviewers can also suggest changes to multiple lines with a single suggestion within merge request diff threads by adjusting the range offsets. The @@ -67,9 +67,9 @@ suggestion. ## Code block nested in suggestions -If you need to make a suggestion that involves a -[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks -instead of the usual three. +To add a suggestion that includes a +[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion +in four backticks instead of three:  @@ -95,14 +95,14 @@ You can also use following variables besides static text: | Variable | Description | Output example | |------------------------|-------------|----------------| -| `%{branch_name}` | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` | -| `%{files_count}` | The number of file(s) to which suggestion(s) was(were) applied.| **2** | -| `%{file_paths}` | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | +| `%{branch_name}` | The name of the branch to which suggestions were applied. | `my-feature-branch` | +| `%{files_count}` | The number of files to which suggestions were applied.| **2** | +| `%{file_paths}` | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` | | `%{project_path}` | The project path. | `my-group/my-project` | | `%{project_name}` | The human-readable name of the project. | **My Project** | | `%{suggestions_count}` | The number of suggestions applied.| **3** | -| `%{username}` | The username of the user applying suggestion(s). | `user_1` | -| `%{user_full_name}` | The full name of the user applying suggestion(s). | **User 1** | +| `%{username}` | The username of the user applying suggestions. | `user_1` | +| `%{user_full_name}` | The full name of the user applying suggestions. | **User 1** | For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to @@ -114,32 +114,32 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. -> - Custom commit messages for batch suggestions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) in GitLab 14.4. +> - [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: -  +  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. 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 27487003697..ee4320d5ea1 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 @@ -27,6 +27,17 @@ and steps below. - Access to your domain's server control panel to set up DNS records: - A DNS A or CNAME record pointing your domain to GitLab Pages server. - A DNS `TXT` record to verify your domain's ownership. +- Set either `external_http` or `external_https` in `/etc/gitlab/gitlab.rb` to the IP and port of + your [Pages Daemon](../../../../administration/pages/index.md#overview). + If you don't have IPv6, you can omit the IPv6 address. + + Example: + + ```ruby + # Redirect pages from HTTP to HTTPS + gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon + gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # The secondary IPs for the GitLab Pages daemon + ``` ### Steps 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 4f2b62beab1..25382778b1d 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 @@ -13,31 +13,16 @@ the CI/CD pipeline to generate a Pages website. Use a `.gitlab-ci.yml` template when you have an existing project that you want to add a Pages site to. -Your GitLab repository should contain files specific to an SSG, or plain HTML. -After you complete these steps, you may need to do additional -configuration for the Pages site to generate properly. - -1. On the left sidebar, select **Project information**. -1. Click **Set up CI/CD**. - -  - - If this button is not available, CI/CD is already configured for - your project. You may want to browse the `.gitlab-ci.yml` files - [in these projects instead](https://gitlab.com/pages). - -1. From the **Apply a template** list, choose a template for the SSG you're using. - You can also choose plain HTML. - -  - - If you don't find a corresponding template, you can view the - [GitLab Pages group of sample projects](https://gitlab.com/pages). - These projects contain `.gitlab-ci.yml` files that you can modify for your needs. - You can also [learn how to write your own `.gitlab-ci.yml` - file for GitLab Pages](pages_from_scratch.md). - -1. Save and commit the `.gitlab-ci.yml` file. +Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete +these steps, you may have to do additional configuration for the Pages site to generate properly. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select the project's name. +1. From the **Add** (**{plus}**) dropdown, select **New file**. +1. From the **Select a template type** dropdown, select `.gitlab-ci.yml`. +1. From the **Apply a template** dropdown, in the **Pages** section, select the name of your SSG. +1. In the **Commit message** box, type the commit message. +1. Select **Commit changes**. If everything is configured correctly, the site can take approximately 30 minutes to deploy. diff --git a/doc/user/project/pages/img/choose_ci_template_v13_1.png b/doc/user/project/pages/img/choose_ci_template_v13_1.png Binary files differdeleted file mode 100644 index a0c25ba1642..00000000000 --- a/doc/user/project/pages/img/choose_ci_template_v13_1.png +++ /dev/null diff --git a/doc/user/project/pages/img/setup_ci_v13_1.png b/doc/user/project/pages/img/setup_ci_v13_1.png Binary files differdeleted file mode 100644 index 2cf1c05d6d8..00000000000 --- a/doc/user/project/pages/img/setup_ci_v13_1.png +++ /dev/null diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 45c2f1aaf04..59a2f0c2eba 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -223,16 +223,13 @@ Consider a Pages site deployed with the following files: ```plaintext public/ -├─┬ index.html -│ ├ data.html -│ └ info.html -│ +├── index.html +├── data.html +├── info.html ├── data/ │ └── index.html -├── info/ -│ └── details.html -└── other/ - └── index.html +└── info/ + └── details.html ``` Pages supports reaching each of these files through several different URLs. In @@ -241,23 +238,19 @@ specifies the directory. If the URL references a file that doesn't exist, but adding `.html` to the URL leads to a file that *does* exist, it's served instead. Here are some examples of what happens given the above Pages site: -| URL path | HTTP response | File served | -| -------------------- | ------------- | ----------- | -| `/` | `200 OK` | `public/index.html` | -| `/index.html` | `200 OK` | `public/index.html` | -| `/index` | `200 OK` | `public/index.html` | -| `/data` | `200 OK` | `public/data/index.html` | -| `/data/` | `200 OK` | `public/data/index.html` | -| `/data.html` | `200 OK` | `public/data.html` | -| `/info` | `200 OK` | `public/info.html` | -| `/info/` | `200 OK` | `public/info.html` | -| `/info.html` | `200 OK` | `public/info.html` | -| `/info/details` | `200 OK` | `public/info/details.html` | -| `/info/details.html` | `200 OK` | `public/info/details.html` | -| `/other` | `302 Found` | `public/other/index.html` | -| `/other/` | `200 OK` | `public/other/index.html` | -| `/other/index` | `200 OK` | `public/other/index.html` | -| `/other/index.html` | `200 OK` | `public/other/index.html` | +| URL path | HTTP response | +| -------------------- | ------------- | +| `/` | `200 OK`: `public/index.html` | +| `/index.html` | `200 OK`: `public/index.html` | +| `/index` | `200 OK`: `public/index.html` | +| `/data` | `302 Found`: redirecting to `/data/` | +| `/data/` | `200 OK`: `public/data/index.html` | +| `/data.html` | `200 OK`: `public/data.html` | +| `/info` | `302 Found`: redirecting to `/info/` | +| `/info/` | `404 Not Found` Error Page | +| `/info.html` | `200 OK`: `public/info.html` | +| `/info/details` | `200 OK`: `public/info/details.html` | +| `/info/details.html` | `200 OK`: `public/info/details.html` | Note that when `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 305bbb2ded0..15df69ee68c 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -69,8 +69,8 @@ time as pushing changes: | `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. Ex: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | -| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | +| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID.For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | If you use a push option that requires text with spaces in it, you need to enclose it in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: @@ -117,3 +117,13 @@ pipeline succeeds: ```shell git mwps origin <local-branch-name> ``` + +## Troubleshooting + +## Push options for merge request assignment ignored + +When you push a branch to GitLab, you can use push options to assign to (`merge_request.assign="<USERNAME>"`) +or unassign from (`merge_request.unassign="<USERNAME>"`) a user. If GitLab creates +the merge request successfully, but fails to assign or unassign the merge request +correctly, you can use the user ID instead. For more information, read the issue +[Push option `merge_request.(un)assign` seems to be ignored](https://gitlab.com/gitlab-org/gitlab/-/issues/325169). diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 45a83394c41..a4d7b94506b 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -78,6 +78,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | | `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | | `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 9e4d621dbc6..abedae5d10b 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -78,17 +78,172 @@ To create a new release through the GitLab UI: [release notes](#release-notes-description), or [assets links](#links). 1. Click **Create release**. -### Create release from GitLab CI +## Create a release by using a CI/CD job > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. -You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/index.md#release) -by using a `release` node in the job definition. +You can create a release directly as part of the GitLab CI/CD pipeline +by using [the `release` keyword](../../../ci/yaml/index.md#release) in the job definition. The release is created only if the job processes without error. If the Rails API returns an error during release creation, the release job fails. -### Upcoming releases +### CI/CD example of the `release` keyword + +To create a release when you push a Git tag, or when you add a Git tag +in the UI by going to **Repository > Tags**: + +```yaml +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG # Run this job when a tag is created manually + script: + - echo 'running release_job' + release: + name: 'Release $CI_COMMIT_TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined + tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline. + ref: '$CI_COMMIT_TAG' + milestones: + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: # Optional, multiple asset links + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + +To create a release automatically when commits are pushed or merged to the default branch, +using a new Git tag that is defined with variables: + +```yaml +prepare_job: + stage: prepare # This stage must run before the release stage + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "EXTRA_DESCRIPTION=some message" >> variables.env # Generate the EXTRA_DESCRIPTION and TAG environment variables + - echo "TAG=v$(cat VERSION)" >> variables.env # and append to the variables.env file + artifacts: + reports: + dotenv: variables.env # Use artifacts:reports:dotenv to expose the variables to other jobs + +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + needs: + - job: prepare_job + artifacts: true + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo 'running release_job for $TAG' + release: + name: 'Release $TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG + tag_name: '$TAG' # variables must be defined elsewhere + ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the + milestones: # prepare_job + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + +NOTE: +Environment variables set in `before_script` or `script` are not available for expanding +in the same job. Read more about +[potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). + +### Use a custom SSL CA certificate authority + +You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, +which is used to verify the peer when the `release-cli` creates a release through the API using HTTPS with custom certificates. +The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the +[text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1) +or the `path/to/file` containing the certificate authority. +For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +release: + variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- + script: + - echo "Create release" + release: + name: 'My awesome release' + tag_name: '$CI_COMMIT_TAG' +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a +[custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), +either as a `file`, which requires the path to the certificate, or as a variable, +which requires the text representation of the certificate. + +### `release-cli` command line + +The entries under the `release` node are transformed into a `bash` command line and sent +to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). +You can also call the `release-cli` directly from a `script` entry. + +For example, if you use the YAML described previously: + +```shell +release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} +``` + +### Create multiple releases in a single pipeline + +A pipeline can have multiple `release` jobs, for example: + +```yaml +ios-release: + script: + - echo 'iOS release job' + release: + tag_name: v1.0.0-ios + description: 'iOS release v1.0.0' + +android-release: + script: + - echo 'Android release job' + release: + tag_name: v1.0.0-android + description: 'Android release v1.0.0' +``` + +### Release assets as Generic packages + +You can use [Generic packages](../../packages/generic_packages/index.md) to host your release assets. +For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) +project. + +## Upcoming releases > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. @@ -238,14 +393,6 @@ The release title can be customized using the **Release title** field when creating or editing a release. If no title is provided, the release's tag name is used instead. -Guest users of private projects are allowed to view the **Releases** page -but are _not_ allowed to view details about the Git repository (in particular, -tag names). Because of this, release titles are replaced with a generic -title like "Release-1234" for Guest users to avoid leaking tag name information. - -See the [Release permissions](#release-permissions) section for -more information about permissions. - ### Tag name The release tag name should include the release version. GitLab uses [Semantic Versioning](https://semver.org/) @@ -569,11 +716,14 @@ In the API: ### View a release and download assets -- Users with [Reporter role or above](../../../user/permissions.md#project-members-permissions) +> [Changes were made to the Guest role access](https://gitlab.com/gitlab-org/gitlab/-/issues/335209) in GitLab 14.5. + +- Users with the [Reporter role or above](../../../user/permissions.md#project-members-permissions) + have read and download access to the project releases. +- Users with the [Guest role](../../../user/permissions.md#project-members-permissions) have read and download access to the project releases. -- Users with [Guest role](../../../user/permissions.md#project-members-permissions) - have read and download access to the project releases, however, - repository-related information are redacted (for example the Git tag name). + This includes associated Git-tag-names, release description, author information of the releases. + However, other repository-related information, such as [source code](#source-code), [release evidence](#release-evidence) are redacted. ### Create, update, and delete a release and its assets diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md new file mode 100644 index 00000000000..c23ceaa1aba --- /dev/null +++ b/doc/user/project/releases/release_cli.md @@ -0,0 +1,76 @@ +--- +type: reference, howto +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install the `release-cli` for the Shell executor + +> - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. +> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages). + +When you use a runner with the Shell executor, you can download and install +the `release-cli` manually for your [supported OS and architecture](https://release-cli-downloads.s3.amazonaws.com/latest/index.html). +Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is available to use in your CI/CD jobs. + +## Install on Unix/Linux + +1. Download the binary for your system from S3, in the following example for amd64 systems: + + ```shell + curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64" + ``` + + Or from the GitLab Package Registry: + + ```shell + curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-darwin-amd64" + ``` + +1. Give it permissions to execute: + + ```shell + sudo chmod +x /usr/local/bin/release-cli + ``` + +1. Verify `release-cli` is available: + + ```shell + $ release-cli -v + + release-cli version 0.6.0 + ``` + +## Install on Windows PowerShell + +1. Create a folder somewhere in your system, for example `C:\GitLab\Release-CLI\bin` + + ```shell + New-Item -Path 'C:\GitLab\Release-CLI\bin' -ItemType Directory + ``` + +1. Download the executable file: + + ```shell + PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe" + + Directory: C:\GitLab\Release-CLI + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + d----- 3/16/2021 4:17 AM bin + ``` + +1. Add the directory to your `$env:PATH`: + + ```shell + $env:PATH += ";C:\GitLab\Release-CLI\bin" + ``` + +1. Verify `release-cli` is available: + + ```shell + PS C:\> release-cli -v + + release-cli version 0.6.0 + ``` diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 5cd025f017d..bc6bc799670 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -167,7 +167,7 @@ changed, GitLab records the name of the old default branch. If that branch is deleted, attempts to view a file or directory on it are redirected to the current default branch, instead of displaying the "not found" page. -## Resources +## Related topics - [Configure a default branch for your wiki](../../wiki/index.md) - [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 23d7aecc960..6aa32b1b816 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -39,7 +39,10 @@ For a commit to be verified by GitLab: - The committer's public key must have been uploaded to their GitLab account. - One of the emails in the GPG key must match a **verified** email address - used by the committer in GitLab. + used by the committer in GitLab. This address will be part of the public key. + If you want to keep this address private, use the automatically generated + [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) + GitLab provides in your profile. - The committer's email address must match the verified email address from the GPG key. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index de7459e6278..bb1a55f6b2b 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -41,7 +41,7 @@ to a branch in the repository. When you use the command line, you can commit mul If the project is configured with [GitLab CI/CD](../../../ci/index.md), you trigger a pipeline per push, not per commit. - **Skip pipelines:** - Add the [`ci skip`](../../../ci/yaml/index.md#skip-pipeline) keyword to + Add the [`ci skip`](../../../ci/pipelines/index.md#skip-a-pipeline) keyword to your commit message to make GitLab CI/CD skip the pipeline. - **Cross-link issues and merge requests:** Use [cross-linking](../issues/crosslinking_issues.md#from-commit-messages) @@ -82,14 +82,19 @@ prompted to open XCode. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. -All projects can be cloned into Visual Studio Code. To do that: +All projects can be cloned into Visual Studio Code from the GitLab user interface, but you +can also install the [GitLab Workflow VS Code extension](vscode.md) to clone from +Visual Studio Code: -1. From the GitLab UI, go to the project's overview page. -1. Click **Clone**. -1. Select **Clone with Visual Studio Code** under either HTTPS or SSH method. -1. Select a folder to clone the project into. +- From the GitLab interface: + 1. Go to the project's overview page. + 1. Select **Clone**. + 1. Under either the **HTTPS** or **SSH** method, select **Clone with Visual Studio Code**. + 1. Select a folder to clone the project into. -When VS Code has successfully cloned your project, it opens the folder. + After Visual Studio Code clones your project, it opens the folder. +- From Visual Studio Code, with the [extension](vscode.md) installed, use the + extension's [`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). ## Download the code in a repository @@ -243,6 +248,10 @@ When you [rename a user](../../profile/index.md#change-your-username), - The redirects are available as long as the original path is not claimed by another group, user, or project. +## Related links + +- [GitLab Workflow VS Code extension](vscode.md) + ## Troubleshooting ### Repository Languages: excessive CPU use diff --git a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png Binary files differnew file mode 100644 index 00000000000..bc63322cd65 --- /dev/null +++ b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 2ad1504aac3..d040cc93876 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -4,22 +4,42 @@ group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- -# Jupyter Notebook Files **(FREE)** +# Jupyter Notebook files **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. +[Jupyter Notebook](https://jupyter.org/) (previously, IPython Notebook) files are used for +interactive computing in many fields. They contain a complete record of the +user's sessions and include: -[Jupyter](https://jupyter.org/) Notebook (previously IPython Notebook) files are used for -interactive computing in many fields and contain a complete record of the -user's sessions and include code, narrative text, equations, and rich output. +- Code. +- Narrative text. +- Equations. +- Rich output. -When added to a repository, Jupyter Notebooks with a `.ipynb` extension are -rendered to HTML when viewed: +When you add a Jupyter Notebook (with `.ipynb` extension) to your repository, +it's rendered into HTML when you view it:  Interactive features, including JavaScript plots, don't work when viewed in GitLab. +## Cleaner diffs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. 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 `jupyter_clean_diffs`. +On GitLab.com, this feature is available. + +When commits include changes to Jupyter Notebook files, GitLab: + +- Transforms the machine-readable `.ipynb` file into a human-readable Markdown file. +- Displays a cleaner version of the diff that includes syntax highlighting. + +Code suggestions are not available on diffs and merge requests for `.ipynb` files. + + + ## Jupyter Git integration Jupyter can be configured as an OAuth application with repository access, acting diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index c4254655fcc..340d7b48a47 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -139,7 +139,7 @@ This sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update, and Git displays warnings about it. -## Mirror with Perforce Helix via Git Fusion **(PREMIUM)** +## Mirror with Perforce Helix with Git Fusion **(PREMIUM)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/repository/mirror/img/repository_mirroring_copy_ssh_public_key_button.png b/doc/user/project/repository/mirror/img/repository_mirroring_copy_ssh_public_key_button.png Binary files differdeleted file mode 100644 index e20dae09a4d..00000000000 --- a/doc/user/project/repository/mirror/img/repository_mirroring_copy_ssh_public_key_button.png +++ /dev/null diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 4532a80c2f5..361c0902ebf 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -7,102 +7,162 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** -Repository mirroring allows for the mirroring of repositories to and from external sources. You -can use it to mirror branches, tags, and commits between repositories. It helps you use -a repository outside of GitLab. +You can _mirror_ a repository to and from external sources. You can select which +repository serves as the source, and modify which parts of the repository are copied. +Branches, tags, and commits can be mirrored. -A repository mirror at GitLab updates automatically. You can also manually trigger an update: - -- At most once every five minutes on GitLab.com. -- According to a [limit set by the administrator](../../../../administration/instance_limits.md#pull-mirroring-interval) - on self-managed instances. - -There are two kinds of repository mirroring supported by GitLab: +Several mirroring methods exist: - [Push](push.md): for mirroring a GitLab repository to another location. - [Pull](pull.md): for mirroring a repository from another location to GitLab. +- [Bidirectional](bidirectional.md) mirroring is also available, but can cause conflicts. + +Mirror a repository when: + +- The canonical version of your project has migrated to GitLab. To keep providing a + copy of your project at its previous home, configure your GitLab repository as a + [push mirror](push.md). Changes you make to your GitLab repository are copied to + the old location. +- Your GitLab project is private, but some components can be shared publicly. + Configure your primary repository as a [push mirror](push.md) and push the portions + you want to make public. With this configuration, you can open-source specific + projects, contribute back to the open-source community, and protect the sensitive + parts of your project. +- You migrated to GitLab, but the canonical version of your project is somewhere else. + Configure your GitLab repository as a [pull mirror](pull.md) of the other project. + Your GitLab repository pulls copies of the commits, tags, and branches of project. + They become available to use on GitLab. + +## Create a repository mirror + +Prerequisite: + +- You must have at least the [Maintainer role](../../../permissions.md) for the project. +- If your mirror connects with `ssh://`, the host key must be detectable on the server, + or you must have a local copy of the key. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Enter a **Git repository URL**. For security reasons, the URL to the original + repository is only displayed to users with the [Maintainer role](../../../permissions.md) + or the [Owner role](../../../permissions.md) for the mirrored project. +1. Select a **Mirror direction**. +1. If you entered a `ssh://` URL, select either: + - **Detect host keys**: GitLab fetches the host keys from the server and displays the fingerprints. + - **Input host keys manually**, and enter the host key into **SSH host key**. + + When mirroring the repository, GitLab confirms at least one of the stored host keys + matches before connecting. This check can protect your mirror from malicious code injections, + or your password from being stolen. +1. Select an **Authentication method**. To learn more, read + [Authentication methods for mirrors](#authentication-methods-for-mirrors). +1. If you authenticate with SSH host keys, [verify the host key](#verify-a-host-key) + to ensure it is correct. +1. To prevent force-pushing over diverged refs, select [**Keep divergent refs**](push.md#keep-divergent-refs). +1. Optional. Select [**Mirror only protected branches**](#mirror-only-protected-branches). +1. Select **Mirror repository**. + +If you select `SSH public key` as your authentication method, GitLab generates a +public key for your GitLab repository. You must provide this key to the non-GitLab server. +To learn more, read [Get your SSH public key](#get-your-ssh-public-key). + +## Update a mirror When the mirror repository is updated, all new branches, tags, and commits are visible in the -project's activity feed. +project's activity feed. A repository mirror at GitLab updates automatically. +You can also manually trigger an update: -Users with the [Maintainer role](../../../permissions.md) for the project can also force an -immediate update, unless: +- At most once every five minutes on GitLab.com. +- According to [the pull mirroring interval limit](../../../../administration/instance_limits.md#pull-mirroring-interval) + set by the administrator on self-managed instances. -- The mirror is already being updated. -- The [limit for pull mirroring interval seconds](../../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed after its last update. +### Force an update -For security reasons, the URL to the original repository is only displayed to users with the -[Maintainer role](../../../permissions.md) or the [Owner role](../../../permissions.md) for the mirrored -project. +While mirrors are scheduled to update automatically, you can force an immediate update unless: -## Use cases +- The mirror is already being updated. +- The [interval, in seconds](../../../../administration/instance_limits.md#pull-mirroring-interval) + for pull mirroring limits has not elapsed after its last update. -The following are some possible use cases for repository mirroring: +Prerequisite: -- You migrated to GitLab but still must keep your project in another source. In that case, you - can set it up to mirror to GitLab (pull) and all the essential history of commits, tags, - and branches are available in your GitLab instance. **(PREMIUM)** -- You have old projects in another source that you don't use actively anymore, but don't want to - remove for archiving purposes. In that case, you can create a push mirror so that your active - GitLab repository can push its changes to the old location. -- You are a GitLab self-managed user for privacy reasons and your instance is closed to the public, - but you still have certain software components that you want open sourced. In this case, utilizing - GitLab to be your primary repository which is closed from the public, and using push mirroring to a - GitLab.com repository that's public, allows you to open source specific projects and contribute back - to the open source community. +- You must have at least the [Maintainer role](../../../permissions.md) for the project. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Scroll to **Mirrored repositories** and identify the mirror to update. +1. Select **Update now** (**{retry}**): +  ## Mirror only protected branches **(PREMIUM)** > Moved to GitLab Premium in 13.9. -Based on the mirror direction that you choose, you can opt to mirror only the +You can choose to mirror only the [protected branches](../../protected_branches.md) in the mirroring project, -either from or to your remote repository. For pull mirroring, non-protected branches in -the mirroring project are not mirrored and can diverge. +either from or to your remote repository. For [pull mirroring](pull.md), +non-protected branches in the mirroring project are not mirrored and can diverge. + +To use this option, select **Only mirror protected branches** when you create a repository mirror. -To use this option, check the **Only mirror protected branches** box when -creating a repository mirror. **(PREMIUM)** +## Authentication methods for mirrors -## SSH authentication +When you create a mirror, you must configure the authentication method for it. +GitLab supports these authentication methods: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. +- [SSH authentication](#ssh-authentication). +- Password. + +### SSH authentication SSH authentication is mutual: -- You have to prove to the server that you're allowed to access the repository. -- The server also has to prove to *you* that it's who it claims to be. +- You must prove to the server that you're allowed to access the repository. +- The server must also *prove to you* that it's who it claims to be. -You provide your credentials as a password or public key. The server that the -other repository resides on provides its credentials as a "host key", the -fingerprint of which needs to be verified manually. +For SSH authentication, you provide your credentials as a password or _public key_. +The server that the other repository resides on provides its credentials as a _host key_. +You must [verify the fingerprint](#verify-a-host-key) of this host key manually. If you're mirroring over SSH (using an `ssh://` URL), you can authenticate using: - Password-based authentication, just as over HTTPS. -- Public key authentication. This is often more secure than password authentication, +- Public key authentication. This method is often more secure than password authentication, especially when the other repository supports [deploy keys](../../deploy_keys/index.md). -To get started: - -1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. -1. Enter an `ssh://` URL for mirroring. +### Get your SSH public key -NOTE: -SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. +When you mirror a repository and select the **SSH public key** as your +authentication method, GitLab generates a public key for you. The non-GitLab server +needs this key to establish trust with your GitLab repository. To copy your SSH public key: -Entering the URL adds two buttons to the page: +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Scroll to **Mirrored repositories**. +1. Identify the correct repository, and select **Copy SSH public key** (**{copy-to-clipboard}**). +1. Add the public SSH key to the other repository's configuration: + - If the other repository is hosted on GitLab, add the public SSH key + as a [deploy key](../../../project/deploy_keys/index.md). + - If the other repository is hosted elsewhere, add the key to + your user's `authorized_keys` file. Paste the entire public SSH key into the + file on its own line and save it. -- **Detect host keys**. -- **Input host keys manually**. +If you must change the key at any time, you can remove and re-add the mirror +to generate a new key. Update the other repository with the new +key to keep the mirror running. -If you select the: +NOTE: +The generated keys are stored in the GitLab database, not in the file system. Therefore, +SSH public key authentication for mirrors cannot be used in a pre-receive hook. -- **Detect host keys** button, GitLab fetches the host keys from the server and display the fingerprints. -- **Input host keys manually** button, a field is displayed where you can paste in host keys. +### Verify a host key -Assuming you used the former, you now must verify that the fingerprints are -those you expect. GitLab.com and other code hosting sites publish their -fingerprints in the open for you to check: +When using a host key, always verify the fingerprints match what you expect. +GitLab.com and other code hosting sites publish their fingerprints +for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) @@ -112,9 +172,11 @@ fingerprints in the open for you to check: - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) - [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) -Other providers vary. If you're running self-managed GitLab, or otherwise -have access to the server for the other repository, you can securely gather the -key fingerprints: +Other providers vary. You can securely gather key fingerprints with the following +command if you: + +- Run self-managed GitLab. +- Have access to the server for the other repository. ```shell $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - @@ -123,45 +185,9 @@ $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - 2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) ``` -NOTE: -You must exclude `-E md5` for some older versions of SSH. - -When mirroring the repository, GitLab checks that at least one of the -stored host keys matches before connecting. This can prevent malicious code from -being injected into your mirror, or your password being stolen. - -### SSH public key authentication - -To use SSH public key authentication, you must also choose that option -from the **Authentication method** dropdown. When the mirror is created, -GitLab generates a 4096-bit RSA key that can be copied by selecting the **Copy SSH public key** button. - - +Older versions of SSH may require you to remove `-E md5` from the command. -You then must add the public SSH key to the other repository's configuration: - -- If the other repository is hosted on GitLab, you should add the public SSH key - as a [deploy key](../../../project/deploy_keys/index.md). -- If the other repository is hosted elsewhere, you must add the key to - your user's `authorized_keys` file. Paste the entire public SSH key into the - file on its own line and save it. - -If you must change the key at any time, you can remove and re-add the mirror -to generate a new key. Update the other repository with the new -key to keep the mirror running. - -NOTE: -The generated keys are stored in the GitLab database, not in the file system. Therefore, -SSH public key authentication for mirrors cannot be used in a pre-receive hook. - -## Force an update **(FREE)** - -While mirrors are scheduled to update automatically, you can always force an update by using the -update button which is available on the **Mirroring repositories** section of the **Repository Settings** page. - - - -## Resources +## Related topics - Configure a [Pull Mirroring Interval](../../../../administration/instance_limits.md#pull-mirroring-interval) - [Disable mirrors for a project](../../../admin_area/settings/visibility_and_access_controls.md#enable-project-mirroring) @@ -171,24 +197,33 @@ update button which is available on the **Mirroring repositories** section of th Should an error occur during a push, GitLab displays an **Error** highlight for that repository. Details on the error can then be seen by hovering over the highlight text. -### 13:Received RST_STREAM with error code 2 with GitHub +### Received RST_STREAM with error code 2 with GitHub + +If you receive this message while mirroring to a GitHub repository: + +```plaintext +13:Received RST_STREAM with error code 2 +``` + +Your GitHub settings might be set to block pushes that expose your email address +used in commits. To fix this problem, either: -If you receive a "13:Received RST_STREAM with error code 2" message while mirroring to a GitHub repository, -your GitHub settings might be set to block pushes that expose your email address used in commits. Either -set your email address on GitHub to be public, or disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. +- Set your GitHub email address to public. +- Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. -### 4:Deadline Exceeded +### Deadline Exceeded -When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you +When upgrading to GitLab 11.11.8 or later, a change in how usernames are represented means that you must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. ### Connection blocked because server only allows public key authentication -As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a -[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, -you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. +The connection between GitLab and the remote repository is blocked. Even if a +[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) +is successful, you must check any networking components in the route from GitLab +to the remote server for blockage. -For example, we've seen this error when a Firewall was performing a `Deep SSH Inspection` on outgoing packets. +This error can occur when a firewall performs a `Deep SSH Inspection` on outgoing packets. ### Could not read username: terminal prompts disabled @@ -196,29 +231,31 @@ If you receive this error after creating a new project using [GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/): ```plaintext -"2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': terminal prompts disabled\n": exit status 128." +"2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': +terminal prompts disabled\n": exit status 128." ``` Check if the repository owner is specified in the URL of your mirrored repository: -1. Go to your project. +1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. -1. Select **Mirroring repositories**. -1. If no repository owner is specified, delete and add the URL again in this format: +1. Expand **Mirroring repositories**. +1. If no repository owner is specified, delete and add the URL again in this format, + replacing `OWNER`, `ACCOUNTNAME`, and `REPONAME` with your values: ```plaintext - https://**<repo_owner>**@bitbucket.org/<accountname>/<reponame>.git + https://OWNER@bitbucket.org/ACCOUNTNAME/REPONAME.git ``` -The repository owner is needed for Bitbucket to connect to the repository for mirroring. +When connecting to the repository for mirroring, Bitbucket requires the repository owner in the string. ### Pull mirror is missing LFS files In some cases, pull mirroring does not transfer LFS files. This issue occurs when: - You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. - There is [an issue to fix this for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). + An issue exists [to fix this problem for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). - You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. - This was [fixed in GitLab 14.0.6](https://gitlab.com/gitlab-org/gitlab/-/issues/335123). + [Fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/335123) in GitLab 14.0.6. - You mirror an external repository using object storage. - There is [an issue to fix this](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). + An issue exists [to fix this problem](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index d1943cbfd71..4c437d0f8c8 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -41,7 +41,7 @@ After you configure a GitLab repository as a pull mirror: 1. Sidekiq becomes available to process updates, mirrors are updated. If the update process: - **Succeeds**: An update is enqueued again with at least a 30 minute wait. - **Fails**: The update is attempted again later. After 14 failures, a mirror is marked as a - [hard failure](#hard-failure) and is no longer enqueued for updates. A branch diverging + [hard failure](#fix-hard-failures-when-mirroring) and is no longer enqueued for updates. A branch diverging from its upstream counterpart can cause failures. To prevent branches from diverging, configure [Overwrite diverged branches](#overwrite-diverged-branches) when you create your mirror. @@ -102,7 +102,7 @@ updates are pulled immediately. For more information, read [Start the pull mirroring process for a project](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). -## Hard failure +## Fix hard failures when mirroring > Moved to GitLab Premium in 13.9. @@ -112,7 +112,7 @@ and mirroring attempts stop. This failure is visible in either the: - Project's main dashboard. - Pull mirror settings page. -You can resume the project mirroring again by [forcing an update](index.md#force-an-update). +To resume project mirroring, [force an update](index.md#force-an-update). ## Related topics diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md new file mode 100644 index 00000000000..bbf14a71653 --- /dev/null +++ b/doc/user/project/repository/vscode.md @@ -0,0 +1,47 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab Workflow extension for VS Code **(FREE)** + +The [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +integrates GitLab with Visual Studio Code. You can decrease context switching and +do more day-to-day tasks in Visual Studio Code, such as: + +- [View issues](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-issues-review-mrs). +- Run [common commands](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#commands) + from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). +- Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) + merge requests directly from Visual Studio Code. +- [Validate your GitLab CI configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration). +- [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). +- [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) + 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. + +## Download the extension + +Download the extension from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). + +## Configure the extension + +After you [download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#extension-settings): + +- [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. + +## Report issues with the extension + +Report any issues, bugs, or feature requests in the +[`gitlab-vscode-extension` issue queue](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues). + +## Related topics + +- [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. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 17031dd29af..2db7ae308bd 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -158,7 +158,7 @@ can start signing your tags: git config --global tag.gpgsign true ``` -## Resources +## Related topics - [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 661bd3e0598..6ee23c91680 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -38,7 +38,9 @@ see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) A paginated list of requirements is available in each project, and there you can create a new requirement. -Users with Reporter or higher [permissions](../../permissions.md) can create requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To create a requirement: @@ -66,7 +68,9 @@ next to the requirement title. You can edit a requirement from the requirements list page. -Users with Reporter or higher [permissions](../../permissions.md) can edit requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To edit a requirement: @@ -80,7 +84,9 @@ To edit a requirement: You can archive an open requirement while you're in the **Open** tab. -Users with Reporter or higher [permissions](../../permissions.md) can archive requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To archive a requirement, select **Archive** (**{archive}**). @@ -90,7 +96,9 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab. You can view the list of archived requirements in the **Archived** tab. -Users with Reporter or higher [permissions](../../permissions.md) can reopen archived requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md).  @@ -209,13 +217,13 @@ requirements_confirmation: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. +You must have at least the Reporter [role](../../permissions.md). + You can import requirements to a project by uploading a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) with the columns `title` and `description`. After the import, the user uploading the CSV file is set as the author of the imported requirements. -Users with Reporter or higher [permissions](../../permissions.md) can import requirements. - ### Import the file Before you import your file: @@ -281,7 +289,9 @@ By exporting requirements, you and your team can import them into another tool o your customers. Exporting requirements can aid collaboration with higher-level systems, as well as audit and regulatory compliance tasks. -Users with Reporter or higher [permissions](../../permissions.md) can export requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To export requirements: diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index fa5ef35418a..4f8e068ca2d 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -86,10 +86,10 @@ To improve your project's security, we recommend the following: - [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 with Maintainer (or higher) -[permission level](../permissions.md) -in your GitLab instance. However, when using an email alias externally, an end user -(issue creator) cannot see the internal email address displayed in the information note. +The unique internal email address is visible to project members at least +the Reporter [role](../permissions.md) in your GitLab instance. +An external user (issue creator) cannot see the internal email address +displayed in the information note. ### Using customized email templates @@ -137,15 +137,23 @@ You can use these placeholders to be automatically replaced in each email: #### New Service Desk issues -You can select one [issue description template](description_templates.md#create-an-issue-template) +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. -Issue description templates should reside in your repository's `.gitlab/issue_templates/` directory. -To use a custom issue template with Service Desk, in your project: +You can set description templates at various levels: -1. [Create a description template](description_templates.md#create-an-issue-template) -1. Go to **Settings > General > Service Desk**. -1. From the dropdown **Template to append to all Service Desk issues**, select your template. +- The entire [instance](description_templates.md#set-instance-level-description-templates). +- A specific [group or subgroup](description_templates.md#set-group-level-description-templates). +- A specific [project](description_templates.md#set-a-default-template-for-merge-requests-and-issues). + +The templates are inherited. For example, in a project, you can also access templates set for the instance or the project’s parent groups. + +To use a custom description template with Service Desk: + +1. On the top bar, select **Menu > Projects** and find your project. +1. [Create a description template](description_templates.md#create-an-issue-template). +1. On the left sidebar, select **Settings > General > Service Desk**. +1. From the dropdown **Template to append to all Service Desk issues**, search or select your template. ### Using a custom email display name @@ -156,7 +164,8 @@ this name in the `From` header. The default display name is `GitLab Support Bot` To edit the custom email display name: -1. In a project, go to **Settings > General > Service Desk**. +1. On the top bar, select **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**. @@ -166,13 +175,13 @@ To edit the custom email display name: > - [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 -both a [custom mailbox](#configuring-a-custom-mailbox) and a +a [custom mailbox](#configuring-a-custom-mailbox). If you want you can also configure a [custom suffix](#configuring-a-custom-email-address-suffix). #### Configuring a custom mailbox NOTE: -On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, so you only have to configure the +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. Using the `service_desk_email` configuration, you can customize the mailbox @@ -198,7 +207,7 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip service_desk_email: enabled: true address: "project_contact+%{key}@example.com" - user: "project_support@example.com" + user: "project_contact@example.com" password: "[REDACTED]" host: "imap.gmail.com" port: 993 @@ -215,7 +224,7 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip ```ruby gitlab_rails['service_desk_email_enabled'] = true gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" - gitlab_rails['service_desk_email_email'] = "project_support@gmail.com" + gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" gitlab_rails['service_desk_email_password'] = "[REDACTED]" gitlab_rails['service_desk_email_mailbox_name'] = "inbox" gitlab_rails['service_desk_email_idle_timeout'] = 60 @@ -271,6 +280,8 @@ For example, suppose the `mygroup/myproject` project Service Desk settings has t The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. The [incoming email](../../administration/incoming_email.md) address still works. +If you don't configure the custom suffix, the default project identification will be used for identifying the project. You can see that email address in the project settings. + ## Using 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). diff --git a/doc/user/project/settings/img/general_settings_v13_11.png b/doc/user/project/settings/img/general_settings_v13_11.png Binary files differdeleted file mode 100644 index 9da5acdf82e..00000000000 --- a/doc/user/project/settings/img/general_settings_v13_11.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_download_export.png b/doc/user/project/settings/img/import_export_download_export.png Binary files differindex c7ab7565fc7..62292e99e8e 100644 --- a/doc/user/project/settings/img/import_export_download_export.png +++ b/doc/user/project/settings/img/import_export_download_export.png diff --git a/doc/user/project/settings/img/import_export_export_button.png b/doc/user/project/settings/img/import_export_export_button.png Binary files differindex 6933e3edfcc..6f3663d64e8 100644 --- a/doc/user/project/settings/img/import_export_export_button.png +++ b/doc/user/project/settings/img/import_export_export_button.png diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 6c3bf731cf8..74879dae2d6 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -2,7 +2,6 @@ stage: Manage group: Import info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, howto --- # Project import/export **(FREE)** @@ -159,7 +158,9 @@ To export a project and its data, follow these steps: 1. Go to your project's homepage. -1. Click **Settings** in the sidebar. +1. Select **Settings** in the sidebar. + +1. Scroll down and expand the **Advanced** section. 1. Scroll down to find the **Export project** button: @@ -178,12 +179,14 @@ To export a project and its data, follow these steps: ## Import the project +> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. + WARNING: Only import projects from sources you trust. If you import a project from an untrusted source, it may be possible for an attacker to steal your sensitive data. 1. The GitLab project import feature is the first import option when creating a - new project. Click on **GitLab export**: + new project. Select **GitLab export**:  @@ -191,7 +194,7 @@ may be possible for an attacker to steal your sensitive data.  -1. Click on **Import project** to begin importing. Your newly imported project +1. Select **Import project** to begin importing. Your newly imported project page appears shortly. NOTE: @@ -199,9 +202,8 @@ If use of the `Internal` visibility level [is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. -NOTE: -The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. +The maximum import file size can be set by the Administrator, and the default is `0` (unlimited). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). ### Project import status @@ -224,6 +226,11 @@ To help avoid abuse, by default, users are rate limited to: GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. +## 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). + ## Troubleshooting ### Project fails to import due to mismatch @@ -233,15 +240,18 @@ does not match between the exported project, and the project import, the project Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and either: - Ensure shared runners are enabled in both the source and destination projects. -- Disable shared runners on the parent group when you import the project. +- Disable shared runners on the parent group when you import the project. -### Import workaround for large repositories +### Import workarounds for large repositories [Maximum import size limitations](#import-the-project) -can prevent an import from being successful. -If changing the import limits is not possible, -the following local workflow can be used to temporarily -reduce the repository size for another import attempt. +can prevent an import from being successful. If changing the import limits is not possible, you can +try one of the workarounds listed here. + +#### Workaround option 1 + +The following local workflow can be used to temporarily +reduce the repository size for another import attempt: 1. Create a temporary working directory from the export: @@ -291,6 +301,58 @@ reduce the repository size for another import attempt. delete the temporary, `smaller-tmp-main` branch, and the local, temporary data. +#### Workaround option 2 + +Rather than attempting to push all changes at once, this workaround: + +- Separates the project import from the Git Repository import +- Incrementally pushes the repository to GitLab + +1. Make a local clone of the repository to migrate. In a later step, you push this clone outside of + the project export. +1. Download the export and remove the `project.bundle` (which contains the Git repository): + + ```shell + tar -czvf new_export.tar.gz --exclude='project.bundle' @old_export.tar.gz + ``` + +1. Import the export without a Git repository. It asks you to confirm to import without a + repository. +1. Save this bash script as a file and run it after adding the appropriate origin. + + ```shell + #!/bin/sh + + # ASSUMPTIONS: + # - The GitLab location is "origin" + # - The default branch is "main" + # - This will attempt to push in chunks of 500MB (dividing the total size by 500MB). + # Decrease this size to push in smaller chunks if you still receive timeouts. + + git gc + SIZE=$(git count-objects -v 2> /dev/null | grep size-pack | awk '{print $2}') + + # Be conservative... and try to push 2GB at a time + # (given this assumes each commit is the same size - which is wrong) + BATCHES=$(($SIZE / 500000)) + TOTAL_COMMITS=$(git rev-list --count HEAD) + if (( BATCHES > TOTAL_COMMITS )); then + BATCHES=$TOTAL_COMMITS + fi + + INCREMENTS=$(( ($TOTAL_COMMITS / $BATCHES) - 1 )) + + for (( BATCH=BATCHES; BATCH>=1; BATCH-- )) + do + COMMIT_NUM=$(( $BATCH - $INCREMENTS )) + COMMIT_SHA=$(git log -n $COMMIT_NUM --format=format:%H | tail -1) + git push -u origin ${COMMIT_SHA}:refs/heads/main + done + git push -u origin main + git push -u origin -—all + git push -u origin -—tags + ``` + ### Manually execute export steps Exports sometimes fail without giving enough information to troubleshoot. In these cases, it can be diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 30def6ae80f..5c4d4649240 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -28,12 +28,32 @@ functionality of a project. Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics: - - The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +#### Topics + +Use topics to categorize projects and find similar new projects. + +To assign topics to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings** > **General**. +1. Under **Topics**, enter the project topics. Existing popular topics are suggested as you type. +1. Select **Save changes**. + +For GitLab.com, explore popular topics on the [Explore topics page](../working_with_projects.md#explore-topics). +When you select a topic, you can see relevant projects. + +NOTE: +The assigned topics are visible only to everyone with access to the project, +but everyone can see which topics exist at all on the GitLab instance. +Do not include sensitive information in the name of a topic. + +If you're an instance administrator, see also +[Administering topics](../../admin_area/index.md#administering-topics). + #### Compliance frameworks **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. @@ -157,7 +177,9 @@ audit trail: include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch. + ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch + rules: + - exists: '$CI_CONFIG_PATH' ``` ##### Ensure compliance jobs are always run @@ -236,7 +258,7 @@ Use the switches to enable or disable the following features: | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | | **Pages** | ✓ | Allows you to [publish static websites](../pages/). | -| **Operations** | ✓ | Control access to [operations dashboard](../../../operations/index.md). | +| **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | | **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | Some features depend on others: @@ -293,6 +315,7 @@ Set up your project's merge request settings: - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). +- Configure [merge commit message template](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cae9276eafd..85e412e7a41 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -10,6 +10,7 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md) except they are attached to a project rather than a user. They can be used to: @@ -32,6 +33,9 @@ Project access tokens: For examples of how you can use a project access token to authenticate with the API, see the [relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens). +NOTE: +For GitLab.com and self-managed instances, the default prefix is `glpat-`. + ## Creating a project access token 1. Log in to GitLab. @@ -58,7 +62,9 @@ For the bot: - The name is set to the name of the token. - The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. -- The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. +- The email is set to `project{project_id}_bot@example.com`, for example `project123_bot@example.com`. +- For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`, for example `project_123_bot1`. +- For additional acess tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`, for example `project123_bot1@example.com` API calls made with a project access token are associated with the corresponding bot user. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 71cf0c03549..d75a180492e 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -15,7 +15,8 @@ projects by providing an advanced editor with commit staging. ## Open the Web IDE -You can open the Web IDE when viewing a file, from the repository file list, +Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md) to open the Web IDE. +You can also open the Web IDE when viewing a file, from the repository file list, and from merge requests: - *When viewing a file, or the repository file list* - @@ -100,12 +101,13 @@ same core features for highlighting and linking to particular lines in the edite ## Schema based validation -> - Support for validation based on predefined schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. -> - It was deployed behind a feature flag, disabled by default. -> - It's enabled on GitLab.com. -> - It cannot be enabled or disabled per-project. -> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-validation-based-on-predefined-schemas). -> - Support for validation based on custom schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) validation based on predefined schemas in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `schema_linting`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `schema_linting`. +This feature cannot be enabled or disabled per-project. +On GitLab.com, this feature is available. +You should not use this feature for production environments. The Web IDE provides validation support for certain JSON and YAML files using schemas based on the [JSON Schema Store](https://www.schemastore.org/json/). @@ -115,28 +117,9 @@ based on the [JSON Schema Store](https://www.schemastore.org/json/). The Web IDE has validation for certain files built in. This feature is only supported for the `*.gitlab-ci.yml` files. -#### Enable or disable validation based on predefined schemas **(FREE SELF)** - -Validation based on predefined schemas is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default** for self-managed instances, -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:schema_linting) -``` - -To disable it: - -```ruby -Feature.disable(:schema_linting) -``` - ### Custom schemas **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in GitLab 13.4. The Web IDE also allows you to define custom schemas for certain JSON/YAML files in your project. You can do so by defining a `schemas` entry in the `.gitlab/.gitlab-webide.yml` file inside the diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md new file mode 100644 index 00000000000..731fed2595a --- /dev/null +++ b/doc/user/project/wiki/group.md @@ -0,0 +1,71 @@ +--- +stage: Create +group: Editor +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, how-to +--- + +# Group wikis **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. + +If you use GitLab groups to manage multiple projects, some of your documentation +might span multiple groups. You can create group wikis, instead of [project wikis](index.md), +to ensure all group members have the correct access permissions to contribute. +Group wikis are similar to [project wikis](index.md), with a few limitations: + +- [Git LFS](../../../topics/git/lfs/index.md) is not supported. +- Group wikis are not included in [global search](../../search/advanced_search.md). +- Changes to group wikis don't show up in the [group's activity feed](../../group/index.md#group-activity-analytics). +- Group wikis are enabled by default for **(PREMIUM)** and higher tiers. + You [can't turn them off from the GitLab user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/208413). + +For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). + +Similar to project wikis, group members with the [Developer role](../../permissions.md#group-members-permissions) +and higher can edit group wikis. Group wiki repositories can be moved using the +[Group repository storage moves API](../../../api/group_repository_storage_moves.md). + +## View a group wiki + +To access a group wiki: + +1. On the top bar, select **Menu > Groups** and find your group. +1. To display the wiki, either: + - On the left sidebar, select **Wiki**. + - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> + [wiki keyboard shortcut](../../shortcuts.md). + +## Export a group wiki + +> Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247). + +Users with the [Owner role](../../permissions.md) in a group can +[import and export group wikis](../../group/settings/import_export.md) when importing +or exporting a group. + +Content created in a group wiki is not deleted when an account is downgraded or a +GitLab trial ends. The group wiki data is exported whenever the group owner of +the wiki is exported. + +To access the group wiki data from the export file if the feature is no longer +available, you have to: + +1. Extract the [export file tarball](../../group/settings/import_export.md) with + this command, replacing `FILENAME` with your file's name: + `tar -xvzf FILENAME.tar.gz` +1. Browse to the `repositories` directory. This directory contains a + [Git bundle](https://git-scm.com/docs/git-bundle) with the extension `.wiki.bundle`. +1. Clone the Git bundle into a new repository, replacing `FILENAME` with + your bundle's name: `git clone FILENAME.wiki.bundle` + +All files in the wiki are available in this Git repository. + +## Related topics + +- [Wiki settings for administrators](../../../administration/wikis/index.md) +- [Project wikis API](../../../api/wikis.md) +- [Group repository storage moves API](../../../api/group_repository_storage_moves.md) +- [Group wikis API](../../../api/group_wikis.md) +- [Wiki keyboard shortcuts](../../shortcuts.md#wiki-pages) +- [Epic: Feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782) diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index e2a8167b14c..5d2a0530f68 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -12,16 +12,6 @@ to keep it in the same project as your code, you can use the wiki GitLab provide in each GitLab project. Every wiki is a separate Git repository, so you can create wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). -To access the wiki for a project or group, go to the page for your project or group -and either: - -- In the left sidebar, select **Wiki**. -- On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> - [wiki keyboard shortcut](../../shortcuts.md). - -If **Wiki** is not listed in the left sidebar of your project, a project administrator -has [disabled it](#enable-or-disable-a-project-wiki). - GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. Wiki pages written in Markdown support all [Markdown features](../../markdown.md), and also provide some [wiki-specific behavior](../../markdown.md#wiki-specific-markdown) @@ -35,6 +25,19 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se  +## View a project wiki + +To access a project wiki: + +1. On the top bar, select **Menu > Projects** and find your project. +1. To display the wiki, either: + - On the left sidebar, select **Wiki**. + - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> + [wiki keyboard shortcut](../../shortcuts.md). + +If **Wiki** is not listed in the left sidebar of your project, a project administrator +has [disabled it](#enable-or-disable-a-project-wiki). + ## Configure a default branch for your wiki > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221159) in GitLab 14.1. @@ -56,7 +59,10 @@ When a wiki is created, it is empty. On your first visit, you can create the home page users see when viewing the wiki. This page requires a specific title to be used as your wiki's home page. To create it: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Select **Create your first page**. 1. GitLab requires this first page be titled `home`. The page with this title serves as the front page for your wiki. @@ -71,7 +77,10 @@ to be used as your wiki's home page. To create it: Users with the [Developer role](../../permissions.md) can create new wiki pages: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. 1. Add a title for your new page. Page titles use @@ -135,7 +144,10 @@ may not be able to check out the wiki locally afterward. You need at least the [Developer role](../../permissions.md) to edit a wiki page: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the page you want to edit, and either: - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). - Select the edit icon (**{pencil}**). @@ -151,7 +163,10 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the [Developer role](../../permissions.md) to delete a wiki page: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the page you want to delete. 1. Select the edit icon (**{pencil}**). 1. Select **Delete page**. @@ -161,7 +176,10 @@ You need at least the [Developer role](../../permissions.md) to delete a wiki pa You need at least the [Developer role](../../permissions.md) to move a wiki page: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. For example, if you have a wiki page @@ -172,9 +190,7 @@ You need at least the [Developer role](../../permissions.md) to move a wiki page ## View history of a wiki page The changes of a wiki page over time are recorded in the wiki's Git repository. -To view the changes for a wiki page, select **Page history**. - -From the history page you can see: +The history page shows:  @@ -184,13 +200,25 @@ From the history page you can see: - The last update. - Previous revisions, by selecting a revision number in the **Page version** column. +To view the changes for a wiki page: + +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. +1. Go to the page you want to view history for. +1. Select **Page history**. + ### View changes between page versions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in. @@ -203,10 +231,12 @@ You can see the changes made in a version of a wiki page, similar to versioned d > - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** -GitLab tracks wiki creation, deletion, and update events. These events are displayed on the -[user profile](../../profile/index.md#access-your-user-profile), -[group](../../group/index.md#view-group-activity), -and [project](../working_with_projects.md#project-activity) activity pages. +GitLab tracks wiki creation, deletion, and update events. These events are displayed on these pages: + +- [User profile](../../profile/index.md#access-your-user-profile). +- Activity pages, depending on the type of wiki: + - [Group activity](../../group/index.md#view-group-activity). + - [Project activity](../working_with_projects.md#project-activity). Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). @@ -218,7 +248,10 @@ You need at least the [Developer role](../../permissions.md) to customize the wi navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. In the top right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -241,42 +274,20 @@ Support for displaying a generated table of contents with a custom side navigati ## Enable or disable a project wiki Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) -can enable or disable the project wiki by following the instructions in +can enable or disable a project wiki by following the instructions in [Sharing and permissions](../settings/index.md#sharing-and-permissions). Administrators for self-managed GitLab installs can [configure additional wiki settings](../../../administration/wikis/index.md). -## Group wikis **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. - -Group wikis work the same way as project wikis. Their usage is similar to project -wikis, with a few limitations: - -- Git LFS is not supported. -- Group wikis are not included in global search. -- Changes to group wikis don't show up in the group's activity feed. - -For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). - -Group wikis can be edited by members with the [Developer role](../../permissions.md#group-members-permissions) -and above. Group wiki repositories can be moved using the -[Group repository storage moves API](../../../api/group_repository_storage_moves.md). - -### Export a group wiki **(PREMIUM)** - -Users with the [Owner role](../../permissions.md) in a group can -[import and export group wikis](../../group/settings/import_export.md) when importing -or exporting a group. - -Content created in a group wiki is not deleted when an account is downgraded or a GitLab trial ends. +You can't disable [group wikis](group.md) from the GitLab user interface. ## Link an external wiki To add a link to an external wiki from a project's left sidebar: -1. Go to your project and select **Settings > Integrations**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. 1. (Optional) Select **Test settings** to verify the connection. @@ -291,7 +302,8 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. Go to your project and select **Settings > Integrations**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. In the **Enable integration** section, clear the **Active** checkbox. 1. Select **Save changes**. @@ -300,6 +312,7 @@ To hide the link to an external wiki: To disable a project's internal wiki: +1. On the top bar, select **Menu > Projects** and find your project. 1. Go to your project and select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). @@ -356,7 +369,7 @@ For the status of the ongoing development for CommonMark and GitLab Flavored Mar - [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. - [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. -## Resources +## Related topics - [Wiki settings for administrators](../../../administration/wikis/index.md) - [Project wikis API](../../../api/wikis.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 11b570f19e5..3c82e544e26 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -13,7 +13,7 @@ code are saved in projects, and most features are in the scope of projects. You can explore other popular projects available on GitLab. To explore projects: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Explore projects**. GitLab displays a list of projects, sorted by last updated date. To view @@ -25,12 +25,27 @@ By default, `/explore` is visible to unauthenticated users. However, if the [**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) is restricted, `/explore` is visible only to signed-in users. +## Explore topics + +You can explore popular project topics available on GitLab. To explore project topics: + +1. On the top bar, select **Menu > Projects**. +1. Select **Explore topics**. + +GitLab displays a list of topics sorted by the number of associated projects. +To view projects associated with a topic, select a topic from the list. + +You can assign topics to a project on the [Project Settings page](settings/index.md#topics). + +If you're an instance administrator, you can administer all project topics from the +[Admin Area's Topics page](../admin_area/index.md#administering-topics). + ## Create a project To create a project in GitLab: -1. In your dashboard, click the green **New project** button or use the plus - icon in the navigation bar. This opens the **New project** page. +1. In your dashboard, select **New project** or use the **New...** **{plus-square}** icon +on the top bar. The **New project** page opens. 1. On the **New project** page, choose if you want to: - Create a [blank project](#blank-projects). - Create a project using one of the available [project templates](#project-templates). @@ -213,7 +228,7 @@ To star a project: To view your starred projects: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Starred Projects**. 1. GitLab displays information about your starred projects, including: diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index a8107d77113..810e1427e11 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -19,6 +19,7 @@ You can report a user through their: - [Profile](#reporting-abuse-through-a-users-profile) - [Comments](#reporting-abuse-through-a-users-comment) - [Issues and Merge requests](#reporting-abuse-through-a-users-issue-or-merge-request) +- [Snippets](snippets.md#mark-snippet-as-spam) ## Reporting abuse through a user's profile diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index f994539b9fc..f68951badff 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -26,7 +26,7 @@ when searching in: - Comments - Code - Commits -- Wiki +- Wiki (except [group wikis](../project/wiki/group.md)) - Users The Advanced Search can be useful in various scenarios: @@ -139,4 +139,4 @@ its performance: | Commits | `global_search_commits_tab` | When enabled, the global search includes commits as part of the search. | | Issues | `global_search_issues_tab` | When enabled, the global search includes issues as part of the search. | | Merge Requests | `global_search_merge_requests_tab` | When enabled, the global search includes merge requests as part of the search. | -| Wiki | `global_search_wiki_tab` | When enabled, the global search includes wiki as part of the search. | +| Wiki | `global_search_wiki_tab` | When enabled, the global search includes wiki as part of the search. [Group wikis](../project/wiki/group.md) are not included. | diff --git a/doc/user/search/img/basic_search.png b/doc/user/search/img/basic_search_v14_4.png Binary files differindex 86aab68f1f0..86aab68f1f0 100644 --- a/doc/user/search/img/basic_search.png +++ b/doc/user/search/img/basic_search_v14_4.png diff --git a/doc/user/search/img/issues_mrs_shortcut.png b/doc/user/search/img/issues_mrs_shortcut.png Binary files differdeleted file mode 100644 index 5be8079030a..00000000000 --- a/doc/user/search/img/issues_mrs_shortcut.png +++ /dev/null diff --git a/doc/user/search/img/issues_mrs_shortcut_v14_4.png b/doc/user/search/img/issues_mrs_shortcut_v14_4.png Binary files differnew file mode 100644 index 00000000000..2610e611446 --- /dev/null +++ b/doc/user/search/img/issues_mrs_shortcut_v14_4.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 7cf62f09303..325e5386417 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -35,7 +35,7 @@ You can also filter the results using the search and filter field, as described GitLab shows shortcuts to issues and merge requests created by you or assigned to you in the search field in the upper right corner: - + ### Filter issue and merge request lists @@ -118,7 +118,7 @@ You can add this URL to your feed reader. You can filter the **Issues** list to individual instances by their ID. For example, enter filter `#10` to return only issue 10. The same applies to the **Merge Requests** list. Enter filter `#30` to return only merge request 30. - + ### Filtering merge requests by approvers **(PREMIUM)** @@ -290,7 +290,7 @@ To start a search, type into the search bar on the top-right of the screen. You in all GitLab and may also see the options to search in a group or project if you are in the group or project dashboard. - + After the results are returned, you can modify the search, select a different type of data to search, or choose a specific group or project. @@ -321,9 +321,10 @@ GitLab instance. ## Search settings -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8 behind a feature flag, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8 [with a flag](../../administration/feature_flags.md) named `search_settings_in_page`. Disabled by default. > - [Added to Group, Administrator, and User settings](https://gitlab.com/groups/gitlab-org/-/epics/4842) in GitLab 13.9. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. +> - [Feature flag `search_settings_in_page` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. You can search inside a Project, Group, Administrator, or User's settings by entering a search term in the search box located at the top of the page. The search results diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index f46c5428248..d6cbbf352fc 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -43,6 +43,7 @@ These shortcuts are available in most areas of GitLab: | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. | | <kbd>p</kbd> + <kbd>b</kbd> | Show or hide the Performance Bar. | | <kbd>g</kbd> + <kbd>x</kbd> | Toggle between [GitLab](https://gitlab.com/) and [GitLab Next](https://next.gitlab.com/) (GitLab SaaS only). | +| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | Additionally, the following shortcuts are available when editing text in text fields (for example, comments, replies, issue descriptions, and merge request @@ -101,6 +102,7 @@ These shortcuts are available when viewing issues and [merge requests](project/m | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (merge requests only). | | <kbd>[</kbd> or <kbd>k</kbd> | Move to previous file (merge requests only). | | <kbd>b</kbd> | Copy source branch name (merge requests only). | +| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | ### Project files @@ -114,6 +116,7 @@ These shortcuts are available when browsing the files in a project (go to | <kbd>enter</kbd> | Open selection. | | <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Repository > Files**, then select **Find File**). | | <kbd>y</kbd> | Go to file permalink (only while viewing a file). | +| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | ### Web IDE diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 64da024f5ba..e2cb9937f76 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -14,6 +14,9 @@ You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and [syntax highlighting](#filenames), [embedding](#embed-snippets), [downloading](#download-snippets), and you can maintain your snippets with the [snippets API](../api/snippets.md). +You can create and manage your snippets through the GitLab user interface, or by +using the [GitLab Workflow VS Code extension](project/repository/vscode.md). +  GitLab provides two types of snippets: @@ -39,6 +42,8 @@ You can create snippets in multiple ways, depending on whether you want to creat - *For all other pages,* select the plus icon (**{plus-square-o}**) in the top navigation bar, then select **New snippet** from the dropdown menu. + - If you installed the [GitLab Workflow VS Code extension](project/repository/vscode.md), + use the [`Gitlab: Create snippet` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet). - **To create a project snippet**: Go to your project's page. Select the plus icon (**{plus-square-o}**), and then select **New snippet** from the **This project** section of the dropdown menu. @@ -127,7 +132,7 @@ A single snippet can support up to 10 files, which helps keep related files toge If you need more than 10 files for your snippet, we recommend you create a [wiki](project/wiki/index.md) instead. Wikis are available for projects at all -subscription levels, and [groups](project/wiki/index.md#group-wikis) for +subscription levels, and [groups](project/wiki/group.md) for [GitLab Premium](https://about.gitlab.com/pricing/). Snippets with multiple files display a file count in the [snippet list](https://gitlab.com/dashboard/snippets): @@ -206,6 +211,24 @@ snippet was created using the GitLab web interface the original line ending is W With snippets, you engage in a conversation about that piece of code, which can encourage user collaboration. +## Mark snippet as spam **(FREE SELF)** + +Administrators on self-managed GitLab instances can mark snippets as spam. + +Prerequisites: + +- You must be the administrator for your instance. +- [Akismet](../integration/akismet.md) spam protection must be enabled on the instance. + +To do this task: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Snippets**. +1. Select the snippet you want to report as spam. +1. Select **Submit as spam**. + +GitLab forwards the spam to Akismet. + ## Troubleshooting ### Snippet limitations diff --git a/doc/user/tasks.md b/doc/user/tasks.md new file mode 100644 index 00000000000..e5e5510407e --- /dev/null +++ b/doc/user/tasks.md @@ -0,0 +1,34 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Tasks **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default. + +WARNING: +Tasks are in **Alpha**. Current implementation does not have any API requests and works with mocked data. +For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitlab-org/-/epics/7103). + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `work_items`. +The feature is not ready for production use. + +Use tasks to track steps needed for the [issue](project/issues/index.md) to be closed. + +When planning an issue, you need a way to capture and break down technical +requirements or steps necessary to complete it. An issue with tasks is better defined, +and so you can provide a more accurate issue weight and completion criteria. + +To see the roadmap for migrating issues and [epics](group/epics/index.md) +to work items and adding custom work item types, visit +[epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or +[Plan direction page](https://about.gitlab.com/direction/plan/). + +## View a task + +The only way to view a task is to open it with a deep link, +for example: `/<group_name>/<project_name>/-/work_item/1` diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 5a48353c9d4..16b6424b232 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -36,9 +36,8 @@ namespace to recalculate the storage. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68898) project-level graph in GitLab 14.4 [with a flag](../administration/feature_flags.md) named `project_storage_ui`. Disabled by default. > - Enabled on GitLab.com in GitLab 14.4. - -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 `project_storage_ui`. On GitLab.com, this feature is available. +> - Enabled on self-managed in GitLab 14.5. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71270) in GitLab 14.5. The following storage usage statistics are available to an owner: diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index d75d91f087d..8ca7f7defb2 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -46,3 +46,7 @@ The following provide a preview to the Workspace concept.   + +## Related topics + +- [Workspaces developer documentation](../../development/workspaces/index.md) |
