diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-08-20 21:42:06 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-08-20 21:42:06 +0300 |
| commit | 6e4e1050d9dba2b7b2523fdd1768823ab85feef4 (patch) | |
| tree | 78be5963ec075d80116a932011d695dd33910b4e /doc/user | |
| parent | 1ce776de4ae122aba3f349c02c17cebeaa8ecf07 (diff) | |
Add latest changes from gitlab-org/gitlab@13-3-stable-ee
Diffstat (limited to 'doc/user')
368 files changed, 3490 insertions, 2131 deletions
diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 783aadc0974..0283f1a9eff 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -12,6 +12,14 @@ View and resolve abuse reports from GitLab users. GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse reports in the Admin Area. +## Receiving notifications of abuse reports + +To receive notifications of new abuse reports by e-mail, follow these steps: + +1. Select **Admin Area > Settings > Reporting**. +1. Expand the **Abuse reports** section. +1. Provide an email address. + ## Reporting abuse To find out more about reporting abuse, see [abuse reports user diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index d194ca42215..f39e5b198e7 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Project Management +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/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png b/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png Binary files differindex c6ca2bac83c..fe85d567a57 100644 --- a/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png +++ b/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index e63d0c7c882..8aa50bb0496 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -59,13 +59,13 @@ The Dashboard is the default view of the Admin Area, and is made up of the follo ## Overview section -The following topics document the **{overview}** **Overview** section of the Admin Area. +The following topics document the **Overview** section of the Admin Area. ### Administering Projects You can administer all projects in the GitLab instance from the Admin Area's Projects page. -To access the Projects page, go to **{admin}** **Admin Area >** **{overview}** **Overview > Projects**. +To access the Projects page, go to **Admin Area > Overview > Projects**. Click the **All**, **Private**, **Internal**, or **Public** tab to list only projects of that criteria. @@ -105,7 +105,7 @@ You can combine the filter options. For example, to list only public projects wi You can administer all users in the GitLab instance from the Admin Area's Users page. -To access the Users page, go to **{admin}** **Admin Area >** **{overview}** **Overview > Users**. +To access the Users page, go to **Admin Area > Overview > Users**. To list users matching a specific criteria, click on one of the following tabs on the **Users** page: @@ -157,7 +157,7 @@ reflected in the statistics. You can administer all groups in the GitLab instance from the Admin Area's Groups page. -To access the Groups page, go to **{admin}** **Admin Area >** **{overview}** **Overview > Groups**. +To access the Groups page, go to **Admin Area > Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, number of members, and whether the group is private, internal, or public. To edit a group, click @@ -176,7 +176,7 @@ To [Create a new group](../group/index.md#create-a-new-group) click **New group* You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. -To access the Jobs page, go to **{admin}** **Admin Area >** **{overview}** **Overview > Jobs**. +To access the Jobs page, go to **Admin Area > Overview > Jobs**. All jobs are listed, in descending order of job ID. @@ -201,7 +201,7 @@ For each job, the following details are listed: You can administer all Runners in the GitLab instance from the Admin Area's **Runners** page. See [GitLab Runner](https://docs.gitlab.com/runner/) for more information on Runner itself. -To access the **Runners** page, go to **{admin}** **Admin Area >** **{overview}** **Overview > Runners**. +To access the **Runners** page, go to **Admin Area > Overview > Runners**. The **Runners** page features: @@ -247,7 +247,7 @@ You can also edit, pause, or remove each Runner. You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** page. For more details, see [Gitaly](../../administration/gitaly/index.md). -To access the **Gitaly Servers** page, go to **{admin}** **Admin Area >** **{overview}** **Overview > Gitaly Servers**. +To access the **Gitaly Servers** page, go to **Admin Area > Overview > Gitaly Servers**. For each Gitaly server, the following details are listed: @@ -261,7 +261,7 @@ For each Gitaly server, the following details are listed: ## Monitoring section -The following topics document the **{monitor}** **Monitoring** section of the Admin Area. +The following topics document the **Monitoring** section of the Admin Area. ### System Info diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index c5e29612596..2c849db66b1 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -102,6 +102,14 @@ In order to get back all the previous functionality, a new license must be uploa To fall back to having only the Core features active, you'll need to delete the expired license(s). +### Remove a license + +To remove a license from a self-managed instance: + +1. Go to the [Admin Area](index.md) (click the wrench in the top navigation bar). +1. Click **License** in the left sidebar. +1. Click **Remove License**. + ## License history It's possible to upload and view more than one license, diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 6d9d634ce14..8f51c03e105 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -15,7 +15,7 @@ if they are enabled at an instance level. To enable merge request approval rules for an instance: -1. Navigate to **{admin}** **Admin Area >** **{push-rules}** **Push Rules** and expand **Merge +1. Navigate to **Admin Area >** **{push-rules}** **Push Rules** and expand **Merge requests approvals**. 1. Set the required rule. 1. Click **Save changes**. 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 167016f1cb5..4651a548ff9 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference --- @@ -26,20 +29,6 @@ If you choose a size larger than what is currently configured for the web server you will likely get errors. See the [troubleshooting section](#troubleshooting) for more details. -## Maximum namespace storage size - -This sets a maximum size limit on each namespace. The following are included in the namespace size: - -- Repository -- Wiki -- LFS objects -- Build artifacts -- Packages -- Snippets - -NOTE: **Note:** -This limit is not currently enforced but will be in a future release. - ## Repository size limit **(STARTER ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/740) in [GitLab Enterprise Edition 8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#limit-project-size-ee). @@ -86,7 +75,8 @@ The first push of a new project, including LFS objects, will be checked for size and **will** be rejected if the sum of their sizes exceeds the maximum allowed repository size. -**Note:** The repository size limit includes repository files and LFS, and does not include artifacts. +NOTE: **Note:** +The repository size limit includes repository files and LFS, and does not include artifacts. For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). @@ -159,19 +149,19 @@ To do this: ### Enable or disable optional enforcement of Personal Access Token expiry Feature **(CORE ONLY)** -Optional Enforcement of Personal Access Token Expiry is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. +Optional Enforcement of Personal Access Token Expiry is deployed behind a feature flag and is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it for your instance from the [rails console](../../../administration/feature_flags.md#start-the-gitlab-rails-console). To enable it: ```ruby -Feature.enable(:enforce_personal_access_token_expiration) +Feature.enable(:enforce_pat_expiration) ``` To disable it: ```ruby -Feature.disable(:enforce_personal_access_token_expiration) +Feature.disable(:enforce_pat_expiration) ``` ## Disabling user profile name changes **(PREMIUM ONLY)** diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 68f359368f0..2003d02c9b3 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -1,4 +1,8 @@ --- +stage: Create +group: Gitaly +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" +type: reference type: reference --- diff --git a/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png b/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png Binary files differindex 78c94b3803c..76015ce0ee3 100644 --- a/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png +++ b/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 8c1e82f838b..db6dbb7f38b 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -4,7 +4,7 @@ type: index # Admin Area settings **(CORE ONLY)** -As an administrator of a GitLab self-managed instance, you can manage the behavior of your deployment. To do so, select **{admin}** **Admin Area > Settings**. +As an administrator of a GitLab self-managed instance, you can manage the behavior of your deployment. To do so, select **Admin Area > Settings**. 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) @@ -12,8 +12,7 @@ documentation for all current settings and limits on the GitLab.com instance. ## General -Access the default page for admin area settings by navigating to -**{admin}** **Admin Area > Settings > General**: +Access the default page for admin area settings by navigating to **Admin Area > Settings > General**: | Option | Description | | ------ | ----------- | @@ -62,7 +61,7 @@ Access the default page for admin area settings by navigating to | ------ | ----------- | | [Continuous Integration and Deployment](continuous_integration.md) | Auto DevOps, runners and job artifacts. | | [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration-premium-only) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration will be run after the project's own configuration. | -| [Package Registry](continuous_integration.md#package-registry-configuration-premium-only) **(PREMIUM ONLY)**| Settings related to the use and experience of using GitLab's Package Registry. Note there are [risks involved](./../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | +| [Package Registry](continuous_integration.md#package-registry-configuration-premium-only) | Settings related to the use and experience of using GitLab's Package Registry. Note there are [risks involved](./../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | ## Reporting @@ -90,13 +89,13 @@ Access the default page for admin area settings by navigating to | [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. | | [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](../../incident_management/index.md) Limits | Configure limits on the number of inbound alerts able to be sent to a project. | +| [Incident Management](../../../operations/incident_management/index.md) Limits | Configure limits on the number of inbound alerts able to be sent to a project. | ## Geo | Option | Description | | ------ | ----------- | -| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **{admin}** **Admin Area >** **{location-dot}** **Geo >** **{settings}** **Settings**, and will no longer be available at **{admin}** **Admin Area >** **{settings}** **Settings >** **{location-dot}** **Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | +| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings**, and will no longer be available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | ## Preferences diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index ae56c67f0ab..97380b93295 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference --- @@ -30,12 +33,13 @@ Templates must be added to a specific subdirectory in the repository, corresponding to the kind of template. The following types of custom templates are supported: -| Type | Directory | Extension | -| :---------------: | :-----------: | :-----------: | -| `Dockerfile` | `Dockerfile` | `.dockerfile` | -| `.gitignore` | `gitignore` | `.gitignore` | -| `.gitlab-ci.yml` | `gitlab-ci` | `.yml` | -| `LICENSE` | `LICENSE` | `.txt` | +| Type | Directory | Extension | +| :---------------: | :-----------: | :-----------: | +| `Dockerfile` | `Dockerfile` | `.dockerfile` | +| `.gitignore` | `gitignore` | `.gitignore` | +| `.gitlab-ci.yml` | `gitlab-ci` | `.yml` | +| `LICENSE` | `LICENSE` | `.txt` | +| `metrics-dashboard.yml` | `metrics-dashboards` | `.yml` | Each template must go in its respective subdirectory, have the correct extension and not be empty. So, the hierarchy should look like this: @@ -54,6 +58,9 @@ extension and not be empty. So, the hierarchy should look like this: |-- LICENSE |-- custom_license.txt |-- another_license.txt +|-- metrics-dashboards + |-- custom_metrics-dashboard.yml + |-- another_metrics-dashboard.yml ``` Once this is established, the list of custom templates will be included when diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md new file mode 100644 index 00000000000..e4fe7e36139 --- /dev/null +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -0,0 +1,54 @@ +--- +stage: Create +group: Ecosystem +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 +--- + +# Project integration management **(CORE ONLY)** + +> [Introduced in](https://gitlab.com/groups/gitlab-org/-/epics/2137) GitLab 13.3. + +Project integrations can be configured and enabled by project administrators. As a GitLab instance administrator, you can set default configuration parameters for a given integration that all projects can inherit and use, enabling the integration for all projects that are not already using custom settings. + +You can update these default settings at any time, changing the settings in use for all projects that are set to use instance-level defaults. This also enables the integration for all projects on which it was not already enabled. + +It is only possible to inherit the complete settings for an integration. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137), as well as [group-level management](https://gitlab.com/groups/gitlab-org/-/epics/2543) of integration settings. + +## Manage default settings for a project integration + +1. Navigate to **Admin Area > Settings > Integrations**. +1. Select a project integration. +1. Enter configuration details and click **Save changes**. + +CAUTION: **Caution:** +This may affect all or most of the projects on your GitLab instance. Please review the details below. + +If this is the first time you are setting up instance-level settings for an integration: + +- The integration is enabled for all projects that do not already have this integration configured if you have the **Enable integration** toggle turned on in the instance-level settings. +- Projects that already have the integration configured are not affected, but can choose to use the inherited settings at any time. + +When you make further changes to the instance defaults: + +- They are immediately applied to all projects that have the integration set to use instance-level default settings. +- They are immediately applied to newer projects, created since you last saved defaults for the integration. + - If your instance-level default setting has the **Enable integration** toggle turned on, the integration is automatically enabled for all such projects. +- Projects with custom settings selected for the integration are not immediately affected and may choose to use the latest instance-level defaults at any time. + +It is only possible to inherit the complete settings for an integration. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allow instance administrators to update settings inherited by projects without enabling the integration on all non-configured projects by default. + +## Use instance-level default settings for a project integration + +1. Navigate to **Project > Settings > Integrations**. +1. Choose the integration you want to enable or update. +1. From the drop-down, select **Use default settings**. +1. Ensure the toggle is set to **Enable integration**. +1. Click **Save changes**. + +## Use custom settings for a project integration + +1. Navigate to **Project > Settings > Integrations**. +1. Choose the integration you want to enable or update. +1. From the drop-down, select **Use custom settings**. +1. Ensure the toggle is set to **Enable integration** and enter all required settings. +1. Click **Save changes**. diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index bbc5ed04202..cf23ea12ef4 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference --- 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 92eeb6a04b7..e5c7947399d 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference --- @@ -64,7 +67,7 @@ To ensure only admin users can delete projects: 1. Check the **Default project deletion protection** checkbox. 1. Click **Save changes**. -## Default deletion adjourned period **(PREMIUM ONLY)** +## Default deletion delay **(PREMIUM ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. @@ -85,7 +88,7 @@ To change this period: 1. Select the desired option. 1. Click **Save changes**. -### Override default deletion adjourned period +### Override default deletion delayed period Alternatively, projects that are marked for removal can be deleted immediately. To do so: diff --git a/doc/user/analytics/img/merge_request_analytics_v13_3.png b/doc/user/analytics/img/merge_request_analytics_v13_3.png Binary files differnew file mode 100644 index 00000000000..f90f3625a51 --- /dev/null +++ b/doc/user/analytics/img/merge_request_analytics_v13_3.png diff --git a/doc/user/analytics/img/new_value_stream_v13_3.png b/doc/user/analytics/img/new_value_stream_v13_3.png Binary files differnew file mode 100644 index 00000000000..4284b8ab194 --- /dev/null +++ b/doc/user/analytics/img/new_value_stream_v13_3.png diff --git a/doc/user/analytics/img/repository_analytics_v13_0.png b/doc/user/analytics/img/repository_analytics_v13_0.png Binary files differindex b70b63a6239..dd943b4f44d 100644 --- a/doc/user/analytics/img/repository_analytics_v13_0.png +++ b/doc/user/analytics/img/repository_analytics_v13_0.png diff --git a/doc/user/analytics/img/vsa_filter_bar_v13.3.png b/doc/user/analytics/img/vsa_filter_bar_v13.3.png Binary files differnew file mode 100644 index 00000000000..71e59892434 --- /dev/null +++ b/doc/user/analytics/img/vsa_filter_bar_v13.3.png diff --git a/doc/user/analytics/img/vsa_time_metrics_v13_0.png b/doc/user/analytics/img/vsa_time_metrics_v13_0.png Binary files differindex 073976fd740..799a81584a0 100644 --- a/doc/user/analytics/img/vsa_time_metrics_v13_0.png +++ b/doc/user/analytics/img/vsa_time_metrics_v13_0.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 18f6d79ef23..47852cb0498 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -24,11 +24,11 @@ The following analytics features are available at the group level: - [Contribution](../group/contribution_analytics/index.md). **(STARTER)** - [Insights](../group/insights/index.md). **(ULTIMATE)** -- [Issues](../group/issues_analytics/index.md). **(PREMIUM)** +- [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Productivity](productivity_analytics.md), enabled with the `productivity_analytics` - [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-in-development). **(PREMIUM)** + [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** - [Value Stream](value_stream_analytics.md), enabled with the `cycle_analytics` - [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-in-development). **(PREMIUM)** + [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** ## Project-level analytics @@ -37,7 +37,8 @@ The following analytics features are available at the project level: - [CI/CD](../../ci/pipelines/index.md#pipeline-success-and-duration-charts). **(STARTER)** - [Code Review](code_review_analytics.md). **(STARTER)** - [Insights](../group/insights/index.md). **(ULTIMATE)** -- [Issues](../group/issues_analytics/index.md). **(PREMIUM)** +- [Issue](../group/issues_analytics/index.md). **(PREMIUM)** +- [Merge Request](merge_request_analytics.md). **(STARTER)** - [Repository](repository_analytics.md). - [Value Stream](value_stream_analytics.md), enabled with the `cycle_analytics` - [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-in-development). **(STARTER)** + [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(STARTER)** diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md new file mode 100644 index 00000000000..01295ae888b --- /dev/null +++ b/doc/user/analytics/merge_request_analytics.md @@ -0,0 +1,42 @@ +--- +description: "Merge Request Analytics help you understand the efficiency of your code review process, and the productivity of your team." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. +stage: Manage +group: Analytics +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 +--- + + +# Merge Request Analytics **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3. + +Merge Request Analytics helps you understand the efficiency of your code review process, and the productivity of your team. + +## Overview + +Merge Request Analytics displays information about all accepted merge requests. + +The Throughput chart shows the number of completed merge requests, by month. Merge request throughput is +a common measure of productivity in software engineering. Although imperfect, the average throughput can +be a meaningful benchmark of your team's overall productivity. + +To access Merge Request Analytics, from your project's menu, go to **Analytics > Merge Request**. + + + +## Use cases + +This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) +and others who want to understand broad patterns in code review and productivity. + +You can use Merge Request Analytics to expose when your team is most and least productive, and +identify improvements that might substantially accelerate your development cycle. + +Merge Request Analytics could be used when: + +- You want to know if you were more productive this month than last month, or 12 months ago. +- You want to drill into low- or high-productivity months to understand the work that took place. + +## Permissions + +- On [Starter or Bronze tier](https://about.gitlab.com/pricing/) and above. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index b11bae98af3..9114b6de6bc 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -48,7 +48,30 @@ There are seven stages that are tracked as part of the Value Stream Analytics ca - **Total** (Total) - Total lifecycle time. That is, the velocity of the project or team. [Previously known](https://gitlab.com/gitlab-org/gitlab/-/issues/38317) as **Production**. -## Date ranges +## Filter the analytics data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 + +GitLab provides the ability to filter analytics based on the following parameters: + +- Milestones (Group level) +- Labels (Group level) +- Author +- Assignees + +To filter results: + +1. Select a group. +1. Click on the filter bar. +1. Select a parameter to filter by. +1. Select a value from the autocompleted results, or type to refine the results. + + + +NOTE: **Note:** +Filtering is available only for group-level Value Stream Analytics. + +### Date ranges > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. @@ -165,7 +188,7 @@ A few notes: cycles, calculate their median time and the result is what the dashboard of Value Stream Analytics is showing. -## Customizable Value Stream Analytics +## Customizable Value Stream Analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. @@ -173,8 +196,7 @@ The default stages are designed to work straight out of the box, but they might all teams. Different teams use different approaches to building software, so some teams might want to customize their Value Stream Analytics. -GitLab allows users to hide default stages and create custom stages that align better to their -development workflow. +GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. NOTE: **Note:** Customizability is [only available for group-level](https://gitlab.com/gitlab-org/gitlab/-/issues/35823#note_272558950) Value Stream Analytics. @@ -272,6 +294,34 @@ To recover a default stage that was previously hidden: 1. In the top right corner open the **Recover hidden stage** dropdown. 1. Select a stage. +### Creating a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 + +A default value stream is readily available for each group. You can create additional value streams based on the different areas of work that you would like to measure. + +Once created, a new value stream includes the [seven stages](#overview) that follow +[GitLab workflow](../../topics/gitlab_flow.md) +best practices. You can customize this flow by adding, hiding or re-ordering stages. + +To create a value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select **Create new Value Stream** +1. Fill in a name for the new Value Stream +1. Click the **Create Value Stream** button. + + + +### Disabling custom value streams + +Custom value streams are enabled by default. If you have a self-managed instance, an +administrator can open a Rails console and disable them with the following command: + +```ruby +Feature.disable(:value_stream_analytics_create_multiple_value_streams) +``` + ## Days to completion chart > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 229a8572206..1195d07d7b7 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -9,28 +9,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. -## Overview +The Security Configuration page displays the configuration state of each security feature in the +current project. The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) +to determine each feature's configuration state. If a job with the expected security report artifact +exists in the pipeline, the feature is considered enabled. -The security configuration page displays the configuration state of each of the security -features and can be accessed through a project's sidebar nav. - - - -The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) to determine the configuration -state of each feature. If a job with the expected security report artifact exists in the pipeline, -the feature is considered configured. +You can only enable SAST from the Security Configuration page. Documentation links are included for +the other features. For details about configuring SAST, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). NOTE: **Note:** If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), -all security features will be configured by default. +all security features are configured by default. -## Limitations +## View Security Configuration -It is not yet possible to enable or disable most features using the -configuration page. However, instructions on how to enable or disable a feature -can be found through the links next to each feature on that page. +To view a project's security configuration: -If a project does not have an existing CI configuration, then the SAST feature -can be enabled by clicking on the "Enable with Merge Request" button under the -"Manage" column. Future work will expand this to editing _existing_ CI -configurations, and to other security features. +1. Go to the project's home page. +1. In the left sidebar, go to **Security & Configuration** > **Configuration**. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 7bc8b62825c..6b7086ddc71 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -156,25 +156,25 @@ variables: Container Scanning can be [configured](#customizing-the-container-scanning-settings) using environment variables. -| Environment Variable | Description | Default | -| ------ | ------ | ------ | -| `SECURE_ANALYZERS_PREFIX` | Set the Docker registry base address from which to download the analyzer. | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | -| `KLAR_TRACE` | Set to true to enable more verbose output from klar. | `"false"` | -| `CLAIR_TRACE` | Set to true to enable more verbose output from the clair server process. | `"false"` | -| `DOCKER_USER` | Username for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_USER` | -| `DOCKER_PASSWORD` | Password for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_PASSWORD` | -| `CLAIR_OUTPUT` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold will be outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | `Unknown` | -| `REGISTRY_INSECURE` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | `"false"` | -| `DOCKER_INSECURE` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | `"false"` | -| `CLAIR_VULNERABILITIES_DB_URL` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. | `clair-vulnerabilities-db` | -| `CLAIR_DB_CONNECTION_STRING` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | -| `CI_APPLICATION_REPOSITORY` | Docker repository URL for the image to be scanned. | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | -| `CI_APPLICATION_TAG` | Docker repository tag for the image to be scanned. | `$CI_COMMIT_SHA` | -| `CLAIR_DB_IMAGE` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | `arminc/clair-db:latest` | -| `CLAIR_DB_IMAGE_TAG` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | `latest` | -| `DOCKERFILE_PATH` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner will look for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | `Dockerfile` | -| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs that you want to trust. | "" | -| `SECURE_LOG_LEVEL` | The log levels available are: `fatal`, `error`, `warn`, `info`, `debug` | `info` | +| Environment Variable | Default | Description | +| -------------------- | ----------- | ------- | +| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | +| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | +| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | +| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | +| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | +| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | +| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | +| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. | +| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | +| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | +| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | +| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | +| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | +| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | +| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | ### Overriding the Container Scanning template @@ -291,7 +291,7 @@ build_latest_vulnerabilities: - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db ``` -The above template will work for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. +The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. ## Running the standalone Container Scanning Tool diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 85da7d85506..1672e9fbb25 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -7,8 +7,6 @@ type: reference, howto # Coverage Guided Fuzz Testing **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3226) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). - GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. Coverage-guided fuzzing sends random inputs to an instrumented version of your application in an effort to cause unexpected @@ -16,17 +14,19 @@ behavior, such as a crash. Such behavior indicates a bug that you should address We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md) and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), -you can run your coverage guided fuzz tests as part your CI/CD workflow. You can take advantage of -Coverage Guided Fuzzing by including the CI job in your existing `.gitlab-ci.yml` file. +you can run your coverage-guided fuzz tests as part your CI/CD workflow. You can take advantage of +coverage-guided fuzzing by including the CI job in your existing `.gitlab-ci.yml` file. ## Supported fuzzing engines and languages -GitLab supports these languages through the fuzzing engine listed for each. We currently provide a Docker image for apps written in Go, but you can test the other languages below by providing a Docker image with the fuzz engine to run your app. +GitLab supports these languages through the fuzzing engine listed for each. We currently provide a +Docker image for apps written in Go, but you can test the other languages below by providing a +Docker image with the fuzz engine to run your app. -| Language | Fuzzing Engine | Example | -|----------|---------------------------------------------------------------------------|---------| -| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | | -| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | | +| Language | Fuzzing Engine | Example | +|----------|----------------|---------| +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/c-cpp-fuzzing-example) | +| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | | ## Configuration @@ -49,6 +49,14 @@ 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) contains one job that extends `.fuzz_base` for its single fuzz target. +Note that the hidden job `.fuzz_base` uses several YAML keys that you must not override in your own +job. If you include these keys in your own job, you must copy their original content. These keys +are: + +- `before_script` +- `artifacts` +- `rules` + The `my_fuzz_target` job (the separate job for your fuzz target) does the following: - Extends `.fuzz_base`. @@ -59,8 +67,8 @@ The `my_fuzz_target` job (the separate job for your fuzz target) does the follow The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](#glossary) -and crash events from previous pipelines automatically. This helps your fuzz targets build on the progress of -previous fuzzing jobs. The parsed crash events and data are written to +and crash events from previous pipelines automatically. This helps your fuzz targets build on the +progress of previous fuzzing jobs. The parsed crash events and data are written to `gl-coverage-fuzzing-report.json`. ### Artifacts @@ -84,7 +92,7 @@ There are two types of jobs: Here's our current suggestion for configuring your fuzz target's timeout: -- Set `COVERAGE_FUZZING_BRANCH` to the branch where you want to run long-running (async) fuzzing +- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (async) fuzzing jobs. This is `master` by default. - Use regression or short-running fuzzing jobs for other branches or merge requests. @@ -99,7 +107,54 @@ any option available in the underlying fuzzing engine. | Environment variable | Description | |---------------------------|--------------------------------------------------------------------| -| `COVERAGE_FUZZING_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | +| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | +| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | +| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | + +The files in the seed corpus (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new +files to your Git repository. There's usually no need to frequently update the seed corpus. As part +of the GitLab artifacts system, GitLab saves in a corpus directory the new test cases that every run +generates. In any subsequent runs, GitLab also reuses the generated corpus together with the seed +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). + +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). + +You can download the JSON report file from the CI pipelines page. For more information, see +[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#downloading-artifacts). + +Here's an example coverage fuzzing report: + +```json-doc +{ + "version": "v1.0.8", + "regression": false, + "exit_code": -1, + "vulnerabilities": [ + { + "category": "coverage_fuzzing", + "message": "Heap-buffer-overflow\nREAD 1", + "description": "Heap-buffer-overflow\nREAD 1", + "severity": "Critical", + "stacktrace_snippet": "INFO: Seed: 3415817494\nINFO: Loaded 1 modules (7 inline 8-bit counters): 7 [0x10eee2470, 0x10eee2477), \nINFO: Loaded 1 PC tables (7 PCs): 7 [0x10eee2478,0x10eee24e8), \nINFO: 5 files found in corpus\nINFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes\nINFO: seed corpus: files: 5 min: 1b max: 4b total: 14b rss: 26Mb\n#6\tINITED cov: 7 ft: 7 corp: 5/14b exec/s: 0 rss: 26Mb\n=================================================================\n==43405==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x602000001573 at pc 0x00010eea205a bp 0x7ffee0d5e090 sp 0x7ffee0d5e088\nREAD of size 1 at 0x602000001573 thread T0\n #0 0x10eea2059 in FuzzMe(unsigned char const*, unsigned long) fuzz_me.cc:9\n #1 0x10eea20ba in LLVMFuzzerTestOneInput fuzz_me.cc:13\n #2 0x10eebe020 in fuzzer::Fuzzer::ExecuteCallback(unsigned char const*, unsigned long) FuzzerLoop.cpp:556\n #3 0x10eebd765 in fuzzer::Fuzzer::RunOne(unsigned char const*, unsigned long, bool, fuzzer::InputInfo*, bool*) FuzzerLoop.cpp:470\n #4 0x10eebf966 in fuzzer::Fuzzer::MutateAndTestOne() FuzzerLoop.cpp:698\n #5 0x10eec0665 in fuzzer::Fuzzer::Loop(std::__1::vector\u003cfuzzer::SizedFile, fuzzer::fuzzer_allocator\u003cfuzzer::SizedFile\u003e \u003e\u0026) FuzzerLoop.cpp:830\n #6 0x10eead0cd in fuzzer::FuzzerDriver(int*, char***, int (*)(unsigned char const*, unsigned long)) FuzzerDriver.cpp:829\n #7 0x10eedaf82 in main FuzzerMain.cpp:19\n #8 0x7fff684fecc8 in start+0x0 (libdyld.dylib:x86_64+0x1acc8)\n\n0x602000001573 is located 0 bytes to the right of 3-byte region [0x602000001570,0x602000001573)\nallocated by thread T0 here:\n #0 0x10ef92cfd in wrap__Znam+0x7d (libclang_rt.asan_osx_dynamic.dylib:x86_64+0x50cfd)\n #1 0x10eebdf31 in fuzzer::Fuzzer::ExecuteCallback(unsigned char const*, unsigned long) FuzzerLoop.cpp:541\n #2 0x10eebd765 in fuzzer::Fuzzer::RunOne(unsigned char const*, unsigned long, bool, fuzzer::InputInfo*, bool*) FuzzerLoop.cpp:470\n #3 0x10eebf966 in fuzzer::Fuzzer::MutateAndTestOne() FuzzerLoop.cpp:698\n #4 0x10eec0665 in fuzzer::Fuzzer::Loop(std::__1::vector\u003cfuzzer::SizedFile, fuzzer::fuzzer_allocator\u003cfuzzer::SizedFile\u003e \u003e\u0026) FuzzerLoop.cpp:830\n #5 0x10eead0cd in fuzzer::FuzzerDriver(int*, char***, int (*)(unsigned char const*, unsigned long)) FuzzerDriver.cpp:829\n #6 0x10eedaf82 in main FuzzerMain.cpp:19\n #7 0x7fff684fecc8 in start+0x0 (libdyld.dylib:x86_64+0x1acc8)\n\nSUMMARY: AddressSanitizer: heap-buffer-overflow fuzz_me.cc:9 in FuzzMe(unsigned char const*, unsigned long)\nShadow bytes around the buggy address:\n 0x1c0400000250: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000260: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000270: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000280: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000290: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n=\u003e0x1c04000002a0: fa fa fd fa fa fa fd fa fa fa fd fa fa fa[03]fa\n 0x1c04000002b0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002c0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002d0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002e0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002f0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\nShadow byte legend (one shadow byte represents 8 application bytes):\n Addressable: 00\n Partially addressable: 01 02 03 04 05 06 07 \n Heap left redzone: fa\n Freed heap region: fd\n Stack left redzone: f1\n Stack mid redzone: f2\n Stack right redzone: f3\n Stack after return: f5\n Stack use after scope: f8\n Global redzone: f9\n Global init order: f6\n Poisoned by user: f7\n Container overflow: fc\n Array cookie: ac\n Intra object redzone: bb\n ASan internal: fe\n Left alloca redzone: ca\n Right alloca redzone: cb\n Shadow gap: cc\n==43405==ABORTING\nMS: 1 EraseBytes-; base unit: de3a753d4f1def197604865d76dba888d6aefc71\n0x46,0x55,0x5a,\nFUZ\nartifact_prefix='./crashes/'; Test unit written to ./crashes/crash-0eb8e4ed029b774d80f2b66408203801cb982a60\nBase64: RlVa\nstat::number_of_executed_units: 122\nstat::average_exec_per_sec: 0\nstat::new_units_added: 0\nstat::slowest_unit_time_sec: 0\nstat::peak_rss_mb: 28", + "scanner": { + "id": "libFuzzer", + "name": "libFuzzer" + }, + "location": { + "crash_address": "0x602000001573", + "crash_state": "FuzzMe\nstart\nstart+0x0\n\n", + "crash_type": "Heap-buffer-overflow\nREAD 1" + }, + "tool": "libFuzzer" + } + ] +} +``` ### Additional Configuration @@ -107,6 +162,17 @@ The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying can therefore use all the options available in that fuzzing engine. For more information on these options, see the underlying fuzzing engine's documentation. +### Offline Environment + +To use coverage fuzzing in an offline environment, follow these steps: + +1. Clone [`gitlab-cov-fuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz) + to a private repository that your offline GitLab instance can access. + +1. For each fuzzing step, set `COVFUZZ_URL_PREFIX` to `${NEW_URL_GITLAB_COV_FUZ}/-/raw`, where + `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the + first step. + ### Glossary - Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds diff --git a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png Binary files differindex 8a733c27be1..045221d713c 100644 --- a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png +++ b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index d68928d858b..b2020d48d38 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -48,16 +48,16 @@ uses the popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.o to perform an analysis on your running web application. By default, DAST executes [ZAP Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) -and performs passive scanning only. It won't actively attack your application. +and performs passive scanning only. It doesn't actively attack your application. However, DAST can be [configured](#full-scan) to also perform an *active scan*: attack your application and produce a more extensive security report. It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). NOTE: **Note:** A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any -job fails to finish for any reason, the security dashboard won't show DAST scanner +job fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For example, if the DAST job finishes but the SAST job fails, the security -dashboard won't show DAST results. The analyzer will output an +dashboard doesn't show DAST results. The analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code) on failure. ## Use cases @@ -112,7 +112,7 @@ always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) is used to run the tests on the specified URL and scan it for possible vulnerabilities. -By default, the DAST template will use the latest major version of the DAST Docker +By default, the DAST template uses the latest major version of the DAST Docker image. Using the `DAST_VERSION` variable, you can choose how DAST updates: - Automatically update DAST with new features and fixes by pinning to a major version (such as `1`). @@ -163,7 +163,7 @@ headers whose values you want masked. For details on how to mask headers, see It's also possible to authenticate the user before performing the DAST checks. -Create masked variables to pass the credentials that DAST will use. +Create masked variables to pass the credentials that DAST uses. To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). Note that the key of the username variable must be `DAST_USERNAME` and the key of the password variable must be `DAST_PASSWORD`. @@ -182,7 +182,7 @@ variables: DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` -The results will be saved as a +The results are saved as a [DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. @@ -227,10 +227,10 @@ variables: Since ZAP full scan actively attacks the target application, DAST sends a ping to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand. -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan will - proceed unless the response to the ping includes a `Gitlab-DAST-Permission` +- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan + proceeds unless the response to the ping includes a `Gitlab-DAST-Permission` header with a value of `deny`. -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan will exit +- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan exits unless the response to the ping includes a `Gitlab-DAST-Permission` header with a value of `allow`. @@ -434,7 +434,7 @@ variables: ``` Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline -configuration, the last mention of the variable will take precedence. +configuration, the last mention of the variable takes precedence. ### Available variables @@ -445,24 +445,24 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | | `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` will be submitted with the login form to create an authenticated scan. Not supported for API scans. | +| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | | `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | | `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (introduced in GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | | `DAST_AUTH_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. | | `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were supressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers will be added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | | `DAST_DEBUG` | boolean | Enable debug message output. Default: `false` | | `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | -| `DAST_HTML_REPORT` | string | The file name of the HTML report written at the end of a scan. | -| `DAST_MARKDOWN_REPORT` | string | The file name of the Markdown report written at the end of a scan. | -| `DAST_XML_REPORT` | string | The file name of the XML report written at the end of a scan. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. | +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. | | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false` | | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false` | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | @@ -472,7 +472,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia Not all DAST configuration is available via environment variables. To find out all possible options, run the following configuration. -Available command-line options will be printed to the job log: +Available command-line options are printed to the job log: ```yaml include: @@ -526,7 +526,7 @@ A DAST job has two executing processes: - A series of scripts that start, control and stop the ZAP server. Debug mode of the scripts can be enabled by using the `DAST_DEBUG` environment variable. This can help when troubleshooting the job, -and will output statements indicating what percentage of the scan is complete. +and outputs statements indicating what percentage of the scan is complete. For details on using variables, see [Overriding the DAST template](#customizing-the-dast-settings). Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. @@ -603,24 +603,76 @@ Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override th ## On-Demand Scans > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. -> - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. +> - It's deployed behind a feature flag, enabled by default. +> - It's enabled on GitLab.com. > - It's able to be enabled or disabled per-project. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). -Passive DAST scans may be run on demand against a target website, outside the DevOps lifecycle. These scans will -always be associated with the default or `master` branch of your project and the results can be seen in the project dashboard. +You can run a passive DAST scan against a target website, outside the DevOps lifecycle. These scans +are always associated with the default branch of your project and the results are available in the +project dashboard. + +### Site profile + +An on-demand scan requires a site profile, which includes a profile name and target URL. The profile +name allows you to describe the site to be scanned. The target URL specifies the URL against which +the DAST scan is run. + +### Run an on-demand scan + +NOTE: **Note:** +You must have permission to run an on-demand DAST scan against a protected branch. +The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +Running an on-demand scan requires an existing site profile. If a site profile for the target URL +doesn't exist, first [create a site profile](#create-a-site-profile). An on-demand DAST scan has +a fixed timeout of 60 seconds. + +- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. +- Click **Create new DAST scan**. +- Select a site profile from the profiles dropdown. +- Click **Run scan**. + +#### Create a site profile - +- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. +- Click **Create new DAST scan**. +- Click **New Site Profile**. +- Type in a unique **Profile name** and **Target URL** then click **Save profile**. -### Enable or disable On-Demand Scans +#### Delete a site profile + +- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. +- Click **Create new DAST scan**. +- Click **Delete** in the matching site profile's row. + +### Enable or disable On-demand Scans and site profiles + +On-demand Scans with site profiles is enabled by default. You can disable On-demand Scans +instance-wide, or disable it for specific projects if you prefer. DAST site profiles are not +available if the On-demand Scans feature is disabled. + +Use of On-demand Scans with site profiles requires **both** the following feature flags enabled: + +- security_on_demand_scans_feature_flag +- security_on_demand_scans_site_profiles_feature_flag -On-Demand Scans is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. On-Demand Scans can be enabled or disabled per-project +can disable or enable the feature flags. + +#### Enable or disable On-demand Scans + +To disable On-demand Scans: + +```ruby +# Instance-wide +Feature.disable(:security_on_demand_scans_feature_flag) +# or by project +Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +``` -To enable it: +To enable On-demand Scans: ```ruby # Instance-wide @@ -629,13 +681,29 @@ Feature.enable(:security_on_demand_scans_feature_flag) Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) ``` -To disable it: +#### Enable or disable site profiles + +The Site Profiles feature is enabled instance-wide by default. You can disable it instance-wide, or disable it +for specific projects if you prefer. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable or enable the feature flag. + +To disable Site Profiles: ```ruby # Instance-wide -Feature.disable(:security_on_demand_scans_feature_flag) +Feature.disable(:security_on_demand_scans_site_profiles_feature_flag) # or by project -Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +Feature.disable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) +``` + +To enable Site Profiles: + +```ruby +# Instance-wide +Feature.enable(:security_on_demand_scans_site_profiles_feature_flag) +# or by project +Feature.enable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) ``` ## Reports @@ -719,7 +787,7 @@ For more information about the vulnerabilities database update, check the ## Optimizing DAST -By default, DAST will download all artifacts defined by previous jobs in the pipeline. If +By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created in previous jobs, we recommend you don't download artifacts. To avoid downloading artifacts, add the following to your `gitlab-ci.yml` file: diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index ca2b212ffc3..d41f9441464 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning Analyzers **(ULTIMATE)** -Dependency Scanning relies on underlying third party tools that are wrapped into +Dependency Scanning relies on underlying third-party tools that are wrapped into what we call "Analyzers". An analyzer is a [dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) that wraps a particular tool to: @@ -26,7 +26,7 @@ Dependency Scanning supports the following official analyzers: - [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) - [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) -The analyzers are published as Docker images that Dependency Scanning will use +The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated containers for each analysis. Dependency Scanning is pre-configured with a set of **default images** that are @@ -70,12 +70,12 @@ variables: DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium" ``` -`bundler-audit` runs first. When merging the reports, Dependency Scanning will -remove the duplicates and will keep the `bundler-audit` entries. +`bundler-audit` runs first. When merging the reports, Dependency Scanning +removes the duplicates and keeps the `bundler-audit` entries. ### Disabling default analyzers -Setting `DS_DEFAULT_ANALYZERS` to an empty string will disable all the official +Setting `DS_DEFAULT_ANALYZERS` to an empty string disables all the official default analyzers. In `.gitlab-ci.yml` define: ```yaml @@ -158,8 +158,8 @@ The following table lists the data available for each official analyzer. | Credits | ✓ | 𐄂 | 𐄂 | - ✓ => we have that data -- ⚠ => we have that data but it's partially reliable, or we need to extract that data from unstructured content -- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. +- ⚠ => we have that data, but it's partially reliable, or we need to extract that data from unstructured content +- 𐄂 => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it. -The values provided by these tools are heterogeneous so they are sometimes +The values provided by these tools are heterogeneous, so they are sometimes normalized into common values (e.g., `severity`, `confidence`, etc). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 57b4fae3230..6b14f93735b 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -9,9 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -Dependency Scanning helps to automatically find security vulnerabilities in your dependencies +Dependency Scanning helps to find security vulnerabilities in your dependencies automatically while you're developing and testing your applications, such as when your -application is using an external (open source) library which is known to be vulnerable. +application is using an external (open source) library that is known to be vulnerable. ## Overview @@ -60,6 +60,7 @@ The following languages and dependency managers are supported: | Language (package managers) | Supported files | Scan tool(s) | |----------------------------- | --------------- | ------------ | +| C# .NET ([NuGet](https://www.nuget.org/) 4.9+) | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | Java ([Gradle](https://gradle.org/), [Maven](https://maven.apache.org/)) | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | | Go ([Golang](https://golang.org/)) | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | @@ -84,7 +85,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To enable Dependency Scanning for GitLab 11.9 and later, you must [include](../../../ci/yaml/README.md#includetemplate) the [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) -that's provided as a part of your GitLab installation. +that is provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined that template. @@ -95,9 +96,9 @@ include: - template: Dependency-Scanning.gitlab-ci.yml ``` -The included template will create Dependency Scanning jobs in your CI/CD -pipeline and scan your project's source code for possible vulnerabilities. -The results will be saved as a +The included template creates Dependency Scanning jobs in your CI/CD +pipeline and scans your project's source code for possible vulnerabilities. +The results are saved as a [Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest Dependency Scanning artifact available. @@ -117,7 +118,7 @@ variables: ``` Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline -configuration, the last mention of the variable will take precedence. +configuration, the last mention of the variable takes precedence. ### Overriding Dependency Scanning jobs @@ -155,7 +156,7 @@ The following variables allow configuration of global dependency scanning settin | `DS_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"` | -| `SECURE_LOG_LEVEL` | Default log level is `info`, you can set it to any of the following strings: `fatal`, `error`, `warn`, `info`, `debug`. | +| `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info` | #### Configuring Docker-in-Docker orchestrator @@ -186,10 +187,10 @@ The following variables are used for configuring specific analyzers (used for a | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | | `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1)| -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle will use the Java version specified by this value. | -| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that will be passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | -| `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that will be passed to `gradle` by the analyzer. | -| `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer will pass to `sbt`. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | +| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | +| `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | +| `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | | `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Useful if you're running Dependency Scanning in an offline, air-gapped environment.| | `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | | `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | @@ -310,7 +311,7 @@ Here's an example Dependency Scanning report: "category": "dependency_scanning", "name": "Authentication bypass via incorrect DOM traversal and canonicalization", "message": "Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js", - "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment therefore has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.", + "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment, therefore, has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.", "severity": "Unknown", "solution": "Upgrade to fixed version.\r\n", "scanner": { @@ -390,7 +391,9 @@ Here are the requirements for using Dependency Scanning in an offline environmen - Keep Docker-In-Docker disabled (default). - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of Dependency Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/) +- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/). + This is required because, in an offline environment, the Gemnasium analyzer can't fetch the latest + advisories from the online repository. - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. @@ -428,8 +431,10 @@ For details on saving and transporting Docker images as a file, see Docker's doc ### Set Dependency Scanning CI job variables to use local Dependency Scanning analyzers -Add the following configuration to your `.gitlab-ci.yml` file. You must replace -`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: +Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry. You must also change the +value of `GEMNASIUM_DB_REMOTE_URL` to the location of your offline Git copy of the +[gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/): ```yaml include: diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png Binary files differindex 385236d08f2..cb8911b14b1 100644 --- a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png +++ b/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png Binary files differindex 866ad74d42c..19d47712f9e 100644 --- a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png +++ b/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png diff --git a/doc/user/application_security/img/vulnerability-check_v13_0.png b/doc/user/application_security/img/vulnerability-check_v13_0.png Binary files differindex 536fc4f10f7..9f0bd0f759b 100644 --- a/doc/user/application_security/img/vulnerability-check_v13_0.png +++ b/doc/user/application_security/img/vulnerability-check_v13_0.png diff --git a/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png b/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png Binary files differnew file mode 100644 index 00000000000..10d9effb811 --- /dev/null +++ b/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png diff --git a/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif Binary files differnew file mode 100644 index 00000000000..22acba5fe1e --- /dev/null +++ b/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif diff --git a/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif Binary files differnew file mode 100644 index 00000000000..562ffe7e329 --- /dev/null +++ b/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 3aca4c59423..c003b512808 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -45,6 +45,12 @@ To add Container Scanning, follow the steps listed in the [Container Scanning do To further configure any of the other scanners, refer to each scanner's documentation. +### SAST configuration + +You can set up and configure Static Application Security Testing +(SAST) for your project, without opening a text editor. For more details, +see [configure SAST in the UI](sast/index.md#configure-sast-in-the-ui). + ### Override the default registry base address By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the @@ -61,9 +67,10 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [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. | -| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | +| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | 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) **(ULTIMATE)** | Analyze source code for known vulnerabilities. | +| [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. | ## Security Scanning with Auto DevOps @@ -118,6 +125,8 @@ information with several options: ### View details of a DAST vulnerability +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + Vulnerabilities detected by DAST occur in the live web application. Rectification of these types of vulnerabilities requires specific information. DAST provides the information required to investigate and rectify the underlying cause. @@ -242,6 +251,36 @@ Click this button to create a merge request to apply the solution onto the sourc  +### Managing related issues for a vulnerability + +Issues can be linked to a vulnerability using the related issues block on the vulnerability page. +The relationship is uni-directional. The vulnerability page shows related issues, but the issue page +doesn't show the vulnerability it's related to. An issue can only be related to one vulnerability at +a time. Issues can be linked across groups and projects. + +#### Adding a related issue + +You can link an issue by clicking the **{plus}** button in the **Related Issues** block. + + + +A text box appears that lets you type an issue number or paste an issue link. You can enter multiple +issues at once. Pressing the space bar after each issue number or link converts them to tags that +you can remove by clicking the **{close}** icon to the tag's right. Typing `#` followed by a number +shows an autocomplete menu. Click an issue in the menu to add it as a tag. When you're finished +entering issues, click the **Add** button to link the issues to the vulnerability. Alternatively, +click **Cancel** to exit without linking any issues. + + + +### Removing a related issue + +Click the **{close}** icon to right of an issue to remove it as a related issue. Note that this only +removes it as a related issue of the vulnerability; it doesn't modify or remove the issue itself. +You can link it to the vulnerability again if desired. + + + ## Security approvals in merge requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. @@ -272,7 +311,7 @@ To enable Security Approvals, a [project approval rule](../project/merge_request must be created with the case-sensitive name `Vulnerability-Check`. This approval group must be set with the number of approvals required greater than zero. You must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) to manage approval rules. -1. Navigate to your project's **{settings}** **Settings > General** and expand **Merge request approvals**. +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). @@ -282,14 +321,15 @@ Once this group is added to your project, the approval rule is enabled for all m Any code changes cause the approvals required to reset. -An approval is required when a security report: +An approval is required when the latest security report in a merge request: -- Contains a new vulnerability of `high`, `critical`, or `unknown` severity, regardless of dismissal. +- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the + target branch. Note that approval is still required for dismissed vulnerabilities. - Is not generated during pipeline execution. -An approval is optional when a security report: +An approval is optional when the security report: -- Contains no new vulnerabilities. +- Contains no new vulnerabilities when compared to the target branch. - Contains only new vulnerabilities of `low` or `medium` severity. ## Enabling License Approvals within a project diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 9a2f8768fc0..a5cf93f9448 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -91,3 +91,126 @@ above. You can find more information at each of the pages below: - [DAST offline directions](../dast/index.md#running-dast-in-an-offline-environment) - [License Compliance offline directions](../../compliance/license_compliance/index.md#running-license-compliance-in-an-offline-environment) - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment) + +## Loading Docker images onto your offline host + +To use many GitLab features, including +[security scans](../index.md#working-in-an-offline-environment) +and [Auto DevOps](../../../topics/autodevops/index.md), the GitLab Runner must be able to fetch the +relevant Docker images. + +The process for making these images available without direct access to the public internet +involves downloading the images then packaging and transferring them to the offline host. Here's an +example of such a transfer: + +1. Download Docker images from public internet. +1. Package Docker images as tar archives. +1. Transfer images to offline environment. +1. Load transferred images into offline Docker registry. + +### Using the official GitLab template + +GitLab provides a [vendored template](../../../ci/yaml/README.md#includetemplate) +to ease this process. + +This template should be used in a new, empty project, with a `gitlab-ci.yml` file containing: + +```yaml +include: + - template: Secure-Binaries.gitlab-ci.yml +``` + +The pipeline downloads the Docker images needed for the Security Scanners and saves them as +[job artifacts](../../../ci/pipelines/job_artifacts.md) or pushes them to the [Container Registry](../../packages/container_registry/index.md) +of the project where the pipeline is executed. These archives can be transferred to another location +and [loaded](https://docs.docker.com/engine/reference/commandline/load/) in a Docker daemon. +This method requires a GitLab Runner with access to both `gitlab.com` (including +`registry.gitlab.com`) and the local offline instance. This runner must run in +[privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) +to be able to use the `docker` command inside the jobs. This runner can be installed in a DMZ or on +a bastion, and used only for this specific project. + +#### Scheduling the updates + +By default, this project's pipeline will run only once, when the `.gitlab-ci.yml` is added to the +repo. To update the GitLab security scanners and signatures, it's necessary to run this pipeline +regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For +example, you can set this up to download and store the Docker images every week. + +Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) +for Container Scanning is updated daily. To update this single image, create a new Scheduled +Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only +this job will be triggered, and the image will be updated daily and made available in the project +registry. + +#### Using the secure bundle created + +The project using the `Secure-Binaries.gitlab-ci.yml` template should now host all the required +images and resources needed to run GitLab Security features. + +Next, you must tell the offline instance to use these resources instead of the default ones on +GitLab.com. To do so, set the environment variable `SECURE_ANALYZERS_PREFIX` with the URL of the +project [container registry](../../packages/container_registry/index.md). + +You can set this variable in the projects' `.gitlab-ci.yml`, or +in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../../ci/variables/README.md#custom-environment-variables) +for more information. + +#### Variables + +The following table shows which variables you can use with the `Secure-Binaries.gitlab-ci.yml` +template: + +| VARIABLE | Description | Default value | +|-------------------------------------------|-----------------------------------------------|-----------------------------------| +| `SECURE_BINARIES_ANALYZERS` | Comma-separated list of analyzers to download | `"bandit, brakeman, gosec, and so on..."` | +| `SECURE_BINARIES_DOWNLOAD_IMAGES` | Used to disable jobs | `"true"` | +| `SECURE_BINARIES_PUSH_IMAGES` | Push files to the project registry | `"true"` | +| `SECURE_BINARIES_SAVE_ARTIFACTS` | Also save image archives as artifacts | `"false"` | +| `SECURE_BINARIES_ANALYZER_VERSION` | Default analyzer version (Docker tag) | `"2"` | + +### Alternate way without the official template + +If it's not possible to follow the above method, the images can be transferred manually instead: + +#### Example image packager script + +```shell +#!/bin/bash +set -ux + +# Specify needed analyzer images +analyzers=${SAST_ANALYZERS:-"bandit eslint gosec"} +gitlab=registry.gitlab.com/gitlab-org/security-products/analyzers/ + +for i in "${analyzers[@]}" +do + tarname="${i}_2.tar" + docker pull $gitlab$i:2 + docker save $gitlab$i:2 -o ./analyzers/${tarname} + chmod +r ./analyzers/${tarname} +done +``` + +#### Example image loader script + +This example loads the images from a bastion host to an offline host. In certain configurations, +physical media may be needed for such a transfer: + +```shell +#!/bin/bash +set -ux + +# Specify needed analyzer images +analyzers=${SAST_ANALYZERS:-"bandit eslint gosec"} +registry=$GITLAB_HOST:4567 + +for i in "${analyzers[@]}" +do + tarname="${i}_2.tar" + scp ./analyzers/${tarname} ${GITLAB_HOST}:~/${tarname} + ssh $GITLAB_HOST "sudo docker load -i ${tarname}" + ssh $GITLAB_HOST "sudo docker tag $(sudo docker images | grep $i | awk '{print $3}') ${registry}/analyzers/${i}:2" + ssh $GITLAB_HOST "sudo docker push ${registry}/analyzers/${i}:2" +done +``` diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 70d4b513cf9..fd331020719 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Static Application Security Testing (SAST) **(ULTIMATE)** +# Static Application Security Testing (SAST) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. @@ -14,19 +14,11 @@ The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab. explains how **4 of the top 6 attacks were application based**. Download it to learn how to protect your organization. -## Overview - If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known -vulnerabilities using Static Application Security Testing (SAST). - -You can take advantage of SAST by doing one of the following: - -- [Including the SAST template](#configuration) in your existing `.gitlab-ci.yml` file. -- Implicitly using [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) provided by - [Auto DevOps](../../../topics/autodevops/index.md). +vulnerabilities using Static Application Security Testing (SAST). GitLab checks the SAST report and +compares the found vulnerabilities between the source and target branches. -GitLab checks the SAST report, compares the found vulnerabilities between the -source and target branches, and shows the information right on the merge request. +Details of the vulnerabilities found are included in the merge request. **(ULTIMATE)**  @@ -40,7 +32,7 @@ The results are sorted by the priority of the vulnerability: 1. Everything else NOTE: **Note:** -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard won't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard won't show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. +A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. The analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code) on failure. ## Use cases @@ -51,15 +43,15 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j ## Requirements -To run SAST jobs, by default, you need GitLab Runner with the +To run SAST jobs, by default, you need a 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. -Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for SAST](#enabling-docker-in-docker). +Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for SAST](#enabling-docker-in-docker-ultimate). CAUTION: **Caution:** -Our SAST jobs currently expect a Linux container type. Windows containers are not yet supported. +Our SAST jobs require a Linux container type. Windows containers are not yet supported. CAUTION: **Caution:** If you use your own Runners, make sure the Docker version installed @@ -69,27 +61,27 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae The following table shows which languages, package managers and frameworks are supported and which tools are used. -| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | -|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------| -| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | -| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | -| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11.9 | -| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | -| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | -| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10 | -| Go | [Gosec](https://github.com/securego/gosec) | 10.7 | -| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | -| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | -| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | -| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8, moved to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | -| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | -| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | -| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | -| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | -| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | -| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3, moved to [GitLab Core](https://about.gitlab.com/pricing/) in 13.1 | -| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | -| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, merged with ESLint in 13.2 | +| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | +|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11., [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Go | [Gosec](https://github.com/securego/gosec) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | +| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.1 | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | NOTE: **Note:** The Java analyzers can also be used for variants like the @@ -98,11 +90,11 @@ The Java analyzers can also be used for variants like the ### Making SAST analyzers available to all GitLab tiers -All open source (OSS) analyzers are in the process of being reviewed and potentially moved to the GitLab Core tier. Progress can be +All open source (OSS) analyzers have been moved to the GitLab Core tier. Progress can be tracked in the corresponding [epic](https://gitlab.com/groups/gitlab-org/-/epics/2098). -Please note that support for [Docker-in-Docker](#enabling-docker-in-docker) +Please note that support for [Docker-in-Docker](#enabling-docker-in-docker-ultimate) will not be extended to the GitLab Core tier. #### Summary of features per tier @@ -110,14 +102,14 @@ will not be extended to the GitLab Core tier. Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Core | In Ultimate | -|:--------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | -| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Core | In Ultimate | +|:-----------------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities-ultimate) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](#security-dashboard-ultimate) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -125,9 +117,14 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Configuration -NOTE: **Note:** -You don't have to configure SAST manually as shown in this section if you're using [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) -provided by [Auto DevOps](../../../topics/autodevops/index.md). +To configure SAST for a project you can: + +- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) provided by + [Auto DevOps](../../../topics/autodevops/index.md). +- [Configure SAST manually](#configure-sast-manually). +- [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). + +### Configure SAST manually For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/README.md#includetemplate) the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) @@ -141,14 +138,29 @@ include: - template: SAST.gitlab-ci.yml ``` -The included template will create SAST jobs in your CI/CD pipeline and scan +The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. -The results will be saved as a +The results are saved as a [SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. +### Configure SAST in the UI + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. + +For a project that does not have a `.gitlab-ci.yml` file, you can enable SAST with a basic +configuration using the **SAST Configuration** page: + +1. From the project's home page, go to **Security & Configuration** > **Configuration** in the + left sidebar. +1. Click **Enable via Merge Request** on the Static Application Security Testing (SAST) row. +1. Enter the appropriate SAST details into the fields on the page. See [Available variables](#available-variables) + for a description of these variables. +1. Click **Create Merge Request**. +1. Review and merge the merge request. + ### Customizing the SAST settings The SAST settings can be changed through [environment variables](#available-variables) @@ -203,12 +215,12 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -### Enabling Docker-in-Docker +### Enabling Docker-in-Docker **(ULTIMATE)** If needed, you can enable Docker-in-Docker to restore the SAST behavior that existed prior to GitLab 13.0. Follow these steps to do so: -1. Configure GitLab Runner with Docker-inDocker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). +1. Configure a GitLab Runner with Docker-in-Docker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). 1. Set the variable `SAST_DISABLE_DIND` set to `false`: ```yaml @@ -289,14 +301,16 @@ See [Analyzer settings](#analyzer-settings) for the complete list of available o SAST can be [configured](#customizing-the-sast-settings) using environment variables. -#### Logging Level +#### Logging level -You can control the verbosity of logs by setting the `SECURE_LOG_LEVEL` env var. The default is set to `info`, you can set it to any of the following levels: +To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. + +From highest to lowest severity, the logging levels are: - `fatal` - `error` - `warn` -- `info` +- `info` (default) - `debug` #### Custom Certificate Authority @@ -308,12 +322,12 @@ of CA certs that you want to trust within the SAST environment. The following are Docker image-related variables. -| Environment variable | Description | -|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | +| Environment variable | Description | +|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker-ultimate). This variable is `true` by default. | #### Vulnerability filters @@ -322,9 +336,9 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | Environment variable | Default value | Description | |-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | 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 will also match patterns. | -| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | +| `SEARCH_MAX_DEPTH` | 4 | Maximum number of directories traversed when searching for source code files. | +| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | -| `SAST_DISABLE_BABEL` | `false` | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | | `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | | `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | | `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | @@ -334,40 +348,40 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre #### Docker-in-Docker orchestrator -The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker). +The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker-ultimate). -| Environment variable | Default value | Description | -|------------------------------------------|---------------|-------------| -| `SAST_ANALYZER_IMAGES` | | Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | -| `SAST_PULL_ANALYZER_IMAGES` | 1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | -| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`.| +| Environment variable | Default value | Description | +|------------------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SAST_ANALYZER_IMAGES` | | Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | +| `SAST_PULL_ANALYZER_IMAGES` | 1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | +| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | +| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | +| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | #### Analyzer settings Some analyzers can be customized with environment variables. -| Environment variable | Analyzer | Description | -|---------------------------------------|----------------------|-------------| -| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` will use to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | -| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | -| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | -| `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | -| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | -| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | -| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | -| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | -| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | -| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | -| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | -| `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | -| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | -| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | -| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | -| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | -| `SEARCH_MAX_DEPTH` | any | Maximum number of directories traversed when searching for source code files. Default: `4`. | +| Environment variable | Analyzer | Description | +|---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` will use to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | +| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | +| `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | +| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | +| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | +| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | +| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | +| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | +| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | +| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | +| `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | +| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | +| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | +| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | +| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | +| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | #### Custom environment variables @@ -387,6 +401,9 @@ analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, The SAST 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/sast-report-format.json). +The JSON report file can be downloaded from the CI pipelines page, for more +information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). + Here's an example SAST report: ```json-doc @@ -466,13 +483,13 @@ Here's an example SAST report: Learn more about [Secret Detection](../secret_detection). -## Security Dashboard +## Security Dashboard **(ULTIMATE)** The Security Dashboard is a good place to get an overview of all the security vulnerabilities in your groups, projects and pipelines. Read more about the [Security Dashboard](../security_dashboard/index.md). -## Interacting with the vulnerabilities +## Interacting with the vulnerabilities **(ULTIMATE)** Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). @@ -498,8 +515,9 @@ run successfully. For more information, see [Offline environments](../offline_de To use SAST in an offline environment, you need: - To keep Docker-In-Docker disabled (default). -- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- A GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Configure certificate checking of packages (optional). NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), @@ -556,6 +574,13 @@ variables: The SAST job should now use local copies of the SAST analyzers to scan your code and generate security reports without requiring internet access. +### Configure certificate checking of packages + +If a SAST job invokes a package manager, you must configure its certificate verification. In an +offline environment, certificate verification with an external source isn't possible. Either use a +self-signed certificate or disable certificate verification. Refer to the package manager's +documentation for instructions. + ## Troubleshooting ### `Error response from daemon: error processing tar file: docker-tar: relocation error` diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index ea635212c5d..7daf2f3308b 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -19,7 +19,7 @@ malicious users to gain access to resources like deployment environments. GitLab 11.9 includes a new check called Secret Detection. It scans the content of the repository to find API keys and other information that should not be there. -GitLab displays identified secrets as part of the SAST reports visibly in a few places: +GitLab displays identified secrets visibly in a few places: - [Security Dashboard](../security_dashboard/) - Pipelines' **Security** tab @@ -46,6 +46,25 @@ CAUTION: **Caution:** If you use your own Runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +### Making Secret Detection available to all GitLab tiers + +To make Secret Detection available to as many customers as possible, we have enabled it for all GitLab tiers. +However not all features are available on every tier. See the breakdown below for more details. + +#### 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 Core | In Ultimate | +|:--------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | +| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | + ## Configuration NOTE: **Note:** @@ -145,16 +164,19 @@ Secret Detection can be customized by defining available variables: |-------------------------|---------------|-------------| | `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | | `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | +| `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 will 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. | -### Logging Level +### Logging level + +To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. -You can control the verbosity of logs by setting the `SECURE_LOG_LEVEL` env var. The default is set to `info`, you can set it to any of the following levels: +From highest to lowest severity, the logging levels are: - `fatal` - `error` - `warn` -- `info` +- `info` (default) - `debug` ## Full History Secret Scan diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png Binary files differindex d98fb71ae37..8fab4e39175 100644 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png Binary files differdeleted file mode 100644 index d6cfc2de980..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png Binary files differnew file mode 100644 index 00000000000..4d51f57a98d --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png Binary files differnew file mode 100644 index 00000000000..7b9a48b8738 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif b/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif Binary files differnew file mode 100644 index 00000000000..29e7168b6ea --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif diff --git a/doc/user/application_security/security_dashboard/img/standalone_vulnerability_page_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png Binary files differindex 9cf95b197fe..9cf95b197fe 100644 --- a/doc/user/application_security/security_dashboard/img/standalone_vulnerability_page_v13_1.png +++ b/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 9a13d143d1f..b8fcc513cb1 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -8,24 +8,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboard **(ULTIMATE)** The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects and pipelines. +vulnerabilities in your groups, projects, and pipelines. -You can also drill down into a vulnerability and get extra information, see which -project it comes from, the file it's in, and various metadata to help you analyze -the risk. You can also take actions on vulnerabilities by creating an issue for them, -or by dismissing them. +You can also drill down into a vulnerability and get extra information. This includes the project it +comes from, any related file(s), and metadata that helps you analyze the risk it poses. You can also +dismiss a vulnerability or create an issue for it. To benefit from the Security Dashboard you must first configure one of the -[security reports](../index.md). +[security scanners](../index.md). ## Supported reports -The Security Dashboard supports the following reports: +The Security Dashboard displays vulnerabilities detected by scanners such as: - [Container Scanning](../container_scanning/index.md) - [Dynamic Application Security Testing](../dast/index.md) - [Dependency Scanning](../dependency_scanning/index.md) - [Static Application Security Testing](../sast/index.md) +- And others! ## Requirements @@ -43,10 +43,13 @@ To use the instance, group, project, or pipeline security dashboard: At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against. -Visit the page for any pipeline which has run any of the [supported reports](#supported-reports). Click the **Security** tab to view the Security findings. -  +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. + + + NOTE: **Note:** A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. @@ -56,7 +59,8 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j At the project level, the Security Dashboard displays the vulnerabilities merged into your project's [default branch](../../project/repository/branches/index.md#default-branch). Access it by navigating -to **Security & Compliance > Security Dashboard**. +to **Security & Compliance > Security Dashboard**. By default, the Security Dashboard displays all +detected and confirmed vulnerabilities. The Security Dashboard first displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low). Below this, a table displays each vulnerability's status, severity, @@ -67,7 +71,7 @@ You can filter the vulnerabilities by: - Status - Severity -- Report type +- Scanner You can also dismiss vulnerabilities in the table: @@ -82,31 +86,21 @@ You can also dismiss vulnerabilities in the table: The group Security Dashboard gives an overview of the vulnerabilities in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** -for your group. +for your group. By default, the Security Dashboard displays all detected and confirmed +vulnerabilities. NOTE: **Note:** The Security Dashboard only shows projects with [security reports](#supported-reports) enabled in a group. - - -You can filter which vulnerabilities the Security Dashboard displays by: - -- Status -- Severity -- Report type -- Project - -A table lists the vulnerabilities, sorted by severity. The table shows each vulnerability's status, -severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) -page to view more information about that vulnerability. + -Next to the list is a timeline chart that shows how many open +There is a timeline chart that shows how many open vulnerabilities your projects had at various points in time. You can filter among 30, 60, and 90 days, with the default being 90. Hover over the chart to get more details about the open vulnerabilities at a specific time. -Below the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: +Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: - F: 1 or more "critical" - D: 1 or more "high" or "unknown" @@ -117,7 +111,7 @@ Below the timeline chart is a list of projects, grouped and sorted by the severi Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed vulnerabilities are not included either. -Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +Navigate to the group's [Vulnerability Report](#vulnerability-list) to view the vulnerabilities found. ## Instance Security Dashboard @@ -195,10 +189,21 @@ to configure daily security scans. Each dashboard's vulnerability list contains vulnerabilities from the latest scans that were merged into the default branch. -Click any vulnerability in the table to see more information on that vulnerability. To create an -issue associated with the vulnerability, click the **Create Issue** button. - + + +You can filter which vulnerabilities the Security Dashboard displays by: + +- Status +- Severity +- Scanner +- Project + +Clicking any vulnerability in the table takes you to its +[Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. +To create an issue associated with the vulnerability, click the **Create Issue** button. + + Once you create the issue, the vulnerability list contains a link to the issue and an icon whose color indicates the issue's status (green for open issues, blue for closed issues). @@ -216,3 +221,5 @@ 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. --> + +Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index a6738677454..c916cdbfe7c 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -99,6 +99,11 @@ deployment platform. Changes performed outside of this tab are reflected upon refresh. Enforcement status changes are deployed directly to a deployment namespace of the selected environment. +By default, the network policy list contains predefined policies in a +disabled state. Once enabled,a predefined policy deploys to the +selected environment's deployment platform and you can manage it like +the regular policies. + NOTE: **Note:** If you're using [Auto DevOps](../../../topics/autodevops/index.md) and change a policy in this section, your `auto-deploy-values.yaml` file diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differdeleted file mode 100644 index 2063762d3eb..00000000000 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_dropdown_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_v13_1.png Binary files differdeleted file mode 100644 index ee4e97bcafe..00000000000 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png Binary files differdeleted file mode 100644 index e0e0fdb6f6e..00000000000 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_download_patch_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png Binary files differindex b925c342a11..b925c342a11 100644 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_download_patch_button_v13_1.png +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differnew file mode 100644 index 00000000000..05ca74c3d5c --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png Binary files differnew file mode 100644 index 00000000000..a3034a7db04 --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png Binary files differnew file mode 100644 index 00000000000..30a7195e1ab --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index d5cce6434d8..ffec4bf336d 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -5,16 +5,16 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Standalone Vulnerability pages +# Vulnerability Pages > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. Each security vulnerability in the [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has its own standalone page. - + -On the standalone vulnerability page, you can interact with the vulnerability in +On the vulnerability page, you can interact with the vulnerability in several different ways: - [Change the Vulnerability Status](#changing-vulnerability-status) - You can change the @@ -57,7 +57,7 @@ generates for you. GitLab supports the following scanners: When an automatic solution is available, the button in the header will show "Resolve with merge request": - + Selecting the button will create a merge request with the automatic solution. @@ -66,8 +66,8 @@ Selecting the button will create a merge request with the automatic solution. To manually apply the patch that was generated by GitLab for a vulnerability, select the dropdown arrow on the "Resolve with merge request" button, then select the "Download patch to resolve" option: - + This will change the button text to "Download patch to resolve". Click on it to download the patch: - + diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 512a98d567b..4bd15c7922d 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference, howto +--- + # AsciiDoc GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5. @@ -364,6 +371,89 @@ comment - content which is not included in the output document |=== ``` +### Colors + +It’s possible to have color written in `HEX`, `RGB`, or `HSL` format rendered with a color indicator. +Supported formats (named colors are not supported): + +- HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` +- RGB: `` `RGB[A](R, G, B[, A])` `` +- HSL: `` `HSL[A](H, S, L[, A])` `` + +Color written inside backticks will be followed by a color "chip": + +```plaintext +- `#F00` +- `#F00A` +- `#FF0000` +- `#FF0000AA` +- `RGB(0,255,0)` +- `RGB(0%,100%,0%)` +- `RGBA(0,255,0,0.3)` +- `HSL(540,70%,50%)` +- `HSLA(540,70%,50%,0.3)` +``` + +### STEM + +To activate equation and formula support, +set the `stem` attribute in the document's header to `latexmath`. +Equations and formulas will be rendered using [KaTeX](https://katex.org/): + +```plaintext +:stem: latexmath + +latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon] + +[stem] +++++ +sqrt(4) = 2 +++++ + +A matrix can be written as stem:[[[a,b\],[c,d\]\]((n),(k))]. +``` + +### Diagrams and flowcharts + +It's possible to generate diagrams and flowcharts from text in GitLab using +[Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com). + +#### Mermaid + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31818) in GitLab 13.3. + +Visit the [official page](https://mermaidjs.github.io/) for more details. +If you're new to using Mermaid or need help identifying issues in your Mermaid code, +the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool +for creating and resolving issues within Mermaid diagrams. + +In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: + +```plaintext +[mermaid] +---- +graph LR + A[Square Rect] -- Link text --> B((Circle)) + A --> C(Round Rect) + B --> D{Rhombus} + C --> D +---- +``` + +#### PlantUML + +To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. +Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). + +Once enabled, you should write your text inside the `plantuml` block: + +```plaintext +[plantuml] +---- +Bob -> Alice : hello +---- +``` + ### Multimedia ```plaintext diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 507ba25850d..3b04c7aac18 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -28,9 +28,9 @@ This namespace: To see a list of available applications to install. For a: - [Project-level cluster](../project/clusters/index.md), navigate to your project's - **{cloud-gear}** **Operations > Kubernetes**. + **Operations > Kubernetes**. - [Group-level cluster](../group/clusters/index.md), navigate to your group's - **{cloud-gear}** **Kubernetes** page. + **Kubernetes** page. NOTE: **Note:** As of GitLab 11.6, Helm will be upgraded to the latest version supported @@ -69,47 +69,23 @@ can lead to confusion during deployments. > - Introduced in GitLab 10.2 for project-level clusters. > - Introduced in GitLab 11.6 for group-level clusters. -> - A local Tiller option was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 behind a feature flag, enabled by default. -> - The feature flag for local Tiller is enabled on GitLab.com. +> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) since GitLab 13.2. [Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is used to install the GitLab-managed apps. GitLab runs each `helm` command in a pod within the `gitlab-managed-apps` namespace inside the cluster. -As of GitLab 13.2, the integration uses a local -[Tiller](https://v2.helm.sh/docs/glossary/#tiller) by default. When using a -local Tiller, the Helm application does not need to be installed and will not -be shown in the list of applications. +GitLab's integration uses Helm 2 with a local +[Tiller](https://v2.helm.sh/docs/glossary/#tiller) server for managing +applications. Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), +GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` +namespace. This server can now be safely removed. NOTE: **Note:** GitLab's Helm integration does not support installing applications behind a proxy, but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) is available. -### Enable or disable local Tiller **(CORE ONLY)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 -> - The option to disable local Tiller is [planned for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.3 - -Local Tiller is under development, but is 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 enable it for your instance. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:managed_apps_local_tiller) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:managed_apps_local_tiller) -``` - ### cert-manager > Introduced in GitLab 11.6 for project- and group-level clusters. @@ -311,7 +287,7 @@ This feature: For example: ```shell - kubectl logs -n gitlab-managed-apps $(kubectl get pod -n gitlab-managed-apps -l app=nginx-ingress,component=controller --no-headers=true -o custom-columns=:metadata.name) modsecurity-log -f + kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f ``` To enable WAF, switch its respective toggle to the enabled position when installing or updating [Ingress application](#ingress). @@ -343,7 +319,7 @@ To help you tune your WAF rules, you can globally set your WAF to either To change your WAF's mode: 1. [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md) if you have not already done so. -1. Navigate to **{cloud-gear}** **Operations > Kubernetes**. +1. Navigate to **Operations > Kubernetes**. 1. In **Applications**, scroll to **Ingress**. 1. Under **Global default**, select your desired mode. 1. Click **Save changes**. @@ -535,7 +511,7 @@ To enable log shipping: 1. Ensure your cluster contains at least 3 nodes of instance types larger than `f1-micro`, `g1-small`, or `n1-standard-1`. -1. Navigate to **{cloud-gear}** **Operations > Kubernetes**. +1. Navigate to **Operations > Kubernetes**. 1. In **Kubernetes Cluster**, select a cluster. 1. In the **Applications** section, find **Elastic Stack** and click **Install**. @@ -547,7 +523,7 @@ file. NOTE: **Note:** The chart deploys 3 identical Elasticsearch pods which can't be colocated, and each -require 1 CPU and 2 GB of RAM, making them incompatible with clusters containing +requires 1 CPU and 2 GB of RAM, making them incompatible with clusters containing fewer than 3 nodes or consisting of `f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. @@ -601,7 +577,7 @@ your data. Fluentd sends logs in syslog format. To enable Fluentd: -1. Navigate to **{cloud-gear}** **Operations > Kubernetes** and click +1. Navigate to **Operations > Kubernetes** and click **Applications**. You will be prompted to enter a host, port and protocol where the WAF logs will be sent to via syslog. 1. Provide the host domain name or URL in **SIEM Hostname**. @@ -719,7 +695,7 @@ for the available configuration options. NOTE: **Note:** Support for installing the Ingress managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). +If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). ### Install cert-manager using GitLab CI/CD @@ -760,7 +736,7 @@ available configuration options. NOTE: **Note:** Support for installing the Cert Manager managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). +If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). ### Install Sentry using GitLab CI/CD @@ -951,17 +927,15 @@ For an overview, see the [Container Network Security Demo for GitLab 12.8](https Enable Cilium in the `.gitlab/managed-apps/config.yaml` file to install it: ```yaml -# possible values are gke, eks or you can leave it blank +# possible values are gke or eks clusterType: gke cilium: installed: true ``` -The `clusterType` variable enables the recommended Helm variables for -a corresponding cluster type. The default value is blank. You can -check the recommended variables for each cluster type in the official -documentation: +The `clusterType` variable enables the recommended Helm variables for a corresponding cluster type. +You can check the recommended variables for each cluster type in the official documentation: - [Google GKE](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-eks/#deploy-cilium) @@ -972,6 +946,11 @@ management project. Refer to the [Cilium chart](https://github.com/cilium/cilium/tree/master/install/kubernetes/cilium) for the available configuration options. +You can check Cilium's installation status on the cluster management page: + +- [Project-level cluster](../project/clusters/index.md): Navigate to your project's **Operations > Kubernetes** page. +- [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page. + CAUTION: **Caution:** Installation and removal of the Cilium requires a **manual** [restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) @@ -1004,7 +983,7 @@ The Cilium monitor log for traffic is logged out by the `cilium-monitor` sidecar container. You can check these logs with the following command: ```shell -kubectl -n gitlab-managed-apps logs cilium-XXXX cilium-monitor +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor ``` You can disable the monitor log in `.gitlab/managed-apps/cilium/values.yaml`: @@ -1127,7 +1106,7 @@ falco: You can check these logs with the following command: ```shell -kubectl logs -l app=falco -n gitlab-managed-apps +kubectl -n gitlab-managed-apps logs -l app=falco ``` NOTE: **Note:** @@ -1183,7 +1162,7 @@ below are examples and should be replaced with settings specific to your environ ui: enabled: true server: - # Disable the built in data storage volume as it's not safe for Hight Availability mode + # Disable the built in data storage volume as it's not safe for High Availability mode dataStorage: enabled: false # Enable High Availability Mode @@ -1210,9 +1189,9 @@ server: } ``` -Once you have successfully installed Vault, you will need to [initialize the Vault](https://learn.hashicorp.com/vault/getting-started/deploy#initializing-the-vault) +Once you have successfully installed Vault, you will need to [initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) and obtain the initial root token. You will need access to your Kubernetes cluster that Vault has been deployed into in order to do this. -To initialise the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done by using the `kubectl` command line tool). +To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done by using the `kubectl` command line tool). Once you have a shell into the pod, run the `vault operator init` command: ```shell @@ -1278,7 +1257,7 @@ available configuration options. NOTE: **Note:** Support for installing the JupyterHub managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). +If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). ### Install Elastic Stack using GitLab CI/CD @@ -1393,7 +1372,7 @@ If you plan to use GitLab Serverless capabilities, be sure to set an A record wi NOTE: **Note:** Support for installing the Knative managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). +If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). #### Knative Metrics @@ -1587,7 +1566,7 @@ To avoid installation errors: If you're using a managed cluster on AWS EKS, and you are not able to install some of the managed apps, consider checking the logs. -You can check the logs by running following commands: +You can check the logs by running the following commands: ```shell kubectl get pods --all-namespaces diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 892d2bce184..f7241444a6b 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -73,10 +73,10 @@ configure cluster: name: production ``` -### Setting the environment scope **(PREMIUM)** +### Setting the environment scope [Environment -scopes](../project/clusters/index.md#setting-the-environment-scope-premium) +scopes](../project/clusters/index.md#setting-the-environment-scope) are usable when associating multiple clusters to the same management project. diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_2.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_2.png Binary files differdeleted file mode 100644 index e1edfcdd024..00000000000 --- a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_2.png +++ /dev/null diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png Binary files differnew file mode 100644 index 00000000000..a06f8812b41 --- /dev/null +++ b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png diff --git a/doc/user/compliance/compliance_dashboard/img/failed_icon_v13_3.png b/doc/user/compliance/compliance_dashboard/img/failed_icon_v13_3.png Binary files differnew file mode 100644 index 00000000000..c3f386c9dee --- /dev/null +++ b/doc/user/compliance/compliance_dashboard/img/failed_icon_v13_3.png diff --git a/doc/user/compliance/compliance_dashboard/img/success_icon_v13_3.png b/doc/user/compliance/compliance_dashboard/img/success_icon_v13_3.png Binary files differnew file mode 100644 index 00000000000..ea6ca924f81 --- /dev/null +++ b/doc/user/compliance/compliance_dashboard/img/success_icon_v13_3.png diff --git a/doc/user/compliance/compliance_dashboard/img/warning_icon_v13_3.png b/doc/user/compliance/compliance_dashboard/img/warning_icon_v13_3.png Binary files differnew file mode 100644 index 00000000000..168a7021948 --- /dev/null +++ b/doc/user/compliance/compliance_dashboard/img/warning_icon_v13_3.png diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index e7db73e25d9..5c05725d95b 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -17,7 +17,10 @@ for merging into production. To access the Compliance Dashboard for a group, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu. - + + +NOTE: **Note:** +The Compliance Dashboard shows only the latest MR on each project. ## Use cases @@ -34,3 +37,40 @@ You can use the dashboard to: - On [GitLab Ultimate](https://about.gitlab.com/pricing/) tier. - By **Administrators** and **Group Owners**. + +## Approval status and separation of duties + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. + +We support a separation of duties policy between users who create and approve Merge Requests. +The approval status column can help you identify violations of this policy. +Our criteria for the separation of duties is as follows: + +- [A Merge Request author is **not** allowed to approve their Merge Request](../../project/merge_requests/merge_request_approvals.md#allowing-merge-request-authors-to-approve-their-own-merge-requests) +- [A Merge Request committer is **not** allowed to approve a Merge Request they have added commits to](../../project/merge_requests/merge_request_approvals.md#prevent-approval-of-merge-requests-by-their-committers) +- [The minimum number of approvals required to merge a Merge Request is **at least** two](../../project/merge_requests/merge_request_approvals.md#approval-rules) + +The "Approval status" column shows you, at a glance, whether a Merge Request is complying with the above. +This column has four states: + +| State | Description | +|:------|:------------| +| Empty | The Merge Request approval status is unknown | +|  | The Merge Request **does not** comply with any of the above criteria | +|  | The Merge Request complies with **some** of the above criteria | +|  | The Merge Request complies with **all** of the above criteria | + +If you do not see the success icon in your Compliance dashboard; please review the above criteria for the Merge Requests +project to make sure it complies with the separation of duties described above. + +## Chain of Custody report + +The Chain of Custody report allows customers to export a list of merge commits within the group. +The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, +merge request author, merge request ID, merge user, pipeline ID, group name, project name, and merge request approvers. + +To download the Chain of Custody report, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu and click **List of all merge commits** + +NOTE: **Note:** +The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. +The remaining records are truncated when this limit is reached. diff --git a/doc/user/compliance/license_compliance/img/denied_licenses_v13_3.png b/doc/user/compliance/license_compliance/img/denied_licenses_v13_3.png Binary files differnew file mode 100644 index 00000000000..aa3deb0c154 --- /dev/null +++ b/doc/user/compliance/license_compliance/img/denied_licenses_v13_3.png diff --git a/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png Binary files differindex 992c08edcd3..1366c569f17 100644 --- a/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png +++ b/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png Binary files differindex d6c6142c0e7..42bf8bd1ed5 100644 --- a/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png +++ b/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png Binary files differindex 9ae59e2b96b..49c66832f00 100644 --- a/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png +++ b/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png Binary files differindex 8ee55003768..5a4216dd645 100644 --- a/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png +++ b/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png Binary files differindex 52b26abd9c5..91f1eec2a23 100644 --- a/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png +++ b/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png Binary files differindex dc227bf05ef..20ed30a21e7 100644 --- a/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png +++ b/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/license_list_v13_0.png b/doc/user/compliance/license_compliance/img/license_list_v13_0.png Binary files differindex 3964c837c6a..3c15d4fc99a 100644 --- a/doc/user/compliance/license_compliance/img/license_list_v13_0.png +++ b/doc/user/compliance/license_compliance/img/license_list_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/policies_v13_0.png b/doc/user/compliance/license_compliance/img/policies_v13_0.png Binary files differindex 4712d2b7aba..4918a0e6b62 100644 --- a/doc/user/compliance/license_compliance/img/policies_v13_0.png +++ b/doc/user/compliance/license_compliance/img/policies_v13_0.png diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index fb287fb2bf6..47f14b93d29 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -9,10 +9,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -## Overview - -If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses -using License Compliance. +If you're using [GitLab CI/CD](../../../ci/README.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 +each license. For example, if your application uses an external (open source) library whose license +is incompatible with yours, then you can deny the use of that license. You can take advantage of License Compliance by either [including the job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using @@ -24,7 +24,9 @@ source and target branches, and shows the information right on the merge request Denied licenses will be clearly visible with an `x` red icon next to them as well as new licenses which need a decision from you. In addition, you can [manually allow or deny](#policies) -licenses in your project's license compliance policy section. +licenses in your project's license compliance policy section. If GitLab detects a denied license +in a new commit, GitLab blocks any merge requests containing that commit and instructs the developer +to remove the license. NOTE: **Note:** If the license compliance report doesn't have anything to compare to, no information @@ -48,29 +50,23 @@ You can view and modify existing policies from the [policies](#policies) tab.  -## Use cases - -It helps you find what licenses your project uses in its dependencies, and decide for each of then -whether to allow it or forbid it. For example, your application is using an external (open source) -library whose license is incompatible with yours. - ## Supported languages and package managers The following languages and package managers are supported. -| Language | Package managers | Scan Tool | -|------------|-------------------------------------------------------------------|----------------------------------------------------------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| .NET | [Nuget](https://www.nuget.org/) (.NET Framework is supported via the [mono project](https://www.mono-project.com/). Windows specific dependencies are not supported at this time.) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Python | [pip](https://pip.pypa.io/en/stable/) (Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock).) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Ruby | [gem](https://rubygems.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Language | Package managers | Notes | Scan Tool | +|------------|------------------|-------|-----------| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | | [License Finder](https://github.com/pivotal/LicenseFinder) | +| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | [License Finder](https://github.com/pivotal/LicenseFinder) | +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | [License Finder](https://github.com/pivotal/LicenseFinder) | +| .NET | [Nuget](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | [License Finder](https://github.com/pivotal/LicenseFinder) | +| Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | [License Finder](https://github.com/pivotal/LicenseFinder) | +| Ruby | [gem](https://rubygems.org/) | | [License Finder](https://github.com/pivotal/LicenseFinder)| +| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) | | [License Finder](https://github.com/pivotal/LicenseFinder) | NOTE: **Note:** - Java 8 and Gradle 1.x projects are not supported. +The minimum supported version of Maven is 3.2.5. ### Experimental support @@ -79,15 +75,15 @@ which means that the reported licenses might be incomplete or inaccurate. | Language | Package managers | Scan Tool | |------------|-------------------------------------------------------------------|----------------------------------------------------------| -| JavaScript | [yarn](https://yarnpkg.com/)|[License Finder](https://github.com/pivotal/LicenseFinder)| +| JavaScript | [Yarn](https://yarnpkg.com/)|[License Finder](https://github.com/pivotal/LicenseFinder)| | Go | go get, gvt, glide, dep, trash, govendor |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Erlang | [rebar](https://www.rebar3.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Erlang | [Rebar](https://www.rebar3.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| | Objective-C, Swift | [CocoaPods](https://cocoapods.org/) v0.39 and below |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Elixir | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| C++/C | [conan](https://conan.io/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| C++/C | [Conan](https://conan.io/) |[License Finder](https://github.com/pivotal/LicenseFinder)| | Scala | [sbt](https://www.scala-sbt.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Rust | [cargo](https://crates.io) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| PHP | [composer](https://getcomposer.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Rust | [Cargo](https://crates.io) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| PHP | [Composer](https://getcomposer.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| ## Requirements @@ -106,24 +102,19 @@ For older versions of GitLab from 11.9 to 12.7, you must For GitLab versions earlier than 11.9, you can copy and use the job as defined that template. -NOTE: **Note:** -GitLab 13.0 removes the `License-Management.gitlab-ci.yml` template. -Use `License-Scanning.gitlab-ci.yml` instead. - Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml ``` -The included template will create a `license_scanning` job in your CI/CD pipeline -and scan your dependencies to find their licenses. +The included template creates a `license_scanning` job in your CI/CD pipeline and scans your +dependencies to find their licenses. NOTE: **Note:** -Before GitLab 12.8, the `license_scanning` job was named `license_management`. -GitLab 13.0 removes the `license_management` job, -so you're advised to migrate to the `license_scanning` job and used the new +Before GitLab 12.8, the `license_scanning` job was named `license_management`. GitLab 13.0 removes +the `license_management` job, so you must migrate to the `license_scanning` job and use the new `License-Scanning.gitlab-ci.yml` template. The results will be saved as a @@ -175,7 +166,7 @@ For example: ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml variables: LICENSE_MANAGEMENT_SETUP_CMD: sh my-custom-install-script.sh @@ -196,7 +187,7 @@ after the template inclusion and specify any additional keys under it. For examp ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: variables: @@ -211,7 +202,7 @@ Feel free to use it for the customization of Maven execution. For example: ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: variables: @@ -239,7 +230,7 @@ or internally trusted certificate. For example: ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: variables: @@ -262,7 +253,7 @@ by setting the `LM_PYTHON_VERSION` environment variable to `2`. ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: variables: @@ -282,7 +273,7 @@ to inject a custom [`pip.conf`](https://pip.pypa.io/en/stable/user_guide/#config ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: variables: @@ -339,13 +330,13 @@ strict-ssl = false ### Configuring Yarn projects -You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc) +You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc/) file. #### Using private Yarn registries If you have a private Yarn registry you can use the -[`npmRegistryServer`](https://yarnpkg.com/configuration/yarnrc#npmRegistryServer) +[`npmRegistryServer`](https://yarnpkg.com/configuration/yarnrc/#npmRegistryServer) setting to specify its location. For example: @@ -385,6 +376,8 @@ You can supply a custom root certificate to complete TLS verification by using t specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) file. +### Configuring Bundler projects + #### Using private Bundler registries If you have a private Bundler registry you can use the @@ -405,6 +398,63 @@ specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1. [environment variable](../../../ci/variables/README.md#custom-environment-variables) in the job definition. +### Configuring Cargo projects + +#### Using private Cargo registries + +If you have a private Cargo registry you can use the +[`registries`](https://doc.rust-lang.org/cargo/reference/registries.html) +setting to specify its location. + +For example: + +```toml +[registries] +my-registry = { index = "https://my-intranet:8080/git/index" } +``` + +#### Custom root certificates for Cargo + +To supply a custom root certificate to complete TLS verification, do one of the following: + +- Use the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +- Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) + [environment variable](../../../ci/variables/README.md#custom-environment-variables) + in the job definition. + +### Configuring Composer projects + +#### Using private Composer registries + +If you have a private Composer registry you can use the +[`repositories`](https://getcomposer.org/doc/05-repositories.md) +setting to specify its location. + +For example: + +```json +{ + "repositories": [ + { "packagist.org": false }, + { + "type": "composer", + "url": "https://composer.example.com" + } + ], + "require": { + "monolog/monolog": "1.0.*" + } +} +``` + +#### Custom root certificates for Composer + +You can supply a custom root certificate to complete TLS verification by using the +`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), or by +specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) +[environment variable](../../../ci/variables/README.md#custom-environment-variables) +in the job definition. + ### Configuring Conan projects You can configure [Conan](https://conan.io/) projects by adding a `.conan` directory to your @@ -503,7 +553,7 @@ environment variable. For example: ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: variables: @@ -560,7 +610,7 @@ Should be changed to: ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: artifacts: @@ -625,7 +675,7 @@ the License Compliance Docker image hosted on your local Docker container regist ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: image: @@ -645,6 +695,16 @@ Additional configuration may be needed for connecting to [private Python repositories](#using-private-python-repos), and [private Yarn registries](#using-private-yarn-registries). +### SPDX license list name matching + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212388) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 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) +with identifiers from the [SPDX license list](https://spdx.org/licenses/). +A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab +instance's administrator can manually update it with a [Rake task](../../../raketasks/spdx.md). + Exact name matches are required for [project policies](#policies) when running in an offline environment ([see related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212388)). @@ -675,10 +735,16 @@ in your project's sidebar, and you'll see the licenses displayed, where: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -The **Policies** tab allows you to see your project's software license policies -and the associated classifications for each. +Policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` +license is newly committed it will disallow a merge request and instruct the developer to remove it. +Note, the merge request will not be able to be merged until the `denied` license is removed. +You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), +which enables a designated approver that can approve and then merge a merge request with `denied` license. + + -Policies can be configured by maintainers of the project. +The **Policies** tab in the project's license compliance section displays your project's license +policies. Project maintainers can specify policies in this section.   @@ -742,7 +808,7 @@ project's `.gitlab-ci.yml` file. ```yaml include: - - template: License-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml license_scanning: variables: diff --git a/doc/user/discussions/img/quickly_assign_commenter_v13_1.png b/doc/user/discussions/img/quickly_assign_commenter_v13_1.png Binary files differindex e19a3ed4f75..7f8ce62fe88 100644 --- a/doc/user/discussions/img/quickly_assign_commenter_v13_1.png +++ b/doc/user/discussions/img/quickly_assign_commenter_v13_1.png diff --git a/doc/user/discussions/img/resolve_thread_button.png b/doc/user/discussions/img/resolve_thread_button.png Binary files differdeleted file mode 100644 index ca0a3e50550..00000000000 --- a/doc/user/discussions/img/resolve_thread_button.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_thread_button_v13_3.png b/doc/user/discussions/img/resolve_thread_button_v13_3.png Binary files differnew file mode 100644 index 00000000000..1d7b10ce25d --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_button_v13_3.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 599f46b2c40..f39d0d6c217 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,7 +1,8 @@ --- -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/#designated-technical-writers +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/#designated-technical-writers" +type: reference, howto --- # Threads @@ -89,15 +90,20 @@ When a link of a commit reference is found in a thread inside a merge request, it will be automatically converted to a link in the context of the current merge request. -### Jumping between unresolved threads +### Jumping between unresolved threads (deprecated) + +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/199718) in GitLab 13.3. +> - This button's removal is behind a feature flag enabled by default. +> - For GitLab self-managed instances, GitLab administrators with access to the + [GitLab Rails console](../../administration/feature_flags.md) can opt to disable it by running + `Feature.disable(:hide_jump_to_next_unresolved_in_threads)` (for the instance) or + `Feature.disable(:hide_jump_to_next_unresolved_in_threads, Project.find(<project id>))` + (per project.) **(CORE ONLY)** When a merge request has a large number of comments it can be difficult to track what remains unresolved. You can jump between unresolved threads with the Jump button next to the Reply field on a thread. -You can also jump to the next unresolved thread from the button next to the -resolved threads tracker. - You can also use keyboard shortcuts to navigate among threads: - Use <kbd>n</kbd> to jump to the next unresolved thread. @@ -110,7 +116,7 @@ You can also use keyboard shortcuts to navigate among threads: You can mark a thread as resolved by clicking the **Resolve thread** button at the bottom of the thread. - + Alternatively, you can mark each comment as resolved individually. @@ -242,7 +248,7 @@ After you click on the image, a comment form will be displayed that would be the of your thread. Once you save your comment, you will see a new badge displayed on top of your image. This badge represents your thread. ->**Note:** +NOTE: **Note:** This thread badge is typically associated with a number that is only used as a visual reference for each thread. In the merge request thread tab, this badge will be indicated with a comment icon since each thread will render a new diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index bcaba97cab7..aa9e6715335 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -29,7 +29,10 @@ gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAA ## Mail configuration GitLab.com sends emails from the `mg.gitlab.com` domain via [Mailgun](https://www.mailgun.com/) and has -its own dedicated IP address (`198.61.254.240`). +its own dedicated IP address (`192.237.158.143`). + +NOTE: **Note:** +The IP address for `mg.gitlab.com` is subject to change at any time. ## Backups @@ -81,6 +84,7 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | Artifacts [expiry time](../../ci/yaml/README.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | deleted after 30 days unless otherwise specified | | Scheduled Pipeline Cron | `*/5 * * * *` | `19 * * * *` | | [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 pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | | [Max number of instance level variables](../../administration/instance_limits.md#number-of-instance-level-variables) | `25` | `25` | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs-core-only) | 3 months | Never | @@ -112,12 +116,13 @@ All our runners are deployed into Google Cloud Platform (GCP) - any IP based firewall can be configured by looking up all [IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). -## Maximum number of webhooks +## Webhooks A limit of: - 100 webhooks applies to projects. - 50 webhooks applies to groups. **(BRONZE ONLY)** +- Payload is limited to 25MB ## Shared Runners @@ -212,10 +217,6 @@ sentry_dsn = "X" [runners.machine] IdleCount = 50 IdleTime = 3600 - OffPeakPeriods = ["* * * * * sat,sun *"] - OffPeakTimezone = "UTC" - OffPeakIdleCount = 15 - OffPeakIdleTime = 3600 MaxBuilds = 1 # For security reasons we delete the VM after job has finished so it's not reused. MachineName = "srm-%s" MachineDriver = "google" @@ -233,6 +234,16 @@ sentry_dsn = "X" "engine-opt=fixed-cidr-v6=fc00::/7", "google-operation-backoff-initial-interval=2" # Custom flag from forked docker-machine, for more information check https://github.com/docker/machine/pull/4600 ] + [[runners.machine.autoscaling]] + Periods = ["* * * * * sat,sun *"] + Timezone = "UTC" + IdleCount = 70 + IdleTime = 3600 + [[runners.machine.autoscaling]] + Periods = ["* 30-59 3 * * * *", "* 0-30 4 * * * *"] + Timezone = "UTC" + IdleCount = 700 + IdleTime = 3600 [runners.cache] Type = "gcs" Shared = true diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 89e0c4898fb..e61b24f84f6 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -84,7 +84,7 @@ your cluster, which can cause deployment jobs to fail. To clear the cache: -1. Navigate to your group’s **{cloud-gear}** **Kubernetes** page, +1. Navigate to your group’s **Kubernetes** page, and select your cluster. 1. Expand the **Advanced settings** section. 1. Click **Clear cluster cache**. diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index ebeacda24c6..fd8d966fbe1 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -9,8 +9,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6. -When you create a new [project](../project/index.md), creating it based on custom project templates is -a convenient option. +Custom project templates are useful for organizations that need to create many similar types of [projects](../project/index.md) and want to start from the same jumping-off point. + +## Setting up Group-level Project Templates + +To use a custom project template for a new project you need to: + +1. [Create a 'templates' subgroup](subgroups/index.md). +1. [Add repositories (projects) to the that new subgroup](index.md#add-projects-to-a-group), as your templates. +1. Edit your group's settings to look to your 'templates' subgroup for templates: + 1. In the left-hand menu, click **{settings}** **Settings > General**. + + NOTE: **Note:** + If you don't have access to the group's settings, you may not have sufficient privileges (for example, you may need developer or higher permissions). + + 1. Scroll to **Custom project templates** and click **Expand**. If no **Custom project templates** section displays, make sure you've created a subgroup, and added a project (repository) to it. + 1. Select the 'templates' subgroup. + +### Example structure + +Here is a sample group/project structure for a hypothetical "Acme Co" for project templates: + +```txt +# GitLab instance and group +gitlab.com/acmeco/ + # Subgroups + internal + tools + # Subgroup for handling project templates + websites + templates + # Project templates + client-site-django + client-site-gatsby + client-site-hTML + + # Other projects + client-site-a + client-site-b + client-site-c + ... +``` + +### Adjust Settings Users can configure a GitLab group that serves as template source under a group's **Settings > General > Custom project templates**. diff --git a/doc/user/group/epics/img/epic_activity_sort_order_v13_2.png b/doc/user/group/epics/img/epic_activity_sort_order_v13_2.png Binary files differindex c7e1448fea9..ce85efe3e67 100644 --- a/doc/user/group/epics/img/epic_activity_sort_order_v13_2.png +++ b/doc/user/group/epics/img/epic_activity_sort_order_v13_2.png diff --git a/doc/user/group/epics/img/issue_list_v13_1.png b/doc/user/group/epics/img/issue_list_v13_1.png Binary files differindex f08f774e986..ed0b4842bfe 100644 --- a/doc/user/group/epics/img/issue_list_v13_1.png +++ b/doc/user/group/epics/img/issue_list_v13_1.png diff --git a/doc/user/group/epics/img/new_epic_form_v13.2.png b/doc/user/group/epics/img/new_epic_form_v13.2.png Binary files differindex 3d24763d105..ac1450ae111 100644 --- a/doc/user/group/epics/img/new_epic_form_v13.2.png +++ b/doc/user/group/epics/img/new_epic_form_v13.2.png diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png b/doc/user/group/epics/img/new_epic_from_groups_v13.2.png Binary files differindex 85bc4255595..bb75605af60 100644 --- a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png +++ b/doc/user/group/epics/img/new_epic_from_groups_v13.2.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index a2b04e2d7fe..04b57d13828 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -20,6 +20,10 @@ An epic's page contains the following tabs: shown in a tree view. - Click the chevron (**>**) next to a parent epic to reveal the child epics and issues. - Hover over the total counts to see a breakdown of open and closed items. + + NOTE: **Note:** + The number provided here includes all epics associated with this project. The number includes epics for which users may not currently have permission. + - **Roadmap**: a roadmap view of child epics which have start and due dates.  @@ -65,7 +69,8 @@ to add an issue to an epic, reorder issues, move issues between epics, or promot ## Issue health status in Epic tree **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - The health status of a closed issue [will be hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. You can report on and quickly respond to the health of individual issues and epics by setting a red, amber, or green [health status on an issue](../../project/issues/index.md#health-status-ultimate), @@ -175,7 +180,7 @@ Once you write your comment, you can either: ### Activity sort order -> [Introduced](https://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 Premium](https://about.gitlab.com/pricing/) 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 issue diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 4f9bb0e24fb..aaa5d3a3034 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -151,9 +151,18 @@ The sort option and order is saved and used wherever you browse epics, including > - [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. -When you're creating an epic, you can make it confidential by selecting the **Make this epic -confidential** checkbox. +If you're working on items that contain private information, you can make an epic confidential. + +NOTE: **Note:** +A confidential epic can only contain confidential issues and confidential child epics. + +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 + select **Turn on**. ### Disable confidential epics **(PREMIUM ONLY)** @@ -271,6 +280,16 @@ The following issue metadata will be copied to the epic: - Upvotes/downvotes. - Participants. - Group labels that the issue already has. +- Parent epic. **(ULTIMATE)** + +### Use an epic template for repeating issues + +You can create a spreadsheet template to manage a pattern of consistently repeating issues. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an introduction to epic templates, see [GitLab Epics and Epic Template Tip](https://www.youtube.com/watch?v=D74xKFNw8vg). + +For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/product-marketing/getting-started/104/). ## Manage multi-level child epics **(ULTIMATE)** diff --git a/doc/user/group/img/add_new_members.png b/doc/user/group/img/add_new_members.png Binary files differindex 6d43e309e84..8bd9e2374bc 100644 --- a/doc/user/group/img/add_new_members.png +++ b/doc/user/group/img/add_new_members.png diff --git a/doc/user/group/img/ldap_sync_cn_v13_1.png b/doc/user/group/img/ldap_sync_cn_v13_1.png Binary files differindex 1b0a20b7e64..279b3192328 100644 --- a/doc/user/group/img/ldap_sync_cn_v13_1.png +++ b/doc/user/group/img/ldap_sync_cn_v13_1.png diff --git a/doc/user/group/img/ldap_sync_filter_v13_1.png b/doc/user/group/img/ldap_sync_filter_v13_1.png Binary files differindex 3fc1f28becd..655bed58d46 100644 --- a/doc/user/group/img/ldap_sync_filter_v13_1.png +++ b/doc/user/group/img/ldap_sync_filter_v13_1.png diff --git a/doc/user/group/img/manual_permissions_v13_1.png b/doc/user/group/img/manual_permissions_v13_1.png Binary files differindex 504e6ab3a42..0ada9a4839c 100644 --- a/doc/user/group/img/manual_permissions_v13_1.png +++ b/doc/user/group/img/manual_permissions_v13_1.png diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 5ba0680127c..22ad311ab4f 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -219,7 +219,7 @@ 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}** **Settings > General** page. +1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. 1. Select the desired option in the **Default branch protection** dropdown list. 1. Click **Save changes**. @@ -278,7 +278,7 @@ The group details view also shows the number of the following items created in t - Issues. - Members. -These Group Activity Analytics can be enabled with the `group_activity_analytics` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-in-development). +These Group Activity Analytics can be enabled with the `group_activity_analytics` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development).  @@ -334,7 +334,7 @@ To share a given group, for example, 'Frontend' with another group, for example, All the members of the 'Engineering' group will have been added to 'Frontend'. -## Manage group memberships via LDAP +## Manage group memberships via LDAP **(STARTER ONLY)** Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that will be associated with GitLab groups. @@ -426,6 +426,7 @@ When transferring groups, note: - You must update your local repositories to point to the new location. - If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects will change to match the new parent group's visibility. - Only explicit group membership is transferred, not inherited membership. If the group's owners have only inherited membership, this leaves the group without an owner. In this case, the user transferring the group becomes the group's owner. +- Transfers will fail if [packages](../packages/index.md) exist in any of the projects within the group, or in any of its subgroups. ## Group settings @@ -442,7 +443,7 @@ access further configurations for your group. #### Changing a group's path -Changing a group's path can have unintended side effects. Read +Changing a group's path (group URL) can have unintended side effects. Read [how redirects will behave](../project/index.md#redirects-when-changing-repository-paths) before proceeding. @@ -450,12 +451,12 @@ If you are vacating the path so it can be claimed by another group or user, you may need to rename the group too, since both names and paths must be unique. -To change your group path: +To change your group path (group URL): 1. Navigate to your group's **Settings > General** page. 1. Expand the **Path, transfer, remove** section. -1. Enter a new name under **Change group path**. -1. Click **Change group path**. +1. Enter a new name under **Change group URL**. +1. Click **Change group URL**. CAUTION: **Caution:** It is currently not possible to rename a namespace if it contains a @@ -471,7 +472,7 @@ username, you can create a new group and transfer projects to it. To remove a group and its contents: -1. Navigate to your group's **{settings}** **Settings > General** page. +1. Navigate to your group's **Settings > General** page. 1. Expand the **Path, transfer, remove** section. 1. In the Remove group section, click the **Remove group** button. 1. Confirm the action when asked to. @@ -479,7 +480,7 @@ To remove a group and its contents: This action either: - Removes the group, and also queues a background job to delete all projects in that group. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). ### Restore a group **(PREMIUM)** @@ -487,7 +488,7 @@ This action either: To restore a group that is marked for deletion: -1. Navigate to your group's **{settings}** **Settings > General** page. +1. Navigate to your group's **Settings > General** page. 1. Expand the **Path, transfer, remove** section. 1. In the Restore group section, click the **Restore group** button. @@ -659,7 +660,7 @@ Optionally, on [Premium or Silver](https://about.gitlab.com/pricing/) or higher you can configure the projects within a group to be deleted after a delayed interval. During this interval period, the projects will be in a read-only state and can be restored, if required. -The interval period defaults to 7 days, and can be modified by an admin in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only). +The interval period defaults to 7 days, and can be modified by an admin in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). To enable delayed deletion of projects: @@ -667,6 +668,23 @@ To enable delayed deletion of projects: 1. Expand the **Permissions, LFS, 2FA** section, and check **Enable delayed project removal**. 1. Click **Save changes**. +#### Prevent project forking outside group **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. + +By default, projects within a group can be forked. +Optionally, on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, +you can prevent the projects within a group from being forked outside of the current top-level group. + +Previously this setting was available only for groups enforcing group managed account. This setting will be +removed from SAML setting page and migrated to group setting, but in the interim period of changes both of those settings will be taken into consideration, if even one is set to `true` then it will be assumed group does not allow forking projects outside. + +To enable prevent project forking: + +1. Navigate to the top-level group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section, and check **Prevent project forking outside current group**. +1. Click **Save changes**. + ### Advanced settings - **Projects**: View all projects within that group, add members to each project, @@ -725,9 +743,9 @@ With [GitLab Contribution Analytics](contribution_analytics/index.md), you have an overview of the contributions (pushes, merge requests, and issues) performed by your group members. -## Issues analytics **(PREMIUM)** +## Issue analytics **(PREMIUM)** -With [GitLab Issues Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups. +With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups. ## Dependency Proxy **(PREMIUM)** diff --git a/doc/user/group/issues_analytics/img/issues_table_v13_1.png b/doc/user/group/issues_analytics/img/issues_table_v13_1.png Binary files differindex 0f94f1ba2c5..3e8a729a884 100644 --- a/doc/user/group/issues_analytics/img/issues_table_v13_1.png +++ b/doc/user/group/issues_analytics/img/issues_table_v13_1.png diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 01cee3d09b8..69512f90fca 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -5,16 +5,16 @@ group: Analytics 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 --- -# Issues Analytics **(PREMIUM)** +# 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/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the project level. -Issues Analytics is a bar graph which illustrates the number of issues created each month. +Issue Analytics is a bar graph which illustrates the number of issues created each month. The default timespan is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your group or project sidebar and select **{chart}** **Analytics > Issues Analytics**. +To access the chart, navigate to your group or project sidebar and select **{chart}** **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index e317573d89d..126970ebbb6 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -7,13 +7,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Group Managed Accounts **(PREMIUM)** -CAUTION: **Warning:** -This is a [Closed Beta](https://about.gitlab.com/handbook/product/#closed-beta) feature. +CAUTION: **Caution:** +This [Closed Beta](https://about.gitlab.com/handbook/product/#closed-beta) feature is being re-evaluated in favor of a different +[identity model](https://gitlab.com/gitlab-org/gitlab/-/issues/218631) that does not require separate accounts. +We recommend that group administrators who haven't yet implemented this feature wait for +the new solution. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/709) in GitLab 12.1. > - It's deployed behind a feature flag, disabled by default. -When [SSO for Groups](index.md) is being enforced, groups can enable an additional level of protection by enforcing the creation of dedicated user accounts to access the group. +When [SSO for Groups](index.md) is enforced, groups can enable an additional level of protection by enforcing the creation of dedicated user accounts to access the group. With group-managed accounts enabled, users are required to create a new, dedicated user linked to the group. The notification email address associated with the user is locked to the email address received from the configured identity provider. @@ -21,8 +24,8 @@ Without group-managed accounts, users can link their SAML identity with any exis When this option is enabled: -- All users in the group will be required to log in via the SSO URL associated with the group. -- After the group-managed account has been created, group activity will require the use of this user account. +- All users in the group are required to log in via the SSO URL associated with the group. +- After the group-managed account has been created, group activity requires the use of this user account. - Users can't share a project in the group outside the top-level group (also applies to forked projects). Upon successful authentication, GitLab prompts the user with options, based on the email address received from the configured identity provider: @@ -30,10 +33,10 @@ Upon successful authentication, GitLab prompts the user with options, based on t - To create a unique account with the newly received email address. - If the received email address matches one of the user's verified GitLab email addresses, the option to convert the existing account to a group-managed account. ([Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/13481).) -Since use of the group-managed account requires the use of SSO, users of group-managed accounts will lose access to these accounts when they are no longer able to authenticate with the connected identity provider. In the case of an offboarded employee who has been removed from your identity provider: +Since use of the group-managed account requires the use of SSO, users of group-managed accounts lose access to these accounts when they are no longer able to authenticate with the connected identity provider. In the case of an offboarded employee who has been removed from your identity provider: -- The user will be unable to access the group (their credentials will no longer work on the identity provider when prompted to SSO). -- Contributions in the group (e.g. issues, merge requests) will remain intact. +- The user is unable to access the group (their credentials no longer work on the identity provider when prompted to use SSO). +- Contributions in the group (for example, issues and merge requests) remains intact. ## Assertions @@ -49,7 +52,7 @@ assertions to be able to create a user. ## Feature flag **(PREMIUM ONLY)** -Currently the group-managed accounts feature is behind a feature flag: `group_managed_accounts`. The flag is disabled by default. +The group-managed accounts feature is behind a feature flag: `group_managed_accounts`. The flag is disabled by default. To activate the feature, ask a GitLab administrator with Rails console access to run: ```ruby @@ -101,16 +104,16 @@ Since personal access tokens are the only token needed for programmatic access t ### Setting a limit -Only a GitLab administrator or an owner of a Group-managed account can set a limit. Leaving it empty means that the [instance level restrictions](../../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only) on the lifetime of personal access tokens will apply. +Only a GitLab administrator or an owner of a group-managed account can set a limit. When this field is left empty, the [instance-level restriction](../../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only) on the lifetime of personal access tokens apply. To set a limit on how long personal access tokens are valid for users in a group managed account: -1. Navigate to the **{settings}** **Settings > General** page in your group's sidebar. +1. Navigate to the **Settings > General** page in your group's sidebar. 1. Expand the **Permissions, LFS, 2FA** section. 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. -Once a lifetime for personal access tokens is set, GitLab will: +Once a lifetime for personal access tokens is set: -- Apply the lifetime for new personal access tokens, and require users managed by the group to set an expiration date that is no later than the allowed lifetime. +- GitLab applies the lifetime for new personal access tokens and requires users managed by the group to set an expiration date that's no later than the allowed lifetime. - After three hours, revoke old tokens with no expiration date or with a lifetime longer than the allowed lifetime. Three hours is given to allow administrators/group owner to change the allowed lifetime, or remove it, before revocation takes place. diff --git a/doc/user/group/saml_sso/img/group_saml_settings.png b/doc/user/group/saml_sso/img/group_saml_settings.png Binary files differdeleted file mode 100644 index 487be4faeba..00000000000 --- a/doc/user/group/saml_sso/img/group_saml_settings.png +++ /dev/null diff --git a/doc/user/group/saml_sso/img/group_saml_settings_v13_3.png b/doc/user/group/saml_sso/img/group_saml_settings_v13_3.png Binary files differnew file mode 100644 index 00000000000..f6450c7c1ba --- /dev/null +++ b/doc/user/group/saml_sso/img/group_saml_settings_v13_3.png diff --git a/doc/user/group/saml_sso/img/scim_token.png b/doc/user/group/saml_sso/img/scim_token.png Binary files differdeleted file mode 100644 index bf9347716e9..00000000000 --- a/doc/user/group/saml_sso/img/scim_token.png +++ /dev/null diff --git a/doc/user/group/saml_sso/img/scim_token_v13_3.png b/doc/user/group/saml_sso/img/scim_token_v13_3.png Binary files differnew file mode 100644 index 00000000000..e98f755718a --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_token_v13_3.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index afd676cf897..f0d0fbff158 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -18,6 +18,8 @@ If you follow our guidance to automate user provisioning using [SCIM](scim_setup User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. +SAML SSO is not supported at the subgroup level, + ## Configuring your Identity Provider 1. Navigate to the group and click **Settings > SAML SSO**. @@ -63,10 +65,11 @@ Once you've set up your identity provider to work with GitLab, you'll need to co 1. Navigate to the group's **Settings > SAML SSO**. 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. +1. Select the access level to be applied to newly added users in the **Default membership role** field. The default access level is 'Guest'. 1. Click the **Enable SAML authentication for this group** toggle switch. 1. Click the **Save changes** button. - + NOTE: **Note:** Please note that the certificate [fingerprint algorithm](#additional-providers-and-setup-options) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. @@ -79,6 +82,7 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. However, users will not be prompted to sign in through SSO on each visit. GitLab will check whether a user has authenticated through SSO, and will only prompt the user to sign in via SSO if the session has expired. +You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). @@ -94,7 +98,7 @@ GitLab is unable to provide support for IdPs that are not listed here. | Provider | Documentation | |----------|---------------| | ADFS (Active Directory Federation Services) | [Create a Relying Party Trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) | -| Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications) | +| Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) | | Okta | [Setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) | | OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) | @@ -160,7 +164,7 @@ For more information, see our [discussion on providers](#providers). Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. Examples: -- [Auth0](https://auth0.com/docs/protocols/saml/saml-idp-generic) +- [Auth0](https://auth0.com/docs/protocols/saml-configuration-options/configure-auth0-as-saml-identity-provider) - [G Suite](https://support.google.com/a/answer/6087519?hl=en) - [JumpCloud](https://support.jumpcloud.com/support/s/article/single-sign-on-sso-with-gitlab-2019-08-21-10-36-47) - [PingOne by Ping Identity](https://docs.pingidentity.com/bundle/pingone/page/xsh1564020480660-1.html) @@ -216,7 +220,9 @@ On subsequent visits, you should be able to go [sign in to GitLab.com with SAML] ### Role -The first time you sign in, GitLab adds you to the top-level parent group with the Guest role. Existing members with appropriate privileges can promote that new user. +Starting from [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523), group owners can set a 'Default membership role' other than 'Guest'. To do so, [configure the SAML SSO for the group](#configuring-gitlab). That role becomes the starting access level of all users added to the group. + +Existing members with appropriate privileges can promote or demote users, as needed. If a user is already a member of the group, linking the SAML identity does not change their role. @@ -268,7 +274,7 @@ Group SAML on a self-managed instance is limited when compared to the recommende [instance-wide SAML](../../../integration/saml.md). The recommended solution allows you to take advantage of: - [LDAP compatibility](../../../administration/auth/ldap/index.md). -- [LDAP Group Sync](../index.md#manage-group-memberships-via-ldap). +- [LDAP Group Sync](../index.md#manage-group-memberships-via-ldap-starter-only). - [Required groups](../../../integration/saml.md#required-groups-starter-only). - [Admin groups](../../../integration/saml.md#admin-groups-starter-only). - [Auditor groups](../../../integration/saml.md#auditor-groups-starter-only). @@ -297,6 +303,10 @@ Group SAML on a self-managed instance is limited when compared to the recommende - { name: 'group_saml' } ``` +## Passwords for users created via SAML SSO for Groups + +The [Generated passwords for users created through integrated authentication](../../../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via SAML SSO for Groups. + ## Troubleshooting This section contains possible solutions for problems you might encounter. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 13e9d623e2c..9a2bd2e8806 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -40,7 +40,7 @@ Once [Group Single Sign-On](index.md) has been configured, we can: 1. Click on the **Generate a SCIM token** button. 1. Save the token and URL so they can be used in the next step. - + ## Identity Provider configuration @@ -49,7 +49,7 @@ Once [Group Single Sign-On](index.md) has been configured, we can: ### Azure configuration steps -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/configure-single-sign-on-non-gallery-applications) now needs to be set up for SCIM. +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. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab. @@ -217,6 +217,10 @@ As a workaround, try an alternate mapping: #### How do I diagnose why a user is unable to sign in +Ensure that the user has been added to the SCIM app. + +If you receive "User is not linked to a SAML account", then most likely the user already exists in GitLab. Have the user follow the [User access and linking setup](#user-access-and-linking-setup) instructions. + The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users won't be able to sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index cca918d44f3..ae83c8da462 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -21,7 +21,7 @@ See also: To enable GitLab import/export: -1. Navigate to **{admin}** **Admin Area >** **{settings}** **Settings > Visibility and access controls**. +1. Navigate to **Admin Area > Settings > Visibility and access controls**. 1. Scroll to **Import sources** 1. Enable desired **Import sources** @@ -33,13 +33,13 @@ Note the following: - To preserve group-level relationships from imported projects, run the Group Import/Export first, to allow projects to be imported into the desired group structure. - Imported groups are given a `private` visibility level, unless imported into a parent group. -- If imported into a parent group, subgroups will inherit the same level of visibility unless otherwise restricted. +- If imported into a parent group, a subgroup inherits the same level of visibility unless otherwise restricted. - 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 -The following items will be exported: +The following items are exported: - Milestones - Labels @@ -49,7 +49,7 @@ The following items will be exported: - Epics - Events -The following items will NOT be exported: +The following items are **not** exported: - Projects - Runners token @@ -63,7 +63,7 @@ For more details on the specific data persisted in a group export, see the 1. Navigate to your group's homepage. -1. Click **{settings}** **Settings** in the sidebar. +1. Click **Settings** in the sidebar. 1. In the **Advanced** section, click the **Export Group** button. @@ -83,7 +83,7 @@ As an administrator, you can modify the maximum import file size. To do so, use You can export groups from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. -If you're exporting a group from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../README.md). +The Enterprise Edition retains some group data that isn't part of the Community Edition. If you're exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, see [downgrading from EE to CE](../../../README.md). ## Importing the group @@ -104,7 +104,7 @@ on an existing group's page. 1. Select the file that you exported in the [exporting a group](#exporting-a-group) section. -1. Click **Import group** to begin importing. Your newly imported group page will appear shortly. +1. Click **Import group** to begin importing. Your newly imported group page appears after the operation completes. ## Version history diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index a370c9cf136..235855b6e3a 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -7,13 +7,12 @@ type: reference, howto, concepts > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2772) in GitLab 9.0. GitLab supports up to 20 levels of subgroups, also known as nested groups or hierarchical groups. -levels of groups. By using subgroups you can do the following: - **Separate internal / external organizations.** Since every group - can have its own visibility level, you are able to host groups for different - purposes under the same umbrella. + can have its own visibility level ([public, internal, or private](../../../development/permissions.md#general-permissions)), + you're able to host groups for different purposes under the same umbrella. - **Organize large projects.** For large projects, subgroups makes it potentially easier to separate permissions on parts of the source code. - **Make it easier to manage people and control visibility.** Give people diff --git a/doc/user/img/completed_tasks_v13_3.png b/doc/user/img/completed_tasks_v13_3.png Binary files differnew file mode 100644 index 00000000000..31e051852cb --- /dev/null +++ b/doc/user/img/completed_tasks_v13_3.png diff --git a/doc/user/img/inline_diff_01_v13_3.png b/doc/user/img/inline_diff_01_v13_3.png Binary files differnew file mode 100644 index 00000000000..b14317274d1 --- /dev/null +++ b/doc/user/img/inline_diff_01_v13_3.png diff --git a/doc/user/img/inline_diff_02_v13_3.png b/doc/user/img/inline_diff_02_v13_3.png Binary files differnew file mode 100644 index 00000000000..959f7014e18 --- /dev/null +++ b/doc/user/img/inline_diff_02_v13_3.png diff --git a/doc/user/incident_management/img/incident_management_settings.png b/doc/user/incident_management/img/incident_management_settings.png Binary files differdeleted file mode 100644 index 761a782ce61..00000000000 --- a/doc/user/incident_management/img/incident_management_settings.png +++ /dev/null diff --git a/doc/user/incident_management/img/pagerduty_incidents_integration_13_2.png b/doc/user/incident_management/img/pagerduty_incidents_integration_13_2.png Binary files differdeleted file mode 100644 index 9277b013676..00000000000 --- a/doc/user/incident_management/img/pagerduty_incidents_integration_13_2.png +++ /dev/null diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md index 996f423e770..3d883a6b119 100644 --- a/doc/user/incident_management/index.md +++ b/doc/user/incident_management/index.md @@ -1,136 +1,5 @@ --- -stage: Monitor -group: Health -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 +redirect_to: '../../operations/incident_management/index.md' --- -# Incident Management - -GitLab offers solutions for handling incidents in your applications and services, -such as setting up Prometheus alerts, displaying metrics, and sending notifications. - -## Configure incidents **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in GitLab Ultimate 11.11. - -You can enable or disable Incident Management features in the GitLab user interface -to create issues when alerts are triggered: - -1. Navigate to **{settings}** **Settings > Operations > Incidents** and expand - **Incidents**: - -  - -1. For GitLab versions 11.11 and greater, you can select the **Create an issue** - checkbox to create an issue based on your own - [issue templates](../project/description_templates.md#creating-issue-templates). - For more information, see - [Trigger actions from alerts](../../operations/metrics/alerts.md#trigger-actions-from-alerts-ultimate) **(ULTIMATE)**. -1. To create issues from alerts, select the template in the **Issue Template** - select box. -1. To send [separate email notifications](#notify-developers-of-alerts) to users - with [Developer permissions](../permissions.md), select - **Send a separate email notification to Developers**. -1. Click **Save changes**. - -Appropriately configured alerts include an -[embedded chart](../../operations/metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues) -for the query corresponding to the alert. You can also configure GitLab to -[close issues](../../operations/metrics/alerts.md#trigger-actions-from-alerts-ultimate) -when you receive notification that the alert is resolved. - -### Notify developers of alerts - -GitLab can react to the alerts triggered from your applications and services -by creating issues and alerting developers through email. By default, GitLab -sends these emails to [owners and maintainers](../permissions.md) of the project. -These emails contain details of the alert, and a link for more information. - -To send separate email notifications to users with -[Developer permissions](../permissions.md), see [Configure incidents](#configure-incidents-ultimate). - -## Configure PagerDuty integration - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/119018) in GitLab 13.2. - -You can set up a webhook with PagerDuty to automatically create a GitLab issue -for each PagerDuty incident. This configuration requires you to make changes -in both PagerDuty and GitLab: - -1. Sign in as a user with Maintainer [permissions](../permissions.md). -1. Navigate to **{settings}** **Settings > Operations > Incidents** and expand **Incidents**. -1. Select the **PagerDuty integration** tab: - -  - -1. Activate the integration, and save the changes in GitLab. -1. Copy the value of **Webhook URL**, as you'll need it in a later step. -1. Follow the steps described in the - [PagerDuty documentation](https://support.pagerduty.com/docs/webhooks) - to add the webhook URL to a PagerDuty webhook integration. - -To confirm the integration is successful, trigger a test incident from PagerDuty to -confirm that a GitLab issue is created from the incident. - -## Configure Prometheus alerts - -You can set up Prometheus alerts in: - -- [GitLab-managed Prometheus](../../operations/metrics/alerts.md) installations. -- [Self-managed Prometheus](../../operations/metrics/alerts.md#external-prometheus-instances) installations. - -Prometheus alerts are created by the special Alert Bot user. You can't remove this -user, but it does not count toward your license limit. - -## Configure external generic alerts - -GitLab can accept alerts from any source through a generic webhook receiver. When -[configuring the generic alerts integration](../project/integrations/generic_alerts.md), -GitLab creates a unique endpoint which receives a JSON-formatted, customizable payload. - -## Embed metrics in incidents and issues - -You can embed metrics anywhere [GitLab Markdown](../markdown.md) is used, such as descriptions, -comments on issues, and merge requests. Embedding metrics helps you share them -when discussing incidents or performance issues. You can output the dashboard directly -into any issue, merge request, epic, or any other Markdown text field in GitLab -by [copying and pasting the link to the metrics dashboard](../../operations/metrics/embed.md#embedding-gitlab-managed-kubernetes-metrics). - -You can embed both -[GitLab-hosted metrics](../../operations/metrics/embed.md) and -[Grafana metrics](../../operations/metrics/embed_grafana.md) -in incidents and issue templates. - -### Context menu - -You can view more details about an embedded metrics panel from the context menu. -To access the context menu, click the **{ellipsis_v}** **More actions** dropdown box -above the upper right corner of the panel. The options are: - -- [View logs](#view-logs-from-metrics-panel). -- **Download CSV** - Data from embedded charts can be - [downloaded as CSV](../../operations/metrics/dashboards/index.md#downloading-data-as-csv). - -#### View logs from metrics panel - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201846) in GitLab Ultimate 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. - -Viewing logs from a metrics panel can be useful if you're triaging an application -incident and need to [explore logs](../../operations/metrics/dashboards/index.md#view-logs-ultimate) -from across your application. These logs help you understand what is affecting -your application's performance and resolve any problems. - -## Integrate incidents with Slack - -Slack slash commands allow you to control GitLab and view GitLab content without leaving Slack. - -Learn how to [set up Slack slash commands](../project/integrations/slack_slash_commands.md) -and how to [use the available slash commands](../../integration/slash_commands.md). - -## Integrate issues with Zoom - -GitLab enables you to [associate a Zoom meeting with an issue](../project/issues/associate_zoom_meeting.md) -for synchronous communication during incident management. After starting a Zoom -call for an incident, you can associate the conference call with an issue. Your -team members can join the Zoom call without requesting a link. +This document was moved to [../../operations/incident_management/index.md](../../operations/incident_management/index.md). diff --git a/doc/user/index.md b/doc/user/index.md index f50b712e2c3..1ab3541575c 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,4 +1,5 @@ --- +type: reference, index description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.' --- diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index e24e669d994..2a49ca18aaf 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -50,7 +50,7 @@ If you plan to only run `terraform plan` and `terraform apply` commands from you local machine, this is a simple way to get started: 1. Create your project on your GitLab instance. -1. Navigate to **{settings}** **Settings > General** and note your **Project name** +1. Navigate to **Settings > General** and note your **Project name** and **Project ID**. 1. Define the Terraform backend in your Terraform project to be: @@ -65,16 +65,16 @@ local machine, this is a simple way to get started: the `api` scope. 1. On your local machine, run `terraform init`, passing in the following options, - replacing `<YOUR-PROJECT-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and + replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your Terraform state, and stores that state within your GitLab project. This example uses `gitlab.com`: ```shell terraform init \ - -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>" \ - -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>/lock" \ - -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>/lock" \ + -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ + -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ -backend-config="username=<YOUR-USERNAME>" \ -backend-config="password=<YOUR-ACCESS-TOKEN>" \ -backend-config="lock_method=POST" \ @@ -82,7 +82,7 @@ local machine, this is a simple way to get started: -backend-config="retry_wait_min=5" ``` -Next, [configure the backend](#configure-the-backend). +You can now run `terraform plan` and `terraform apply` as you normally would. ## Get started using GitLab CI @@ -121,17 +121,18 @@ and the CI YAML file: commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab instance where this pipeline runs, and the final path segment in `TF_ADDRESS` is the name of the Terraform state. Projects may have multiple states, and - this name is arbitrary, so in this example we will set it to the name of the - project, and we will ensure that the `.terraform` directory is cached between - jobs in the pipeline using a cache key based on the state name: + this name is arbitrary, so in this example we set it to `example-production` + which corresponds with the directory we're using as our `TF_ROOT`, and we + ensure that the `.terraform` directory is cached between jobs in the pipeline + using a cache key based on the state name (`example-production`): ```yaml variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME} + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production cache: - key: ${CI_PROJECT_NAME} + key: example-production paths: - ${TF_ROOT}/.terraform ``` @@ -189,10 +190,113 @@ and the CI YAML file: The output from the above `terraform` commands should be viewable in the job logs. +CAUTION: **Caution:** +Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan +includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly +recommends encrypting plan output or modifying the project visibility settings. + ## Example project See [this reference project](https://gitlab.com/nicholasklick/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC. +## Copy Terraform state between backends + +Terraform supports copying the state when the backend is changed or +reconfigured. This can be useful if you need to migrate from another backend to +GitLab managed Terraform state. It's also useful if you need to change the state +name as in the following example: + +```shell +PROJECT_ID="<gitlab-project-id>" +TF_USERNAME="<gitlab-username>" +TF_PASSWORD="<gitlab-personal-access-token>" +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +Now that `terraform init` has created a `.terraform/` directory that knows where +the old state is, you can tell it about the new location: + +```shell +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... +Backend configuration changed! + +Terraform has detected that the configuration specified for the backend +has changed. Terraform will now check for existing state in the backends. + + +Acquiring state lock. This may take a few moments... +Do you want to copy existing state to the new backend? + Pre-existing state was found while migrating the previous "http" backend to the + newly configured "http" backend. No existing state was found in the newly + configured "http" backend. Do you want to copy this state to the new "http" + backend? Enter "yes" to copy and "no" to start with an empty state. + + Enter a value: yes + + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +If you type `yes`, it will copy your state from the old location to the new +location. You can then go back to running it from within GitLab CI. + ## Output Terraform Plan information into a merge request Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform), @@ -275,11 +379,11 @@ can configure this manually as follows: image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME} + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production cache: - key: ${CI_PROJECT_NAME} + key: example-production paths: - ${TF_ROOT}/.terraform @@ -329,7 +433,7 @@ apply: ### Multiple Terraform Plan reports -Starting with 13.2, you can display mutiple reports on the Merge Request page. The reports will also display the `artifact: name:`. See example below for a suggested setup. +Starting with 13.2, you can display mutiple reports on the Merge Request page. The reports will also display the `artifacts: name:`. See example below for a suggested setup. ```yaml image: @@ -383,3 +487,47 @@ production_plan: artifacts: name: Production ``` + +## Using a GitLab managed Terraform state backend as a remote data source + +You can use a GitLab-managed Terraform state as a +[Terraform data source](https://www.terraform.io/docs/providers/terraform/d/remote_state.html). +To use your existing Terraform state backend as a data source, provide the following details +as [Terraform input variables](https://www.terraform.io/docs/configuration/variables.html): + +- **address**: The URL of the remote state backend you want to use as a data source. + For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. +- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for + authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. +- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for + authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI variable. + +An example setup is shown below: + +1. Create a file named `example.auto.tfvars` with the following contents: + + ```plaintext + example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> + example_username=<GitLab username> + example_access_token=<GitLab Personal Acceess Token> + ``` + +1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): + + ```hcl + data "terraform_remote_state" "example" { + backend = "http" + + config = { + address = var.example_remote_state_address + username = var.example_username + password = var.example_access_token + } + } + ``` + +Outputs from the data source can now be referenced within your Terraform resources +using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. + +You need at least [developer access](../permissions.md) to the target project +to read the Terraform state. diff --git a/doc/user/instance_statistics/dev_ops_score.md b/doc/user/instance_statistics/dev_ops_score.md index 73b9532015d..35dcbd01916 100644 --- a/doc/user/instance_statistics/dev_ops_score.md +++ b/doc/user/instance_statistics/dev_ops_score.md @@ -7,7 +7,7 @@ NOTE: **Note:** Your GitLab instance's [usage ping](../admin_area/settings/usage_statistics.md#usage-ping-core-only) must be activated in order to use this feature. The DevOps Score gives you an overview of your entire instance's adoption of -[Concurrent DevOps](https://about.gitlab.com/concurrent-devops/) +[Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) from planning to monitoring. This displays the usage of these GitLab features over diff --git a/doc/user/markdown.md b/doc/user/markdown.md index b2b3f0f925c..12d65f75b37 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,7 +1,8 @@ --- -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/#designated-technical-writers +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/#designated-technical-writers" +type: reference, howto --- # GitLab Markdown @@ -21,7 +22,7 @@ We encourage you to view this document as [rendered by GitLab itself](https://gi GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/) (which is based on standard Markdown) in several ways to add additional useful functionality. -It was inspired by [GitHub Flavored Markdown](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). +It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). You can use GFM in the following areas: @@ -78,15 +79,15 @@ character of the top list item (`C` in this case): - milk NOTE: **Note:** -We will flag any significant differences between Redcarpet and CommonMark +We flag any significant differences between Redcarpet and CommonMark Markdown in this document. If you have a large volume of Markdown files, it can be tedious to determine -if they will display correctly or not. You can use the +if they display correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and the -differences between how RedCarpet and CommonMark render the files. It can give -an indication if anything needs to be changed - often nothing will need +differences between how RedCarpet and CommonMark render the files. It gives +an indication if anything needs to be changed - often nothing needs to change. ### GFM extends standard Markdown @@ -136,7 +137,7 @@ Supported formats (named colors are not supported): - RGB: `` `RGB[A](R, G, B[, A])` `` - HSL: `` `HSL[A](H, S, L[, A])` `` -Color written inside backticks will be followed by a color "chip": +Color written inside backticks is followed by a color "chip": ```markdown - `#F00` @@ -258,10 +259,11 @@ If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-f 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"> -> **Note:** The emoji example above uses hard-coded images for this documentation. The emoji, +NOTE: **Note:** +The emoji example above uses hard-coded images for this documentation. The emoji, when rendered within GitLab, may appear different depending on the OS and browser used. -Most emoji are natively supported on macOS, Windows, iOS, Android, and will fall back on image-based emoji where there is no support. +Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based emoji where there is no support. NOTE: **Note:** On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) @@ -346,10 +348,7 @@ The wrapping tags can be either curly braces or square brackets: - [- deletion 4 -] ``` -- {+ addition 1 +} -- [+ addition 2 +] -- {- deletion 3 -} -- [- deletion 4 -] + --- @@ -363,7 +362,7 @@ However, the wrapping tags can't be mixed: ``` If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` `` with a -backslash `\`, otherwise the diff highlight won't render correctly: +backslash `\`, otherwise the diff highlight don't render correctly: ```markdown - {+ Just regular text +} @@ -371,9 +370,7 @@ backslash `\`, otherwise the diff highlight won't render correctly: - {+ Text with escaped \`backticks\` inside +} ``` -- {+ Just regular text +} -- {+ Text with `backticks` inside +} -- {+ Text with escaped \`backticks\` inside +} + ### Math @@ -381,8 +378,8 @@ backslash `\`, otherwise the diff highlight won't render correctly: It's possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX). -Math written between dollar signs `$` will be rendered inline with the text. Math written -inside a [code block](#code-spans-and-blocks) with the language declared as `math`, will be rendered +Math written between dollar signs `$` are rendered inline with the text. Math written +inside a [code block](#code-spans-and-blocks) with the language declared as `math`, are rendered on a separate line: ````markdown @@ -412,13 +409,13 @@ the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activati ### Special GitLab references GFM recognizes special GitLab related references. For example, you can reference -an issue, a commit, a team member, or even the whole team within a project. GFM will turn +an issue, a commit, a team member, or even the whole team within a project. GFM turns that reference into a link so you can navigate between them. Additionally, GFM recognizes certain cross-project references and also has a shorthand version to reference other projects from the same namespace. -GFM will recognize the following: +GFM recognizes the following: | references | input | cross-project reference | shortcut within same namespace | | :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | @@ -444,9 +441,9 @@ GFM will recognize the following: In addition to this, links to some objects are also recognized and formatted. Some examples of these are: -- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which will be rendered as `#1234 (note1)` -- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which will be rendered as `#1234 (designs)`. -- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which will be rendered as `#1234[layout.png]`. +- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (note1)` +- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. +- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. ### Task lists @@ -473,22 +470,13 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` -- [x] Completed task -- [ ] Incomplete task - - [ ] Sub-task 1 - - [x] Sub-task 2 - - [ ] Sub-task 3 - -1. [x] Completed task -1. [ ] Incomplete task - 1. [ ] Sub-task 1 - 1. [x] Sub-task 2 + ### Table of contents You can add a table of contents to a Markdown file, wiki page, or issue/merge request description, by adding the tag `[[_TOC_]]` on its own line. -It will appear as an unordered list that links to the various headers. +It appears as an unordered list that links to the various headers. ```markdown This is an intro sentence to my Wiki page. @@ -512,7 +500,7 @@ The following examples show how links inside wikis behave. #### Wiki - direct page link -A link which just includes the slug for a page will point to that page, +A link which just includes the slug for a page points to that page, _at the base level of the wiki_. This snippet would link to a `documentation` page at the root of your wiki: @@ -583,13 +571,13 @@ This snippet links to `<wiki_root>/miscellaneous.md`: ### Embedding metrics in GitLab Flavored Markdown -Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab flavored Markdown](../operations/metrics/embed.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details. +Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab flavored Markdown](../operations/metrics/embed.md) for more details. ## Standard Markdown and extensions in GitLab All standard Markdown formatting should work as expected within GitLab. Some standard functionality is extended with additional features, without affecting the standard usage. -If a functionality is extended, the new option will be listed as a sub-section. +If a functionality is extended, the new option is listed as a sub-section. ### Blockquotes @@ -602,7 +590,7 @@ by starting the lines of the blockquote with `>`: Quote break. -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +> This is a very long line that is still quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. ``` > Blockquotes are very handy to emulate reply text. @@ -610,7 +598,7 @@ Quote break. Quote break. -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +> This is a very long line that is still quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. #### Multiline blockquote @@ -825,7 +813,7 @@ do*this*and*do*that*and*another thing ### Footnotes -Footnotes add a link to a note that will be rendered at the end of a Markdown file. +Footnotes add a link to a note that are rendered at the end of a Markdown file. To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with the note content. @@ -1016,7 +1004,7 @@ Here's a sample audio clip: > To see the Markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html). -You can also use raw HTML in your Markdown, and it will usually work pretty well. +You can also use raw HTML in your Markdown, and it usually works pretty well. See the documentation for HTML::Pipeline's [SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42) class for the list of allowed HTML tags and attributes. In addition to the default @@ -1028,7 +1016,7 @@ class for the list of allowed HTML tags and attributes. In addition to the defau <dd>Is something people use sometimes.</dd> <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>work</b>, in most cases.</dd> + <dd>Does *not* work **very** well. HTML <em>tags</em> do <b>work</b>, in most cases.</dd> </dl> ``` @@ -1037,7 +1025,7 @@ class for the list of allowed HTML tags and attributes. In addition to the defau <dd>Is something people use sometimes.</dd> <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>work</b>, in most cases.</dd> + <dd>Does *not* work **very** well. HTML <em>tags</em> do <b>work</b>, in most cases.</dd> </dl> --- @@ -1048,12 +1036,12 @@ are separated into their own lines: ```html <dl> <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. HTML tags will work, in most cases.</dd> + <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd> <dt>Markdown in HTML</dt> <dd> - Does *not* work **very** well. HTML tags will work, in most cases. + Does *not* work **very** well. HTML tags work, in most cases. </dd> </dl> @@ -1061,17 +1049,17 @@ are separated into their own lines: <!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, -Markdown will be fine in GitLab. +Markdown is fine in GitLab. --> <dl> <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. HTML tags will work, in most cases.</dd> + <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd> <dt>Markdown in HTML</dt> <dd> - Does <em>not</em> work <b>very</b> well. HTML tags will work, in most cases. + Does <em>not</em> work <b>very</b> well. HTML tags work, in most cases. </dd> </dl> @@ -1089,7 +1077,7 @@ tags. This is especially useful for collapsing long logs so they take up less sc <details> <summary>Click this to collapse/fold.</summary> -These details <em>will</em> remain <strong>hidden</strong> until expanded. +These details <em>remain</em> <strong>hidden</strong> until expanded. <pre><code>PASTE LOGS HERE</code></pre> @@ -1101,7 +1089,7 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded. <details> <summary>Click this to collapse/fold.</summary> -These details <em>will</em> remain <strong>hidden</strong> until expanded. +These details <em>remain</em> <strong>hidden</strong> until expanded. <pre><code>PASTE LOGS HERE</code></pre> @@ -1124,7 +1112,7 @@ as shown in the example: <details> <summary>Click this to collapse/fold.</summary> -These details _will_ remain **hidden** until expanded. +These details _remain_ **hidden** until expanded. ``` PASTE LOGS HERE @@ -1135,13 +1123,13 @@ PASTE LOGS HERE <!-- The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown -will work correctly in GitLab. +works correctly in GitLab. --> <details> <summary>Click this to collapse/fold.</summary> -These details <em>will</em> remain <b>hidden</b> until expanded. +These details <em>remain</em> <b>hidden</b> until expanded. <pre><code>PASTE LOGS HERE</code></pre> @@ -1149,16 +1137,16 @@ These details <em>will</em> remain <b>hidden</b> until expanded. ### Line breaks -A line break will be inserted (a new paragraph will start) if the previous text is +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 will be part of the +use one newline (hit <kbd>Enter</kbd> once), the next sentence remains part of the same paragraph. This is useful if you want to keep long lines from wrapping, and keep them editable: ```markdown Here's a line for us to start with. -This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*. +This longer line is separated from the one above by two newlines, so it is a *separate paragraph*. This line is also a separate paragraph, but... These lines are only separated by single newlines, @@ -1168,7 +1156,7 @@ in the *same paragraph*. Here's a line for us to start with. -This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*. +This longer line is separated from the one above by two newlines, so it is a *separate paragraph*. This line is also a separate paragraph, but... These lines are only separated by single newlines, @@ -1183,7 +1171,7 @@ 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). If you need more control over line breaks or soft returns, you can add a single line break -by ending a line with a backslash, or two or more spaces. Two newlines in a row will create a new +by ending a line with a backslash, or two or more spaces. Two newlines in a row create a new paragraph, with a blank line in between: ```markdown @@ -1255,11 +1243,11 @@ NOTE: **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 in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` -will point the link to `wikis/style` only when the link is inside of a wiki Markdown file. +points the link to `wikis/style` only when the link is inside of a wiki Markdown file. #### URL auto-linking -GFM will auto-link almost any URL you put into your text: +GFM auto-links almost any URL you put into your text: ```markdown - https://www.google.com @@ -1283,9 +1271,9 @@ Ordered and unordered lists can be created. 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 will be +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 will use that as the first +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. Examples: @@ -1379,7 +1367,7 @@ Example: --- If the paragraph of the first item is not indented with the proper number of spaces, -the paragraph will appear outside the list, instead of properly indented under the list item. +the paragraph appears outside the list, instead of properly indented under the list item. Example: @@ -1429,18 +1417,18 @@ Example: | header 1 | header 2 | header 3 | | --- | ------ |---------:| | cell 1 | cell 2 | cell 3 | -| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. | +| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell <br> 9 | ``` | header 1 | header 2 | header 3 | | --- | ------ |---------:| | cell 1 | cell 2 | cell 3 | -| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's okay. It will eventually wrap the text when the cell is too large for the display size. | +| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's okay. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell <br> 9 | Additionally, you can choose the alignment of text within columns by adding colons (`:`) -to the sides of the "dash" lines in the second row. This will affect every cell in the column. +to the sides of the "dash" lines in the second row. This affects every cell in the column. NOTE: **Note:** [Within GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables), @@ -1463,8 +1451,8 @@ the headers are always left-aligned in Chrome and Firefox, and centered in Safar [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. If you're working in spreadsheet software (for example, Microsoft Excel, Google -Sheets, or Apple Numbers), you can copy from a spreadsheet, and GitLab will -paste it as a Markdown table. For example, suppose you have the +Sheets, or Apple Numbers), you can copy from a spreadsheet, and GitLab +pastes it as a Markdown table. For example, suppose you have the following spreadsheet:  diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 542efba1fae..9b1f23f6d59 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab Composer Repository **(PREMIUM)** +# GitLab Composer Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab Composer Repository, every project can have its own space to store [Composer](https://getcomposer.org/) packages. @@ -14,9 +15,9 @@ With the GitLab Composer Repository, every project can have its own space to sto NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** +[enabled support for the Package Registry](../../../administration/packages/index.md). -After the Composer Repository is enabled, it will be available for all new projects +When the Composer Repository is enabled, it is available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -27,10 +28,10 @@ You should then be able to see the **Packages & Registries** section on the left ## Getting started -This section will cover creating a new example Composer package to publish. This is a +This section covers creating a new example Composer package to publish. This is a quickstart to test out the **GitLab Composer Registry**. -You will need a recent version of [Composer](https://getcomposer.org/). +To complete this section, you need a recent version of [Composer](https://getcomposer.org/). ### Creating a package project @@ -68,19 +69,21 @@ git init git add composer.json git commit -m 'Composer package test' git tag v1.0.0 -git add origin git@gitlab.com:<namespace>/<project-name>.git +git remote add origin git@gitlab.com:<namespace>/<project-name>.git +git push --set-upstream origin master git push origin v1.0.0 ``` ### Publishing the package Now that the basics of our project is completed, we can publish the package. -For accomplishing this you will need the following: +To publish the package, you need: - A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. - Your project ID which can be found on the home page of your project. -To publish the package hosted on GitLab we'll need to make a `POST` to the GitLab package API using a tool like `curl`: +To publish the package hosted on GitLab, make a `POST` request to the GitLab package API. +A tool like `curl` can be used to make this request: ```shell curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer' @@ -96,7 +99,7 @@ If the above command succeeds, you now should be able to see the package under t ### Installing a package -To install your package you will need: +To install your package, you need: - A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. - Your group ID which can be found on the home page of your project's group. @@ -123,7 +126,7 @@ Where: - `<package_name>` is your package name as defined in your package's `composer.json` file. - `<version>` is your package version (`1.0.0` in this example). -You will also need to create a `auth.json` file with your GitLab credentials: +You also need to create a `auth.json` file with your GitLab credentials: ```json { diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 41b420ce7f6..e8014ad2b84 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab Conan Repository **(PREMIUM)** +# GitLab Conan Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab Conan Repository, every project can have its own space to store Conan packages. @@ -17,9 +18,9 @@ project can have its own space to store Conan packages. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Conan Repository](../../../administration/packages/index.md).**(PREMIUM ONLY)** +[enabled support for the Conan Repository](../../../administration/packages/index.md). -After the Conan Repository is enabled, it will be available for all new projects +After the Conan Repository is enabled, it's available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -30,7 +31,7 @@ You should then be able to see the **Packages & Registries** section on the left ## Getting started -This section will cover installing Conan and building a package for your C/C++ project. This is a quickstart if you are new +This section covers installing Conan and building a package for your C/C++ project. This is a quickstart if you're new to Conan. If you already are using Conan and understand how to build your own packages, move on to the [next section](#adding-the-gitlab-package-registry-as-a-conan-remote). ### Installing Conan @@ -65,10 +66,10 @@ instructions at [cmake.org](https://cmake.org/install/) for your operating syste ### Creating a project -Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you are new to C++ and want to try out the GitLab +Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you're new to C++ and want to try out the GitLab package registry, Conan.io has a great [hello world starter project](https://github.com/conan-io/hello) that you can clone to get started. -Clone the repo and it can be used for the rest of the tutorial if you don't have your own C++ project. +Clone the repository and it can be used for the rest of the tutorial if you don't have your own C++ project. ### Building a package @@ -79,7 +80,7 @@ package name and version: conan new Hello/0.1 -t ``` -Next, you will create a package for that recipe by running `conan create` providing the Conan user and channel: +Next, create a package for that recipe by running `conan create` providing the Conan user and channel: ```shell conan create . my-org+my-group+my-project/beta @@ -90,11 +91,11 @@ Current [naming restrictions](#package-recipe-naming-convention) require you to The example above would create a package belonging to this project: `https://gitlab.com/my-org/my-group/my-project` with a channel of `beta`. -These two example commands will generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`. +These two example commands generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`. For more advanced details on creating and managing your packages, refer to the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html). -You are now ready to upload your package to the GitLab registry. To get started, first you will need to set GitLab as a remote, then you will need to add a Conan user for that remote to authenticate your requests. +You are now ready to upload your package to the GitLab registry. To get started, first you need to set GitLab as a remote. Then you need to add a Conan user for that remote to authenticate your requests. ## Adding the GitLab Package Registry as a Conan remote @@ -114,7 +115,7 @@ conan search Hello* --all --remote=gitlab ## Authenticating to the GitLab Conan Repository -You will need a personal access token or deploy token. +You need a personal access token or deploy token. For repository authentication: @@ -123,7 +124,7 @@ For repository authentication: ### Adding a Conan user to the GitLab remote -Once you have a personal access token and have [set your Conan remote](#adding-the-gitlab-package-registry-as-a-conan-remote), you can associate the token with the remote so you do not have to explicitly add them to each Conan command you run: +Once you have a personal access token and have [set your Conan remote](#adding-the-gitlab-package-registry-as-a-conan-remote), you can associate the token with the remote so you don't have to explicitly add them to each Conan command you run: ```shell conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token> @@ -132,10 +133,10 @@ conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_acc NOTE: **Note:** If you named your remote something other than `gitlab`, your remote name should be used in this command instead of `gitlab`. -From now on, when you run commands using `--remote=gitlab`, your username and password will automatically be included in the requests. +From now on, when you run commands using `--remote=gitlab`, your username and password is automatically included in the requests. NOTE: **Note:** -The personal access token is not stored locally at any moment. Conan uses JWT, so when you run this command, Conan will request an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you will need to re-enter your personal access token when that happens. +The personal access token is not stored locally at any moment. Conan uses JSON Web Tokens (JWT), so when you run this command, Conan requests an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you need to re-enter your personal access token when that happens. Alternatively, you could explicitly include your credentials in any given command. For example: @@ -156,7 +157,7 @@ NOTE: **Note:** The package recipe does include the version, so setting the default remote for `Hello/0.1@user/channel` will not work for `Hello/0.2@user/channel`. This functionality is best suited for when you want to consume or install packages from the GitLab registry without having to specify a remote. -The rest of the example commands in this documentation assume that you have added a Conan user with your credentials to the `gitlab` remote and will not include the explicit credentials or remote option, but be aware that any of the commands could be run without having added a user or default remote: +The rest of the example commands in this documentation assume that you've added a Conan user with your credentials to the `gitlab` remote and will not include the explicit credentials or remote option. With that said, be aware that any of the commands could be run without having added a user or default remote: ```shell `CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command> --remote=gitlab @@ -166,7 +167,7 @@ The rest of the example commands in this documentation assume that you have adde First you need to [create your Conan package locally](https://docs.conan.io/en/latest/creating_packages/getting_started.html). In order to work with the GitLab Package Registry, a specific [naming convention](#package-recipe-naming-convention) must be followed. -Ensure you have a project created on GitLab and that the personal access token you are using has the correct permissions for write access to the container registry by selecting the `api` [scope](../../../user/profile/personal_access_tokens.md#limiting-scopes-of-a-personal-access-token). +Ensure you have a project created on GitLab and that the personal access token you're using has the correct permissions for write access to the container registry by selecting the `api` [scope](../../../user/profile/personal_access_tokens.md#limiting-scopes-of-a-personal-access-token). You can upload your package to the GitLab Package Registry using the `conan upload` command: @@ -180,7 +181,7 @@ Standard Conan recipe convention looks like `package_name/version@user/channel`. **The recipe user must be the `+` separated project path**. The package name may be anything, but it is preferred that the project name be used unless -it is not possible due to a naming collision. For example: +it's not possible due to a naming collision. For example: | Project | Package | Supported | | ---------------------------------- | ----------------------------------------------- | --------- | @@ -190,7 +191,7 @@ it is not possible due to a naming collision. For example: | `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No | NOTE: **Note:** -A future iteration will extend support to [project and group level](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) remotes which will allow for more flexible naming conventions. +A future iteration will extend support to [project and group level](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) remotes which allows for more flexible naming conventions. ## Installing a package @@ -222,7 +223,7 @@ conan install .. ``` NOTE: **Note:** -If you are trying to install the package you just created in this tutorial, not much will happen since that package +If you're trying to install the package you just created in this tutorial, not much will happen since that package already exists on your local machine. ## Removing a package @@ -235,11 +236,11 @@ There are two ways to remove a Conan package from the GitLab Package Registry. conan remove Hello/0.2@user/channel --remote=gitlab ``` - You need to explicitly include the remote in this command, otherwise the package will only be removed from your + You need to explicitly include the remote in this command, otherwise the package is only removed from your local system cache. NOTE: **Note:** - This command will remove all recipe and binary package files from the Package Registry. + This command removes all recipe and binary package files from the Package Registry. - **GitLab project interface**: in the packages view of your project page, you can delete packages by clicking the red trash icons. @@ -247,7 +248,7 @@ There are two ways to remove a Conan package from the GitLab Package Registry. The `conan search` command can be run searching by full or partial package name, or by exact recipe. -To search using a partial name, use the wildcard symbol `*`, which should be placed at the end of your search (e.g., `my-packa*`): +To search using a partial name, use the wildcard symbol `*`, which should be placed at the end of your search (for example, `my-packa*`): ```shell conan search Hello --all --remote=gitlab @@ -255,11 +256,11 @@ conan search He* --all --remote=gitlab conan search Hello/0.1@my-group+my-project/beta --all --remote=gitlab ``` -The scope of your search will include all projects you have permission to access, this includes your private projects as well as all public projects. +The scope of your search includes all projects you have permission to access, this includes your private projects as well as all public projects. ## Fetching Conan package information from the GitLab Package Registry -The `conan info` command will return information about a given package: +The `conan info` command returns information about a given package: ```shell conan info Hello/0.1@my-group+my-project/beta @@ -282,8 +283,8 @@ The GitLab Conan repository supports the following Conan CLI commands: To work with Conan commands within [GitLab CI/CD](./../../../ci/README.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. -It is easiest to provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each -Conan command in your `.gitlab-ci.yml` file: +It's easiest to provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each +Conan command in your `.gitlab-ci.yml` file. For example: ```yaml image: conanio/gcc7 @@ -292,8 +293,10 @@ create_package: stage: deploy script: - conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan - - conan create . my-group+my-project/beta - - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload Hello/0.1@root+ci-conan/beta1 --all --remote=gitlab + - conan new <package-name>/0.1 -t + - conan create . <group-name>+<project-name>/stable + - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab + ``` You can find additional Conan images to use as the base of your CI file diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 429d29b7677..f46ad99e573 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -49,7 +49,7 @@ project: 1. Expand the **Visibility, project features, permissions** section and enable the **Container Registry** feature on your project. For new projects this might be enabled by default. For existing projects - (prior GitLab 8.8), you will have to explicitly enable it. + (prior GitLab 8.8), enable it explicitly. 1. Press **Save changes** for the changes to take effect. You should now be able to see the **Packages & Registries > Container Registry** link in the sidebar. @@ -64,14 +64,14 @@ Navigate to your project's **{package}** **Packages & Registries > Container Reg  -This view will: +This view allows you to: - Show all the image repositories that belong to the project. -- Allow you to filter image repositories by their name. -- Allow you to [delete](#delete-images-from-within-gitlab) one or more image repository. -- Allow you to navigate to the image repository details page. +- Filter image repositories by their name. +- [Delete](#delete-images-from-within-gitlab) one or more image repository. +- Navigate to the image repository details page. - Show a **Quick start** dropdown with the most common commands to log in, build and push -- Optionally, a banner will be visible if the [cleanup policy](#cleanup-policy) is enabled for this project. +- Show a banner if the optional [cleanup policy](#cleanup-policy) is enabled for this project. ### Control Container Registry for your group @@ -79,15 +79,15 @@ Navigate to your groups's **{package}** **Packages & Registries > Container Regi  -This view will: +This view allows you to: - Show all the image repositories of the projects that belong to this group. -- Allow to [delete](#delete-images-from-within-gitlab) one or more image repositories. -- Allow to navigate to a specific image repository details page. +- [Delete](#delete-images-from-within-gitlab) one or more image repositories. +- Navigate to a specific image repository details page. ### Image Repository details page -Clicking on the name of any image repository will navigate to the details. +Clicking on the name of any image repository navigates to the details.  @@ -133,8 +133,10 @@ enabled in your account, you need to pass a [personal access token](../../profile/personal_access_tokens.md) instead of your password in order to login to GitLab's Container Registry. -If a project is private, credentials will need to be provided for authorization. -There are two ways to do this: +Credentials must be provided for authorization to any non-public registry. Only project members can access private, +GitLab-hosted registries. + +There are two ways to authenticate: - By using a [personal access token](../../profile/personal_access_tokens.md). - By using a [deploy token](../../project/deploy_tokens/index.md). @@ -158,7 +160,7 @@ docker build -t registry.example.com/group/project/image . docker push registry.example.com/group/project/image ``` -Your image will be named after the following scheme: +Your image is named after the following scheme: ```plaintext <registry URL>/<namespace>/<project>/<image> @@ -175,8 +177,8 @@ registry.example.com/group/project/my/image:rc1 ## Build and push images using GitLab CI/CD -While you can build and push your images from your local machine, the true -power of the Container Registry comes when you combine it with GitLab CI/CD. +While you can build and push your images from your local machine, take +full advantage of the Container Registry by combining it with GitLab CI/CD. You can then create workflows and automate any processes that involve testing, building, and eventually deploying your project from the Docker image you created. @@ -192,7 +194,7 @@ Before diving into the details, some things you should be aware of: - Doing an explicit `docker pull` before each `docker run` fetches the latest image that was just built. This is especially important if you are using multiple Runners that cache images locally. Using the Git SHA in your - image tag makes this less necessary since each job will be unique and you + image tag makes this less necessary since each job is unique and you shouldn't ever have a stale image. However, it's still possible to have a stale image if you re-build a given commit after a dependency has changed. - You don't want to build directly to `latest` tag in case there are multiple jobs @@ -201,10 +203,7 @@ Before diving into the details, some things you should be aware of: ### Authenticating to the Container Registry with GitLab CI/CD There are three ways to authenticate to the Container Registry via -[GitLab CI/CD](../../../ci/yaml/README.md) which depend on the visibility of -your project. - -Available for all projects, though more suitable for public ones: +[GitLab CI/CD](../../../ci/yaml/README.md): - **Using the special `CI_REGISTRY_USER` variable**: The user specified by this variable is created for you in order to push to the Registry connected to your project. Its password is automatically @@ -216,14 +215,22 @@ Available for all projects, though more suitable for public ones: docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY ``` -For private and internal projects: +- **Using the GitLab Deploy Token**: You can create and use a + [special deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) + with your projects. + Once created, you can use the special environment variables, and GitLab CI/CD + fills them in for you. You can use the following example as-is: + + ```shell + docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + ``` - **Using a personal access token**: You can create and use a [personal access token](../../profile/personal_access_tokens.md) in case your project is private: - For read (pull) access, the scope should be `read_registry`. - - For read/write (pull/push) access, use `api`. + - For write (push) access, the scope should be `write_registry`. Replace the `<username>` and `<access_token>` in the following example: @@ -231,16 +238,6 @@ For private and internal projects: docker login -u <username> -p <access_token> $CI_REGISTRY ``` -- **Using the GitLab Deploy Token**: You can create and use a - [special deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) - with your private projects. It provides read-only (pull) access to the Registry. - Once created, you can use the special environment variables, and GitLab CI/CD - will fill them in for you. You can use the following example as-is: - - ```shell - docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY - ``` - ### Container Registry examples with GitLab CI/CD If you're using Docker-in-Docker on your Runners, this is how your `.gitlab-ci.yml` @@ -276,7 +273,7 @@ build: Here, `$CI_REGISTRY_IMAGE` would be resolved to the address of the registry tied to this project. Since `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, -and your branch-name can contain forward slashes (e.g., feature/my-feature), it is +and your branch name can contain forward slashes (for example, `feature/my-feature`), it is safer to use `$CI_COMMIT_REF_SLUG` as the image tag. This is due to that image tags cannot contain forward slashes. We also declare our own variable, `$IMAGE_TAG`, combining the two to save us some typing in the `script` section. @@ -352,8 +349,8 @@ is set to `always`. ### Using a Docker-in-Docker image from your Container Registry -If you want to use your own Docker images for Docker-in-Docker, there are a few -things you need to do in addition to the steps in the +To use your own Docker images for Docker-in-Docker, follow these steps +in addition to the steps in the [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) section: 1. Update the `image` and `service` to point to your registry. @@ -373,8 +370,8 @@ Below is an example of what your `.gitlab-ci.yml` should look like: - docker run my-docker-image /script/to/run/tests ``` -If you forget to set the service alias, the `docker:19.03.12` image won't find the -`dind` service, and an error like the following will be thrown: +If you forget to set the service alias, the `docker:19.03.12` image is unable to find the +`dind` service, and an error like the following is thrown: ```plaintext error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host @@ -496,81 +493,71 @@ Container Registry. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. -For a specific project, if you want to remove tags you no longer need, -you can create a cleanup policy. When the policy is applied, tags matching the regex pattern are removed. +The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. +For the project where it's defined, tags matching the regex pattern are removed. The underlying layers and images remain. -To delete the underlying layers and images no longer associated with any tags, Instance Administrators can use +To delete the underlying layers and images that aren't associated with any tags, administrators can use [garbage collection](../../../administration/packages/container_registry.md#removing-unused-layers-not-referenced-by-manifests) with the `-m` switch. -NOTE: **Note:** -For GitLab.com, cleanup policies are not available for projects created -before this feature was deployed to production (February 2020). -Support for pre-existing projects on GitLab.com -[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). -For self-managed instances, cleanup policies may be enabled by an admin in the -[GitLab application settings](../../../api/settings.md#change-application-settings) by setting `container_expiration_policies_enable_historic_entries` to true. -Note the inherent [risks involved](./index.md#use-with-external-container-registries). - -The cleanup policy algorithm starts by collecting all the tags for a given repository in a list, -then goes through a process of excluding tags from it until only the ones to be deleted remain: - -1. Collect all the tags for a given repository in a list. -1. Excludes the tag named `latest` from the list. -1. Evaluates the `name_regex`, excluding non-matching names from the list. -1. Excludes any tags that do not have a manifest (not part of the options). -1. Orders the remaining tags by `created_date`. -1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). -1. Excludes from the list the tags more recent than the `older_than` value (Cleanup interval). -1. Excludes from the list any tags matching the `name_regex_keep` value (Images to preserve). -1. Finally, the remaining tags in the list are deleted from the Container Registry. +### Enable the cleanup policy -### Managing project cleanup policy through the UI +Cleanup policies can be run on all projects, with these exceptions: -To manage project cleanup policy, navigate to **{settings}** **Settings > CI/CD > Container Registry tag cleanup policy**. +- For GitLab.com, the project must have been created after 2020-02-22. + Support for projects created earlier + [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). +- For self-managed GitLab instances, the project must have been created + in GitLab 12.8 or later. However, an administrator can enable the cleanup policy + for all projects (even those created before 12.8) in + [GitLab application settings](../../../api/settings.md#change-application-settings) + by setting `container_expiration_policies_enable_historic_entries` to true. -The UI allows you to configure the following: + There are performance risks with enabling it for all projects, especially if you + are using an [external registry](./index.md#use-with-external-container-registries). -- **Cleanup policy:** enable or disable the cleanup policy. -- **Cleanup interval:** how long tags are exempt from being deleted. -- **Cleanup schedule:** how often the cron job checking the tags should run. -- **Number of tags to retain:** how many tags to _always_ keep for each image. -- **Docker tags with names matching this regex pattern will expire:** the regex used to determine what tags should be cleaned up. To qualify all tags for cleanup, use the default value of `.*`. -- **Docker tags with names matching this regex pattern will be preserved:** the regex used to determine what tags should be preserved. To preserve all tags, use the default value of `.*`. +### How the cleanup policy works -#### Troubleshooting cleanup policies +The cleanup policy collects all tags in the Container Registry and excludes tags +until only the tags to be deleted remain. -If you see the following message: - -"Something went wrong while updating the cleanup policy." - -Check the regex patterns to ensure they are valid. +The cleanup policy: -You can use [Rubular](https://rubular.com/) to check your regex. -View some common [regex pattern examples](#regex-pattern-examples). +1. Collects all tags for a given repository in a list. +1. Excludes the tag named `latest` from the list. +1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list. +1. Excludes any tags that do not have a manifest (not part of the options in the UI). +1. Orders the remaining tags by `created_date`. +1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). +1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval). +1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). +1. Finally, the remaining tags in the list are deleted from the Container Registry. -### Managing project cleanup policy through the API +### Create a cleanup policy -You can set, update, and disable the cleanup policies using the GitLab API. +You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. -Examples: +To create a cleanup policy in the UI: -- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: +1. For your project, go to **Settings > CI/CD**. +1. Expand the **Cleanup policy for tags** section. +1. Complete the fields. - ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2' - ``` + | Field | Description | + |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| + | **Cleanup policy** | Turn the policy on or off. | + | **Expiration interval** | How long tags are exempt from being deleted. | + | **Expiration schedule** | How often the policy should run. | + | **Number of tags to retain** | How many tags to _always_ keep for each image. | + | **Tags with names matching this regex pattern expire:** | The regex pattern that determines which tags to remove. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Tags with names matching this regex pattern are preserved:** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | -See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). +1. Click **Set cleanup policy**. -### Use with external container registries +Depending on the interval you chose, the policy is scheduled to run. -When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), -running a cleanup policy on a project may have some performance risks. If a project is going to run -a policy that will remove large quantities of tags (in the thousands), the GitLab background jobs that -run the policy may get backed up or fail completely. It is recommended you only enable container cleanup -policies for projects that were created before GitLab 12.8 if you are confident the amount of tags -being cleaned up will be minimal. +NOTE: **Note:** +If you edit the policy and click **Set cleanup policy** again, the interval is reset. ### Regex pattern examples @@ -602,6 +589,41 @@ Here are examples of regex patterns you may want to use: (?:v.+|master|release) ``` +### Use the cleanup policy API + +You can set, update, and disable the cleanup policies using the GitLab API. + +Examples: + +- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: + + ```shell + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2' + ``` + +See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). + +### Use with external container registries + +When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), +running a cleanup policy on a project may have some performance risks. +If a project runs a policy to remove thousands of tags +the GitLab background jobs may get backed up or fail completely. +It is recommended you only enable container cleanup +policies for projects that were created before GitLab 12.8 if you are confident the number of tags +being cleaned up is minimal. + +### Troubleshooting cleanup policies + +If you see the following message: + +"Something went wrong while updating the cleanup policy." + +Check the regex patterns to ensure they are valid. + +You can use [Rubular](https://rubular.com/) to check your regex. +View some common [regex pattern examples](#regex-pattern-examples). + ## Use the Container Registry to store Helm Charts With the launch of [Helm v3](https://helm.sh/docs/topics/registries/), @@ -616,9 +638,9 @@ You can read more about the above challenges [here](https://gitlab.com/gitlab-or - Moving or renaming existing Container Registry repositories is not supported once you have pushed images, because the images are signed, and the signature includes the repository name. To move or rename a repository with a -Container Registry, you will have to delete all existing images. +Container Registry, you must delete all existing images. - Prior to GitLab 12.10, any tags that use the same image ID as the `latest` tag -will not be deleted by the cleanup policy. +are not deleted by the cleanup policy. ## Troubleshooting the GitLab Container Registry @@ -637,7 +659,7 @@ name. ### Troubleshoot as a GitLab server admin Troubleshooting the GitLab Container Registry, most of the times, requires -administration access to the GitLab server. +administrator access to the GitLab server. [Read how to troubleshoot the Container Registry](../../../administration/packages/container_registry.md#troubleshooting). @@ -655,22 +677,22 @@ the project. The following procedure uses these sample project names: -- For the current project: `example.gitlab.com/org/build/sample_project/cr:v2.9.1` -- For the new project: `example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1` +- For the current project: `gitlab.example.com/org/build/sample_project/cr:v2.9.1` +- For the new project: `gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1` Use your own URLs to complete the following steps: 1. Download the Docker images on your computer: ```shell - docker login example.gitlab.com - docker pull example.gitlab.com/org/build/sample_project/cr:v2.9.1 + docker login gitlab.example.com + docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1 ``` 1. Rename the images to match the new project name: ```shell - docker tag example.gitlab.com/org/build/sample_project/cr:v2.9.1 example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1 + docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1 ``` 1. Delete the images in both projects by using the [UI](#delete-images) or [API](../../../api/packages.md#delete-a-project-package). @@ -680,7 +702,7 @@ Use your own URLs to complete the following steps: 1. Restore the images: ```shell - docker push example.gitlab.com/new_org/build/new_sample_project/cr:v2.9.1 + docker push gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1 ``` Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/18383) for details. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index e68883a1382..e3ee8909165 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,9 +4,9 @@ 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/#designated-technical-writers --- -# Dependency Proxy **(PREMIUM ONLY)** +# Dependency Proxy **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. NOTE: **Note:** This is the user guide. In order to use the dependency proxy, an administrator @@ -63,10 +63,10 @@ To get a Docker image into the dependency proxy: image: gitlab.com/groupname/dependency_proxy/containers/alpine:latest ``` -GitLab will then pull the Docker image from Docker Hub and will cache the blobs -on the GitLab server. The next time you pull the same image, it will get the latest -information about the image from Docker Hub but will serve the existing blobs -from GitLab. +GitLab pulls the Docker image from Docker Hub and caches the blobs +on the GitLab server. The next time you pull the same image, GitLab gets the latest +information about the image from Docker Hub but serves the existing blobs +from the GitLab server. The blobs are kept forever, and there is no hard limit on how much data can be stored. @@ -82,6 +82,6 @@ for more details. The following limitations apply: -- Only public groups are supported (authentication is not supported yet). +- Only [public groups are supported](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) (authentication is not supported yet). - Only Docker Hub is supported. - This feature requires Docker Hub being available. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index a705b956d30..edf1528a751 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,13 +4,14 @@ 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/#designated-technical-writers --- -# GitLab Go Proxy **(PREMIUM)** +# GitLab Go Proxy > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. > - It's deployed behind a feature flag, disabled by default. > - It's disabled on GitLab.com. > - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). **(PREMIUM)** +> - 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 Core in 13.3. With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). @@ -53,7 +54,7 @@ the **{package}** **Packages > List** entry under your project's sidebar, verify the following: 1. Your GitLab administrator has - [enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** + [enabled support for the Package Registry](../../../administration/packages/index.md). 1. The Package Registry is [enabled for your project](../index.md). NOTE: **Note:** diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index ab9cdc204f8..92d31c31986 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -4,106 +4,37 @@ 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/#designated-technical-writers --- -# GitLab Package Registry +# Packages & Registries -With the GitLab Package Registry, you can use GitLab as a private or public repository -for a variety of common package managers. You can build and publish +The GitLab [Package Registry](package_registry/index.md) acts as a private or public registry +for a variety of common package managers. You can publish and share packages, which can be easily consumed as a dependency in downstream projects. -GitLab acts as a repository for the following: - -| Software repository | Description | Available in GitLab version | -| ------------------- | ----------- | --------------------------- | -| [Container Registry](container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | 8.8+ | -| [Dependency Proxy](dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | 11.11+ | -| [Conan Repository](conan_repository/index.md) **(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.6+ | -| [Maven Repository](maven_repository/index.md) **(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ | -| [NPM Registry](npm_registry/index.md) **(PREMIUM)** | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ | -| [NuGet Repository](nuget_repository/index.md) **(PREMIUM)** | The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ | -| [PyPi Repository](pypi_repository/index.md) **(PREMIUM)** | The GitLab PyPi Repository will enable every project in GitLab to have its own space to store [PyPi](https://pypi.org/) packages. | 12.10+ | -| [Go Proxy](go_proxy/index.md) **(PREMIUM)** | The Go proxy for GitLab enables every project in GitLab to be fetched with the [Go proxy protocol](https://proxy.golang.org/). | 13.1+ | -| [Composer Repository](composer_repository/index.md) **(PREMIUM)** | The GitLab Composer Repository will enable every project in GitLab to have its own space to store [Composer](https://getcomposer.org/) packages. | 13.2+ | - -## View packages - -You can view packages for your project or group. - -1. Go to the project or group. -1. Go to **{package}** **Packages & Registries > Package Registry**. - -You can search, sort, and filter packages on this page. - -For information on how to create and upload a package, view the GitLab documentation for your package type. - -## Use GitLab CI/CD to build packages - -You can use [GitLab CI/CD](./../../ci/README.md) to build packages. -For Maven and NPM packages, and Composer dependencies, you can -authenticate with GitLab by using the `CI_JOB_TOKEN`. - -CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). - -Learn more about [using CI/CD to build Maven packages](maven_repository/index.md#creating-maven-packages-with-gitlab-cicd) -and [NPM packages](npm_registry/index.md#publishing-a-package-with-cicd). - -If you use CI/CD to build a package, extended activity -information is displayed when you view the package details: - - - -You can view which pipeline published the package, as well as the commit and -user who triggered it. - -## Download a package - -To download a package: - -1. Go to **{package}** **Packages & Registries > Package Registry**. -1. Click the name of the package you want to download. -1. In the **Activity** section, click the name of the package you want to download. - -## Delete a package - -You cannot edit a package after you publish it in the Package Registry. Instead, you -must delete and recreate it. - -- You cannot delete packages from the group view. You must delete them from the project view instead. - See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/227714) for details. -- You must have suitable [permissions](../permissions.md). - -You can delete packages by using [the API](../../api/packages.md#delete-a-project-package) or the UI. - -To delete a package in the UI: - -1. Go to **{package}** **Packages & Registries > Package Registry**. -1. Find the name of the package you want to delete. -1. Click **Delete**. - -The package is permanently deleted. - -## Disable the Package Registry - -The Package Registry is automatically enabled. - -If you are using a self-managed instance of GitLab, your administrator can remove -the menu item, **{package}** **Packages & Registries**, from the GitLab sidebar. For more information, -see the [administration documentation](../../administration/packages/index.md). - -You can also remove the Package Registry for your project specifically: - -1. In your project, go to **{settings}** **Settings > General**. -1. Expand the **Visibility, project features, permissions** section and disable the - **Packages** feature. -1. Click **Save changes**. - -The **{package}** **Packages & Registries > Package Registry** entry is removed from the sidebar. - -## Package workflows - -Learn how to use the GitLab Package Registry to build your own custom package workflow. - -- [Use a project as a package registry](./workflows/project_registry.md) to publish all of your packages to one project. -- Publish multiple different packages from one [monorepo project](./workflows/monorepo.md). +The Package Registry supports the following formats: + +<div class="row"> +<div class="col-md-9"> +<table align="left" style="width:50%"> +<tr style="background:#dfdfdf"><th>Package type</th><th>GitLab version</th></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/composer_repository/index.html">Composer</a></td><td>13.2+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">NPM</a></td><td>11.7+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> +</table> +</div> +</div> + +You can also use the [API](../../api/packages.md) to administer the Package 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. + +The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. ## Suggested contributions diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index b194b7d837a..f98a8eb9c6d 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab Maven Repository **(PREMIUM)** +# GitLab Maven Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab [Maven](https://maven.apache.org) Repository, every project can have its own space to store its Maven artifacts. @@ -17,7 +18,7 @@ project can have its own space to store its Maven artifacts. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Maven repository](../../../administration/packages/index.md).**(PREMIUM ONLY)** +[enabled support for the Maven repository](../../../administration/packages/index.md). After the Packages feature is enabled, the Maven Repository will be available for all new projects by default. To enable it for existing projects, or if you want @@ -321,7 +322,7 @@ repositories { name "GitLab" credentials(HttpHeaderCredentials) { name = 'Job-Token' - value = '${CI_JOB_TOKEN}' + value = System.getenv("CI_JOB_TOKEN") } authentication { header(HttpHeaderAuthentication) @@ -689,7 +690,7 @@ downloaded from the GitLab Package Registry: Downloading from gitlab-maven: http://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom ``` -#### Install with `mvn dependency:get` +### Install using Maven with `mvn dependency:get` The second way to install packages is to use the Maven commands directly. Inside your project directory, run: @@ -782,7 +783,7 @@ is updated: ```yaml deploy: - image: maven:3.3.9-jdk-8 + image: maven:3.6-jdk-11 script: - 'mvn deploy -s ci_settings.xml' only: @@ -807,7 +808,7 @@ is updated: ```yaml deploy: - image: gradle:latest + image: gradle:6.5-jdk11 script: - 'gradle publish' only: @@ -816,11 +817,6 @@ is updated: 1. Push those files to your repository. -The next time the `deploy` job runs, it will copy `ci_settings.xml` to the -user's home location (in this case the user is `root` since it runs in a -Docker container), and Maven will use the configured CI -[environment variables](../../../ci/variables/README.md#predefined-environment-variables). - ### Version validation The version string is validated using the following regex. @@ -833,10 +829,25 @@ You can play around with the regex and try your version strings on [this regular ## Troubleshooting -### Useful Maven command line options +### Review network trace logs + +If you are having issues with the Maven Repository, you may want to review network trace logs. + +For example, try to run `mvn deploy` locally with a PAT token and use these options: + +```shell +mvn deploy \ +-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient=trace \ +-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace +``` + +CAUTION: **Caution:** +When you set these options, all network requests are logged and a large amount of output is generated. + +### Useful Maven command-line options -There's some [maven command line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) -which maybe useful when doing tasks with GitLab CI/CD. +There are some [Maven command-line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) +that may be useful when performing tasks with GitLab CI/CD. - File transfer progress can make the CI logs hard to read. Option `-ntp,--no-transfer-progress` was added in diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 390b2c28e10..5b90ec6f18c 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab NPM Registry **(PREMIUM)** +# GitLab NPM Registry -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab NPM Registry, every project can have its own space to store NPM packages. @@ -20,9 +21,9 @@ Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the NPM registry](../../../administration/packages/index.md).**(PREMIUM ONLY)** +[enabled support for the NPM registry](../../../administration/packages/index.md). -After the NPM registry is enabled, it will be available for all new projects +Enabling the NPM registry makes it available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -36,7 +37,7 @@ get familiar with the package naming convention. ## Getting started -This section will cover installing NPM (or Yarn) and building a package for your +This section covers how to install NPM (or Yarn) and build a package for your JavaScript project. This is a quickstart if you are new to NPM packages. If you are already using NPM and understand how to build your own packages, move on to the [next section](#authenticating-to-the-gitlab-npm-registry). @@ -93,24 +94,24 @@ Or if you're using Yarn: yarn init ``` -This will take you through a series of questions to produce a `package.json` +This takes you through a series of questions to produce a `package.json` file, which is required for all NPM packages. The most important question is the package name. NPM packages must [follow the naming convention](#package-naming-convention) and be scoped to the project or group where the registry exists. Once you have completed the setup, you are now ready to upload your package to -the GitLab registry. To get started, you will need to set up authentication then +the GitLab registry. To get started, you need to set up authentication and then configure GitLab as a remote registry. ## Authenticating to the GitLab NPM Registry If a project is private or you want to upload an NPM package to GitLab, -credentials will need to be provided for authentication. [Personal access tokens](../../profile/personal_access_tokens.md) +you need to provide credentials for authentication. [Personal access tokens](../../profile/personal_access_tokens.md) and [deploy tokens](../../project/deploy_tokens/index.md) are preferred, but support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:** -If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens won't be able to authenticate to the GitLab NPM Registry. +If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. ### Authenticating with a personal access token or deploy token @@ -168,7 +169,7 @@ Then, you could run `npm publish` either locally or via GitLab CI/CD: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. 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 will inherit the permissions of the user that generates the pipeline. +The token inherits the permissions of the user that generates the pipeline. Add a corresponding section to your `.npmrc` file: @@ -180,7 +181,7 @@ Add a corresponding section to your `.npmrc` file: ## Uploading packages -Before you will be able to upload a package, you need to specify the registry +Before you can upload a package, you need to specify the registry for NPM. To do this, add the following section to the bottom of `package.json`: ```json @@ -205,8 +206,8 @@ npm publish You can then navigate to your project's **Packages & Registries** page and see the uploaded packages or even delete them. -If you attempt to publish a package with a name that already exists within -a given scope, you will receive a `403 Forbidden!` error. +Attempting to publish a package with a name that already exists within +a given scope causes a `403 Forbidden!` error. ## Uploading a package with the same version twice @@ -245,7 +246,7 @@ project path is `My-Group/project-foo`, your package must be named `@My-Group/an `@my-group/any-package-name` will not work. CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:** -If you update the root namespace of a project with NPM packages, your changes will be rejected. To be allowed to do that, make sure to remove any NPM package first. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. +Make sure to remove any NPM packages first. You cannot update the root namespace of a project with NPM packages. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. Now, you can configure your project to authenticate with the GitLab NPM Registry. @@ -253,16 +254,16 @@ Registry. ## Installing a package NPM packages are commonly installed using the `npm` or `yarn` commands -inside a JavaScript project. If you haven't already, you will need to set the +inside a JavaScript project. If you haven't already, set the URL for scoped packages. You can do this with the following command: ```shell npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ ``` -You will need to replace `@foo` with your scope. +Replace `@foo` with your scope. -Next, you will need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) +Next, you need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) is setup so you can successfully install the package. Once this has been completed, you can run the following command inside your project to install a package: @@ -281,7 +282,7 @@ yarn add @my-project-scope/my-package > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. -By default, when an NPM package is not found in the GitLab NPM Registry, the request will be forwarded to [npmjs.com](https://www.npmjs.com/). +By default, when an NPM package is not found in the GitLab NPM Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). @@ -367,7 +368,7 @@ And the `.npmrc` file should look like: ### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}` -You do not need a token to run `npm install` unless your project is private (the token is only required to publish). If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you'll need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): +You do not need a token to run `npm install` unless your project is private (the token is only required to publish). If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 4ee5e5c4627..9fb50ce71fb 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab NuGet Repository **(PREMIUM)** +# GitLab NuGet Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab NuGet Repository, every project can have its own space to store NuGet packages. @@ -18,7 +19,7 @@ The GitLab NuGet Repository works with: ## Setting up your development environment -You will need [NuGet CLI 5.2 or later](https://www.nuget.org/downloads). Earlier versions have not been tested +[NuGet CLI 5.2 or later](https://www.nuget.org/downloads) is required. Earlier versions have not been tested against the GitLab NuGet Repository and might not work. If you have [Visual Studio](https://visualstudio.microsoft.com/vs/), NuGet CLI is probably already installed. @@ -42,6 +43,9 @@ Available commands: [output truncated] ``` +NOTE: **Note:** +GitLab currently only supports NuGet v3. Earlier versions are not supported. + ### macOS support For macOS, you can also use [Mono](https://www.mono-project.com/) to run @@ -58,9 +62,9 @@ mono nuget.exe NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** +[enabled support for the Package Registry](../../../administration/packages/index.md). -After the NuGet Repository is enabled, it will be available for all new projects +When the NuGet Repository is enabled, it is available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -71,7 +75,7 @@ You should then be able to see the **Packages & Registries** section on the left ## Adding the GitLab NuGet Repository as a source to NuGet -You will need the following: +You need the following: - Your GitLab username. - A personal access token or deploy token. For repository authentication: @@ -108,7 +112,7 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example/api/v4/projects/ 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). 1. Open the **FILE > OPTIONS** (Windows) or **Visual Studio > Preferences** (Mac OS). -1. In the **NuGet** section, open **Sources**. You will see a list of all your NuGet sources. +1. In the **NuGet** section, open **Sources** to see a list of all your NuGet sources. 1. Click **Add**. 1. Fill the fields with: - **Name**: Desired name for the source @@ -152,8 +156,8 @@ When uploading packages, note that: - The maximum allowed size is 50 Megabytes. - If you upload the same package with the same version multiple times, each consecutive upload - is saved as a separate file. When installing a package, GitLab will serve the most recent file. -- When uploading packages to GitLab, they will not be displayed in the packages UI of your project + is saved as a separate file. When installing a package, GitLab serves the most recent file. +- When uploading packages to GitLab, they are not displayed in the packages UI of your project immediately. It can take up to 10 minutes to process a package. ### Upload packages with NuGet CLI @@ -197,7 +201,7 @@ dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab CAUTION: **Warning:** By default, `nuget` checks the official source at `nuget.org` first. If you have a package in the GitLab NuGet Repository with the same name as a package at `nuget.org`, you must specify the source -name or the wrong package will be installed. +name to install the correct package. Install the latest version of a package using the following command: @@ -210,7 +214,7 @@ nuget install <package_id> -OutputDirectory <output_directory> \ Where: - `<package_id>` is the package ID. -- `<output_directory>` is the output directory, where the package will be installed. +- `<output_directory>` is the output directory, where the package is installed. - `<package_version>` (Optional) is the package version. - `<source_name>` (Optional) is the source name. @@ -232,3 +236,35 @@ Where: - `<package_id>` is the package ID. - `<package_version>` (Optional) is the package version. + +## Publishing a NuGet package with CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. + +If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. +The token inherits the permissions of the user that generates the pipeline. + +This example shows how to create a new package each time the `master` branch +is updated: + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + image: mcr.microsoft.com/dotnet/core/sdk:3.1 + + stages: + - deploy + + deploy: + stage: deploy + script: + - dotnet restore -p:Configuration=Release + - dotnet build -c Release + - dotnet pack -c Release + - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text + - dotnet nuget push "bin/Release/*.nupkg" --source gitlab + only: + - master + ``` + +1. Commit the changes and push it to your GitLab repository to trigger a new CI build. diff --git a/doc/user/packages/img/package_activity_v12_10.png b/doc/user/packages/package_registry/img/package_activity_v12_10.png Binary files differindex 4fea9a7ca3f..4fea9a7ca3f 100644 --- a/doc/user/packages/img/package_activity_v12_10.png +++ b/doc/user/packages/package_registry/img/package_activity_v12_10.png diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md new file mode 100644 index 00000000000..fd250c9ac95 --- /dev/null +++ b/doc/user/packages/package_registry/index.md @@ -0,0 +1,93 @@ +--- +stage: Package +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/#designated-technical-writers +--- + +# Package Registry + +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core 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. + +## View packages + +You can view packages for your project or group. + +1. Go to the project or group. +1. Go to **{package}** **Packages & Registries > Package Registry**. + +You can search, sort, and filter packages on this page. + +For information on how to create and upload a package, view the GitLab documentation for your package type. + +## Use GitLab CI/CD to build packages + +You can use [GitLab CI/CD](../../../ci/README.md) to build packages. +For Maven, NuGet and NPM packages, and Composer dependencies, you can +authenticate with GitLab by using the `CI_JOB_TOKEN`. + +CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). + +Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd) and [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd). + +If you use CI/CD to build a package, extended activity +information is displayed when you view the package details: + + + +You can view which pipeline published the package, as well as the commit and +user who triggered it. + +## Download a package + +To download a package: + +1. Go to **{package}** **Packages & Registries > Package Registry**. +1. Click the name of the package you want to download. +1. In the **Activity** section, click the name of the package you want to download. + +## Delete a package + +You cannot edit a package after you publish it in the Package Registry. Instead, you +must delete and recreate it. + +- You cannot delete packages from the group view. You must delete them from the project view instead. + See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/227714) for details. +- You must have suitable [permissions](../../permissions.md). + +You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. + +To delete a package in the UI: + +1. Go to **{package}** **Packages & Registries > Package Registry**. +1. Find the name of the package you want to delete. +1. Click **Delete**. + +The package is permanently deleted. + +## Disable the Package Registry + +The Package Registry is automatically enabled. + +If you are using a self-managed instance of GitLab, your administrator can remove +the menu item, **{package}** **Packages & Registries**, from the GitLab sidebar. For more information, +see the [administration documentation](../../../administration/packages/index.md). + +You can also remove the Package Registry for your project specifically: + +1. In your project, go to **Settings > General**. +1. Expand the **Visibility, project features, permissions** section and disable the + **Packages** feature. +1. Click **Save changes**. + +The **{package}** **Packages & Registries > Package Registry** entry is removed from the sidebar. + +## Package workflows + +Learn how to use the GitLab Package Registry to build your own custom package workflow. + +- [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. +- Publish multiple different packages from one [monorepo project](../workflows/monorepo.md). diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 615741cc303..63e6cd7b5b4 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,9 +4,10 @@ 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/#designated-technical-writers --- -# GitLab PyPi Repository **(PREMIUM)** +# GitLab PyPi Repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. With the GitLab PyPi Repository, every project can have its own space to store PyPi packages. @@ -17,15 +18,15 @@ The GitLab PyPi Repository works with: ## Setting up your development environment -You will need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). +You need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). ## Enabling the PyPi Repository NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** +[enabled support for the Package Registry](../../../administration/packages/index.md). -After the PyPi Repository is enabled, it will be available for all new projects +After the PyPi Repository is enabled, it is available for all new projects by default. To enable it for existing projects, or if you want to disable it: 1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. @@ -36,7 +37,7 @@ You should then be able to see the **Packages & Registries** section on the left ## Getting started -This section will cover creating a new example PyPi package to upload. This is a +This section covers creating a new example PyPi package to upload. This is a quickstart to test out the **GitLab PyPi Registry**. If you already understand how to build and publish your own packages, move on to the [next section](#adding-the-gitlab-pypi-repository-as-a-source). @@ -158,7 +159,7 @@ Package Registry**. Before we do so, we next need to set up authentication. ### Authenticating with a personal access token -You will need the following: +You need the following: - A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. - A suitable name for your source. @@ -179,7 +180,7 @@ password = <your personal access token> ### Authenticating with a deploy token -You will need the following: +You need the following: - A deploy token. You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the `read_package_registry` and/or `write_package_registry` scopes for repository authentication. - A suitable name for your source. @@ -204,7 +205,7 @@ When uploading packages, note that: - The maximum allowed size is 50 Megabytes. - If you upload the same package with the same version multiple times, each consecutive upload - is saved as a separate file. When installing a package, GitLab will serve the most recent file. + is saved as a separate file. When installing a package, GitLab serves the most recent file. ### Upload packages with Twine @@ -228,8 +229,8 @@ Uploading mypypipackage-0.0.1.tar.gz This indicates that the package was uploaded successfully. You can then navigate to your project's **Packages & Registries** page and see the uploaded packages. -If you did not follow the guide above, the you'll need to ensure your package -has been properly built and you [created a PyPi package with setuptools](https://packaging.python.org/tutorials/packaging-projects/). +If you did not follow the guide above, then you need to ensure your package +has been properly built and you [created a PyPi package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). You can then upload your package using the following command: diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md index 5acd4fd0735..c87f181bf82 100644 --- a/doc/user/packages/workflows/monorepo.md +++ b/doc/user/packages/workflows/monorepo.md @@ -1,3 +1,9 @@ +--- +stage: Package +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/#designated-technical-writers +--- + # Monorepo package management workflows Oftentimes, one project or Git repository may contain multiple different @@ -76,44 +82,39 @@ Using the example project above, this `gitlab-ci.yml` file will publish and publish `MyPackage` anytime changes are made to anywhere _except_ the `Foo` directory on the `master` branch. -```shell +```yaml +image: node:latest + stages: - build -.default-rule: &default-rule - if: '$CI_MERGE_REQUEST_IID || $CI_COMMIT_REF_SLUG == "master"' - -.foo-package: +build-foo-package: + stage: build variables: PACKAGE: "Foo" - before_script: + script: - cd src/components/Foo + - echo "Building $PACKAGE" + - npm publish only: + refs: + - master + - merge_requests changes: - "src/components/Foo/**/*" -.parent-package: +build-my-project-package: + stage: build variables: PACKAGE: "MyPackage" - except: - changes: - - "src/components/Foo/**/*" - -.build-package: - stage: build script: - echo "Building $PACKAGE" - npm publish - rules: - - <<: *default-rule - -build-foo-package: - extends: - - .build-package - - .foo-package - -build-my-project-package: - extends: - - .build-package - - .parent-package + only: + refs: + - master + - merge_requests + except: + changes: + - "src/components/Foo/**/*" ``` diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index df330931ac5..a7bc4436d0e 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -1,3 +1,9 @@ +--- +stage: Package +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/#designated-technical-writers +--- + # Project as a package registry Using the features of the package registry, it is possible to use one project to store all of your packages. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index ba62cf81847..a89d534c782 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -8,15 +8,14 @@ Users have different abilities depending on the access level they have in a particular group or project. If a user is both in a project's group and the project itself, the highest permission level is used. -On public and internal projects the Guest role is not enforced. All users will -be able to: +On public and internal projects the Guest role is not enforced. All users can: - Create issues. - Leave comments. - Clone or download the project code. When a member leaves a team's project, all the assigned [Issues](project/issues/index.md) and [Merge Requests](project/merge_requests/index.md) -will be unassigned automatically. +are unassigned automatically. GitLab [administrators](../administration/index.md) receive all permissions. @@ -39,15 +38,15 @@ NOTE: **Note:** In GitLab 11.0, the Master role was renamed to Maintainer. While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, -or an instance admin, who receives all permissions. For more information, see [projects members documentation](project/members/index.md). +or an instance administrator, who receives all permissions. For more information, see [projects members documentation](project/members/index.md). The following table depicts the various user permission levels in a project. | Action | Guest | Reporter | Developer |Maintainer| Owner* | |---------------------------------------------------|---------|------------|-------------|----------|--------| | Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Leave comments | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +| View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | View Dependency list **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | @@ -61,9 +60,9 @@ The following table depicts the various user permission levels in a project. | See a list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | See a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| Create new issue | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| Create new issue | ✓ | ✓ | ✓ | ✓ | ✓ | | See related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create confidential issue | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | | View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | | View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | | View requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -85,8 +84,10 @@ The following table depicts the various user permission levels in a project. | Create new merge request | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Pull [packages](packages/index.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Publish [packages](packages/index.md) **(PREMIUM)**| | | ✓ | ✓ | ✓ | +| Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | +| Delete [packages](packages/index.md) | | | | ✓ | ✓ | +| Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | | Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | Create/edit/delete [Releases](project/releases/index.md)| | | ✓ | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | @@ -128,7 +129,7 @@ The following table depicts the various user permission levels in a project. | Push to protected branches | | | | ✓ | ✓ | | Turn on/off protected branch push for devs | | | | ✓ | ✓ | | Enable/disable tag protections | | | | ✓ | ✓ | -| Edit project | | | | ✓ | ✓ | +| Edit project settings | | | | ✓ | ✓ | | Edit project badges | | | | ✓ | ✓ | | Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*)| | Add deploy keys to project | | | | ✓ | ✓ | @@ -141,7 +142,7 @@ The following table depicts the various user permission levels in a project. | Remove GitLab Pages | | | | ✓ | ✓ | | Manage clusters | | | | ✓ | ✓ | | Manage Project Operations | | | | ✓ | ✓ | -| View Pods logs | | | | ✓ | ✓ | +| View Pods logs | | | ✓ | ✓ | ✓ | | Read Terraform state | | | ✓ | ✓ | ✓ | | Manage Terraform state | | | | ✓ | ✓ | | Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | @@ -155,7 +156,7 @@ The following table depicts the various user permission levels in a project. | Transfer project to another namespace | | | | | ✓ | | Rename project | | | | | ✓ | | Remove fork relationship | | | | | ✓ | -| Remove project | | | | | ✓ | +| Delete project | | | | | ✓ | | Archive project | | | | | ✓ | | Delete issues | | | | | ✓ | | Delete pipelines | | | | | ✓ | @@ -166,7 +167,8 @@ The following table depicts the various user permission levels in a project. | View CI\CD analytics | | ✓ | ✓ | ✓ | ✓ | | View Code Review analytics **(STARTER)** | | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Issues analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Merge Request analytics **(STARTER)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Repository analytics | | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -191,7 +193,7 @@ 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 +- 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) @@ -245,8 +247,8 @@ group. | Create/edit group epic **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Manage group labels | | ✓ | ✓ | ✓ | ✓ | | See a container registry | | ✓ | ✓ | ✓ | ✓ | -| Pull [packages](packages/index.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Publish [packages](packages/index.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | Create project in group | | | ✓ (3) | ✓ (3) | ✓ (3) | | Share (invite) groups with groups | | | | | ✓ | @@ -270,7 +272,7 @@ group. | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Issues analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Billing **(FREE ONLY)** | | | | | ✓ (4) | @@ -308,10 +310,10 @@ External users: logged out). Access can be granted by adding the user as member to the project or group. -Like usual users, they will receive a role in the project or group with all +Like usual users, they receive a role in the project or group with all the abilities that are mentioned in the [permissions table above](#project-members-permissions). For example, if an external user is added as Guest, and your project is -private, they will not have access to the code; you would need to grant the external +private, they do not have access to the code; you need to grant the external user access at the Reporter level or above if you want them to have access to the code. You should always take into account the [project's visibility and permissions settings](project/settings/index.md#sharing-and-permissions) @@ -324,7 +326,7 @@ An administrator can flag a user as external by either of the following methods: - Either [through the API](../api/users.md#user-modification). - Or by navigating to the **Admin Area > Overview > Users** to create a new user - or edit an existing one. There, you will find the option to flag the user as + or edit an existing one. There, you can find the option to flag the user as external. ### Setting new users to external @@ -332,14 +334,14 @@ An administrator can flag a user as external by either of the following methods: By default, new users are not set as external users. This behavior can be changed by an administrator on the **Admin Area > Settings > General** page, under **Account and limit**. -If you change the default behavior of creating new users as external, you will +If you change the default behavior of creating new users as external, you have the option to narrow it down by defining a set of internal users. The **Internal users** field allows specifying an email address regex pattern to identify default internal users. New users whose email address matches the regex -pattern will be set to internal by default rather than an external collaborator. +pattern are set to internal by default rather than an external collaborator. The regex pattern format is Ruby, but it needs to be convertible to JavaScript, -and the ignore case flag will be set (`/regex pattern/i`). Here are some examples: +and the ignore case flag is set (`/regex pattern/i`). Here are some examples: - Use `\.internal@domain\.com$` to mark email addresses ending with `.internal@domain.com` as internal. @@ -354,21 +356,21 @@ Be aware that this regex could lead to a When a user is given Guest permissions 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 will not consume a license seat. +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. -If the user is assigned a higher role on any projects or groups, the user will -take a license seat. If a user creates a project, the user becomes a Maintainer +If the user is assigned a higher role on any projects or groups, the user +takes a license seat. If a user creates a project, the user becomes a Maintainer on the project, resulting in the use of a license seat. Also, note that if your -project is internal or private, Guest users will have all the abilities that are +project is internal or private, Guest users have all the abilities that are mentioned in the [permissions table above](#project-members-permissions) (they -will not be able to browse the project's repository for example). +are unable to browse the project's repository, for example). TIP: **Tip:** To prevent a guest user from creating projects, as an admin, you can edit the user's profile to mark the user as [external](#external-users-core-only). Beware though that even if a user is external, if they already have Reporter or -higher permissions in any project or group, they will **not** be counted as a +higher permissions in any project or group, they are **not** counted as a free guest user. ## Auditor users **(PREMIUM ONLY)** @@ -415,7 +417,7 @@ instance and project. In addition, all admins can use the admin interface under | See commits and jobs | ✓ | ✓ | ✓ | ✓ | | Retry or cancel job | | ✓ | ✓ | ✓ | | Erase job artifacts and trace | | ✓ (*1*) | ✓ | ✓ | -| Remove project | | | ✓ | ✓ | +| Delete project | | | ✓ | ✓ | | Create project | | | ✓ | ✓ | | Change project configuration | | | ✓ | ✓ | | Add specific runners | | | ✓ | ✓ | @@ -432,7 +434,7 @@ instance and project. In addition, all admins can use the admin interface under NOTE: **Note:** In GitLab 11.0, the Master role was renamed to Maintainer. ->**Note:** +NOTE: **Note:** GitLab 8.12 has a completely redesigned job permissions system. Read all about the [new model and its implications](project/new_ci_build_permissions_model.md). @@ -473,7 +475,7 @@ for details about the pipelines security model. ## LDAP users permissions Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user. -Read through the documentation on [LDAP users permissions](group/index.md#manage-group-memberships-via-ldap) to learn more. +Read through the documentation on [LDAP users permissions](group/index.md#manage-group-memberships-via-ldap-starter-only) to learn more. ## Project aliases diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 4f769f9a671..0e645e1b4a3 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -93,7 +93,7 @@ To set up 2FA with a U2F device: 1. Go to your [**Profile settings**](../index.md#profile-settings). 1. Go to **Account**. 1. Click **Enable Two-Factor Authentication**. -1. Plug in your U2F device. +1. Connect your U2F device. 1. Click on **Set up New U2F Device**. 1. A light will start blinking on your device. Activate it by pressing its button. @@ -109,9 +109,9 @@ CAUTION: **Caution:** Each code can be used only once to log in to your account. Immediately after successfully enabling two-factor authentication, you'll be -prompted to download a set of set recovery codes. Should you ever lose access -to your one time password authenticator, you can use one of them to log in to -your account. We suggest copying them, printing them, or downloading them using +prompted to download a set of generated recovery codes. Should you ever lose access +to your one-time password authenticator, you can use one of these recovery codes to log in to +your account. We suggest copying and printing them, or downloading them using the **Download codes** button for storage in a safe place. If you choose to download them, the file will be called `gitlab-recovery-codes.txt`. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 7a871afd861..b6ef6d7fdb7 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -22,7 +22,7 @@ See the [authentication topic](../../topics/authentication/index.md) for more de ### Unknown sign-in -GitLab will notify you if a sign-in occurs that is from an unknown IP address or device. +GitLab notifies you if a sign-in occurs that is from an unknown IP address or device. See [Unknown Sign-In Notification](unknown_sign_in_notification.md) for more details. ## User profile @@ -32,7 +32,7 @@ To access your profile: 1. Click on your avatar. 1. Select **Profile**. -On your profile page, you will see the following information: +On your profile page, you can see the following information: - Personal information - Activity stream: see your activity streamline and the history of your contributions @@ -85,7 +85,7 @@ If you don't know your current password, select the 'I forgot my password' link. Your `username` is a unique [`namespace`](../group/index.md#namespaces) related to your user ID. Changing it can have unintended side effects, read -[how redirects will behave](../project/index.md#redirects-when-changing-repository-paths) +[how redirects behave](../project/index.md#redirects-when-changing-repository-paths) before proceeding. To change your `username`: @@ -109,7 +109,7 @@ which also covers the case where you have projects hosted with ## Private profile -The following information will be hidden from the user profile page (`https://gitlab.example.com/username`) if this feature is enabled: +The following information is hidden from the user profile page (`https://gitlab.example.com/username`) if this feature is enabled: - Atom feed - Date when account is created @@ -152,7 +152,7 @@ To add links to other accounts: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14078) in GitLab 11.3. -Enabling private contributions will include contributions to private projects, in the user contribution calendar graph and user recent activity. +Enabling private contributions includes contributions to private projects, in the user contribution calendar graph and user recent activity. To enable private contributions: @@ -225,7 +225,7 @@ To enable this option: 1. Select **Use a private email** option. 1. Click **Update profile settings**. -Once this option is enabled, every Git-related action will be performed using the private commit email. +Once this option is enabled, every Git-related action is performed using the private commit email. To stay fully anonymous, you can also copy this private commit email and configure it on your local machine using the following command: @@ -253,7 +253,7 @@ When the `_gitlab_session` expires or isn't available, GitLab uses the `remember to get you a new `_gitlab_session` and keep you signed in through browser restarts. After your `remember_user_token` expires and your `_gitlab_session` is cleared/expired, -you will be asked to sign in again to verify your identity for security reasons. +you are asked to sign in again to verify your identity for security reasons. ### Increased sign-in time diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index dbf486e399e..336c1b8f254 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -187,7 +187,7 @@ To minimize the number of notifications that do not require any action, from [Gi | Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | | Failed pipeline | The author of the pipeline | -| Fixed pipeline | The author of the pipeline. Enabled by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1. Administrators can disable this notification option using the `ci_pipeline_fixed_notifications` [feature flag](../../administration/feature_flags.md). | +| Fixed pipeline | The author of the pipeline. Enabled by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1. | | Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set. If the pipeline failed previously, a `Fixed pipeline` message will be sent for the first successful pipeline after the failure, then a `Successful pipeline` message for any further successful pipelines. | | New epic **(ULTIMATE)** | | | Close epic **(ULTIMATE)** | | diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 59ca124f566..ae73842dd98 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -9,6 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3749) in GitLab 8.8. > - [Notifications about expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in GitLab 12.6. +> - [Notifications about expired tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/214721) added in GitLab 13.3. > - [Token lifetime limits](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personalproject-access-tokens). @@ -17,7 +18,9 @@ You can also use personal access tokens with Git to authenticate over HTTP or SS Personal access tokens expire on the date you define, at midnight UTC. -- GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that will expire in under seven days. The owners of these tokens are notified by email. +- GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in under seven days. The owners of these tokens are notified by email. +- GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expired on the current date. The owners of these tokens are notified by email. +To turn on the notification for expired personal access tokens in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-notification-for-expired-personal-access-token-core-only). **(CORE ONLY)** - In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only). - In GitLab Ultimate, administrators may [toggle enforcement of personal access token expiry](../admin_area/settings/account_and_limit_settings.md#optional-enforcement-of-personal-access-token-expiry-ultimate-only). @@ -25,6 +28,23 @@ For examples of how you can use a personal access token to authenticate with the GitLab also offers [impersonation tokens](../../api/README.md#impersonation-tokens) which are created by administrators via the API. They're a great fit for automated authentication as a specific user. +## Enable or disable notification for Expired personal access token **(CORE ONLY)** + +[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(:expired_pat_email_notification) +``` + +To disable it: + +```ruby +Feature.disable(:expired_pat_email_notification) +``` + ## Creating a personal access token You can create as many personal access tokens as you like from your GitLab @@ -36,8 +56,8 @@ profile. 1. Choose a name and optional expiry date for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-personal-access-token). 1. Click the **Create personal access token** button. -1. Save the personal access token somewhere safe. Once you leave or refresh - the page, you won't be able to access it again. +1. Save the personal access token somewhere safe. If you navigate away or refresh +your page, and you did not save the token, you must create a new one. ### Revoking a personal access token @@ -46,7 +66,7 @@ respective **Revoke** button under the **Active Personal Access Token** area. ### Token activity -You can see when a token was last used from the **Personal Access Tokens** page. Updates to the token usage is fixed at once per 24 hours. Requests to [API resources](../../api/api_resources.md) and the [GraphQL API](../../api/graphql/index.md) will update a token's usage. +You can see when a token was last used from the **Personal Access Tokens** page. Updates to the token usage is fixed at once per 24 hours. Requests to [API resources](../../api/api_resources.md) and the [GraphQL API](../../api/graphql/index.md) update a token's usage. ## Limiting scopes of a personal access token @@ -60,14 +80,15 @@ the following table. | `api` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | | `read_api` | [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | | `read_registry` | [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11845) | Allows to read (pull) [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `sudo` | [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14838) | Allows performing API actions as any user in the system (if the authenticated user is an admin). | +| `write_registry` | [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) | Allows to write (push) [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `sudo` | [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14838) | Allows performing API actions as any user in the system (if the authenticated user is an administrator). | | `read_repository` | [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) | Allows read-only access (pull) to the repository through `git clone`. | | `write_repository` | [GitLab 11.11](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26021) | Allows read-write access (pull, push) to the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled. | ## Programmatically creating a personal access token You can programmatically create a predetermined personal access token for use in -automation or tests. You will need sufficient access to run a +automation or tests. You need sufficient access to run a [Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session) for your GitLab instance. @@ -89,15 +110,15 @@ sudo gitlab-rails runner "token = User.find_by_username('automation-bot').person ``` NOTE: **Note:** -The token string must be 20 characters in length, or it will not be -recognized as a personal access token. +The token string must be 20 characters in length to be +recognized as a valid personal access token. The list of valid scopes and what they do can be found [in the source code](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/auth.rb). ## Programmatically revoking a personal access token -You can programmatically revoke a personal access token. You will need +You can programmatically revoke a personal access token. You need sufficient access to run a [Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session) for your GitLab instance. diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 9ebf7f821a1..1acdc56de54 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -1,3 +1,11 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference +description: "Autocomplete chars in Markdown fields." +--- + # Autocomplete characters The autocomplete characters provide a quick way of entering field values into diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 542a3763008..ed6e2460554 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference, howto +--- + # Badges > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. @@ -29,6 +36,20 @@ clicking on the trash icon. Badges associated with a group can only be edited or deleted on the [group level](#group-badges). +### Example project badge: Pipeline Status + +A common project badge presents the GitLab CI pipeline status. + +To add this badge to a project: + +1. Navigate to your project's **Settings > General > Badges**. +1. Under **Name**, enter _Pipeline Status_. +1. Under **Link**, enter the following URL: + `https://gitlab.com/%{project_path}/-/commits/%{default_branch}` +1. Under **Badge image URL**, enter the following URL: + `https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg` +1. Submit the badge by clicking the **Add badge** button. + ## Group badges Badges can be added to a group and will then be visible on every project's diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index b11483a7446..d5713f20257 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -56,12 +56,17 @@ Generate an access key for the IAM user, and configure GitLab with the credentia To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes**, for an instance-level cluster. + - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Group's **Kubernetes** page, for a group-level cluster. + - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an `Account ID` and `External ID` to use in the next step. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. + To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions + to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. + In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` + policy for this role in order for GitLab to manage the EKS cluster correctly. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: 1. From the left panel, select **Roles**. 1. Click **Create role**. @@ -135,11 +140,17 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Authenticate with AWS**. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Kubernetes version** - The Kubernetes version to use. Currently the only version supported is 1.14. - - **Role name** - Select the [IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) - to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. This IAM role is separate - to the IAM role created above, you will need to create it if it does not yet exist. + - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS + and the Kubernetes control plane to manage AWS resources on your behalf. + + NOTE: **Note:** + This IAM role is _not_ the IAM role you created in the previous step. It should be + the one you created much earlier by following the + [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) + guide. + - **Region** - The [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in which the cluster will be created. - **Key pair name** - Select the [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) @@ -194,10 +205,10 @@ If the `Cluster` resource failed with the error the role specified in **Role name** is not configured correctly. NOTE: **Note:** -This role should not be the same as the one created above. If you don't have an -existing -[EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html), -you must create one. +This role should be the role you created by following the +[EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide. +In addition to the policies that guide suggests, you must also include the +`AmazonEKSClusterPolicy` policy for this role in order for GitLab to manage the EKS cluster correctly. ## Existing EKS cluster diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 2746076befe..720f9bdf253 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -48,14 +48,14 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP console that will host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 65f1c59f4ca..e4a750084c9 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -142,7 +142,7 @@ Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level 1. Navigate to your: - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Click the **Create new cluster** tab. 1. Click either **Amazon EKS** or **Google GKE**, and follow the instructions for your desired service: @@ -164,12 +164,12 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + 1. **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Click the **Add existing cluster** tab and fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. 1. **Environment scope** (required) - The - [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + [associated environment](index.md#setting-the-environment-scope) to this cluster. 1. **API URL** (required) - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes exposes several APIs, we want the "base" URL that is common to all of them. @@ -331,7 +331,7 @@ a new cluster or added an existing one. To disable Kubernetes cluster integratio 1. Navigate to your: - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click on the name of the cluster. 1. Click the **GitLab Integration** toggle. 1. Click **Save changes**. diff --git a/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_10.png b/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_10.png Binary files differdeleted file mode 100644 index ee37970d867..00000000000 --- a/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index ddcfd376d89..98078854050 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -67,17 +67,17 @@ to: ### Multiple Kubernetes clusters > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Core in 13.2. You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, like dev, staging, production, and so on. Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope-premium) that will +[set an environment scope](#setting-the-environment-scope) that will differentiate the new cluster with the rest. -#### Setting the environment scope **(PREMIUM)** +#### Setting the environment scope When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the @@ -368,7 +368,7 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of ### Visualizing cluster health > - [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 core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor 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/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index ee642dc18cf..afb6d016f45 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Monitor +group: APM 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 --- @@ -9,56 +9,54 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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 Core](https://about.gitlab.com/pricing/) 12.9. -GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). -By displaying the logs directly in GitLab in the **Log Explorer**, developers can avoid -managing console tools or jumping to a different interface. - -NOTE: **Note:** -[Learn more about Kubernetes + GitLab](https://about.gitlab.com/solutions/kubernetes/). -Everything you need to build, test, deploy, and run your application at scale. - -## Overview - -[Kubernetes](https://kubernetes.io) logs can be viewed directly within GitLab with -the **Log Explorer**. +GitLab makes it easy to view the logs of running pods or managed applications in +[connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab +in the **Log Explorer**, developers can avoid managing console tools or jumping +to a different interface. The **Log Explorer** interface provides a set of filters +above the log file data, depending on your configuration:  +- **Namespace** - Select the environment to display. Users with Maintainer or + greater [permissions](../../permissions.md) can also select Managed Apps. +- **Search** - Only available if the Elastic Stack managed application is installed. +- **Select time range** - Select the range of time to display. Only available if the + Elastic Stack managed application is installed. +- **Scroll to bottom** **{scroll_down}** - Scroll to the end of the displayed logs. +- **Refresh** **{retry}** - Reload the displayed logs. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -To learn more, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw). +To learn more about the Log Explorer, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw). + +NOTE: **Note:** +[Learn more about Kubernetes + GitLab](https://about.gitlab.com/solutions/kubernetes/). +Everything you need to build, test, deploy, and run your application at scale. ## Requirements [Deploying to a Kubernetes environment](../deploy_boards.md#enabling-deploy-boards) is required to use Logs. -## Usage - -To access logs, you must have the right [permissions](../../permissions.md#project-members-permissions). - -You can access them in two ways. - -### From the project sidebar +## Accessing the log explorer -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5. +To access the **Log explorer**, click the **More actions** **{ellipsis_v}** menu on +a [metrics dashboard](../../../operations/metrics/index.md) and select **View logs**, or: -Go to **{cloud-gear}** **Operations > Pod logs** on the sidebar menu to display -the **Log Explorer**. +1. Sign in as a user with the _View pod logs_ + [permissions](../../permissions.md#project-members-permissions) in the project. +1. *To navigate to the **Log Explorer** from the sidebar menu,* go to + **{cloud-gear}** **Operations > Pod logs**. + ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5.) +1. *To navigate to the **Log Explorer** from a specific pod on a [Deploy Board](../deploy_boards.md):* - - -### From Deploy Boards - -Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): - -1. Go to **{cloud-gear}** **Operations > Environments** and find the environment - which contains the desired pod, like `production`. -1. On the **Environments** page, you should see the status of the environment's - pods with [Deploy Boards](../deploy_boards.md). -1. When mousing over the list of pods, a tooltip will appear with the exact pod name - and status. -  -1. Click on the desired pod to display the **Log Explorer**. + 1. Go to **{cloud-gear}** **Operations > Environments** and find the environment + which contains the desired pod, like `production`. + 1. On the **Environments** page, you should see the status of the environment's + pods with [Deploy Boards](../deploy_boards.md). + 1. When mousing over the list of pods, GitLab displays a tooltip with the exact pod name + and status. +  + 1. Click on the desired pod to display the **Log Explorer**. ### Logs view @@ -69,6 +67,7 @@ The **Log Explorer** lets you filter the logs by: - [From GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656), [full text search](#full-text-search). - [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/197879), dates. +- [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/208790), managed apps. Loading more than 500 log lines is possible from [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198050) onward. @@ -93,17 +92,16 @@ Click **Show last** in the **Log Explorer** to see the available options. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656) in GitLab 12.7. When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, -you can search the content of your logs through a search bar. - -The search is passed on to Elasticsearch using the +you can search the content of your logs through a search bar. The search is passed +to Elasticsearch using the [simple_query_string](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) Elasticsearch function, which supports the following operators: -| Operator | Description | -|----------------------------|------------------------------------------------------------| -| `\|` | An OR operation. | +| Operator | Description | +|----------------------------|-------------------------------------------------------------| +| `\|` | An `OR` operation. | | `-` | Negates a single token. | -| `+` | An AND operation. | +| `+` | An `AND` operation. | | `"` | Wraps a number of tokens to signify a phrase for searching. | | `*` (at the end of a term) | A prefix query. | | `(` and `)` | Precedence. | diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index a592d59f964..360b02efb69 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -129,7 +129,7 @@ the components outlined above and the pre-loaded demo runbook. %env DB_NAME={project.variables.get('DB_NAME').value} ``` - 1. Navigate to **{settings}** **Settings >> CI/CD >> Variables** to create + 1. Navigate to **Settings > CI/CD > Variables** to create the variables in your project.  diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index b4c20cb8dbc..5b9f776080b 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab makes it easy to secure applications deployed in [connected Kubernetes clusters](index.md). You can benefit from the protection of a [Web Application Firewall](../../../topics/web_application_firewall/quick_start_guide.md), [Network Policies](../../../topics/autodevops/stages.md#network-policy), -or even [Container Host Security](../../clusters/applications.md#install-falco-using-gitlab-cicd). +and [Container Host Security](../../clusters/applications.md#install-falco-using-gitlab-cicd). This page contains full end-to-end steps and instructions to connect your cluster to GitLab and install these features, whether or not your applications are deployed through GitLab CI/CD. If you @@ -25,7 +25,7 @@ At a high level, the required steps include the following: - Connect the cluster to GitLab. - Set up one or more runners. - Set up a cluster management project. -- Install a Web Application Firewall, Network Policies, and/or Container Host +- Install a Web Application Firewall, and/or Network Policies, and/or Container Host Security. - Install Prometheus to get statistics and metrics in the [threat monitoring](../../application_security/threat_monitoring/) @@ -40,6 +40,10 @@ Minimum requirements (depending on the GitLab Manage Application you want to ins ### Understanding how GitLab Managed Apps are installed +NOTE: **Note:** +These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm +Tiller daemon running in a pod in the cluster. + You install GitLab Managed Apps from the GitLab web interface with a one-click setup process. GitLab uses Sidekiq (a background processing service) to facilitate this. @@ -52,12 +56,8 @@ uses Sidekiq (a background processing service) to facilitate this. Sidekiq-->>-GitLab: Refresh UI ``` -NOTE: **Note:** -This diagram uses the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm -Tiller daemon running in a pod in the cluster. - Although this installation method is easier because it's a point-and-click action in the user -interface, it's inflexible and hard to debug. When something goes wrong, you can't see the +interface, it's inflexible and harder to debug. If something goes wrong, you can't see the deployment logs. The Web Application Firewall feature uses this installation method. However, the next generation of GitLab Managed Apps V2 ([CI/CD-based GitLab Managed Apps](https://gitlab.com/groups/gitlab-org/-/epics/2103)) @@ -75,10 +75,10 @@ sequenceDiagram ``` Debugging is easier because you have access to the raw logs of these jobs (the Helm Tiller output is -available as an artifact in case of failure) and the flexibility is much better. Since these +available as an artifact in case of failure), and the flexibility is much better. Since these deployments are only triggered when a pipeline is running (most likely when there's a new commit in the cluster management repository), every action has a paper trail and follows the classic merge -request workflow (approvals, merge, deploy). The Network Policy (Cilium) Managed App and Container +request workflow (approvals, merge, deploy). The Network Policy (Cilium) Managed App, and Container Host Security (Falco) are deployed with this model. ## Connect the cluster to GitLab @@ -151,4 +151,5 @@ falco: installed: true ``` -[Read more] about configuring Container Host Security. +[Read more](../../clusters/applications.md#install-falco-using-gitlab-cicd) +about configuring Container Host Security. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 595d8fb3895..543ffdbce8f 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -373,7 +373,7 @@ variables. To set these: -1. Navigate to the project's **{settings}** **Settings > CI / CD**. +1. Navigate to the project's **Settings > CI / CD**. 1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index e2c2cae3158..be34053cdc7 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference --- @@ -10,7 +13,7 @@ Code Intelligence adds code navigation features common to interactive development environments (IDE), including: - Type signatures and symbol documentation. -- Go-to definition +- Go-to definition. Code Intelligence is built into GitLab and powered by [LSIF](https://lsif.dev/) (Language Server Index Format), a file format for precomputed code @@ -39,6 +42,36 @@ After the job succeeds, code intelligence data can be viewed while browsing the  +## Find references + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217392) in GitLab 13.2. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/225621) on GitLab 13.3. +> - It's enabled on GitLab.com. + +To find where a particular object is being used, you can see links to specific lines of code +under the **References** tab: + + + +### Enable or disable find references + +Find references 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 for your instance. + +To disable it: + +```ruby +Feature.disable(:code_navigation_references) +``` + +To enable it: + +```ruby +Feature.enable(:code_navigation_references) +``` + ## Language support Generating an LSIF file requires a language server indexer implementation for the diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index b35d04dfdfc..dbe3f3dc891 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference --- @@ -175,7 +178,7 @@ Owners" section: ```plaintext [README Owners] -README.md @user1 @user 2 +README.md @user1 @user2 internal/README.md @user2 ``` diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 0a613ff918b..50fb24b555b 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -36,7 +36,7 @@ to the latest release. Since Deploy Boards are tightly coupled with Kubernetes, there is some required knowledge. In particular, you should be familiar with: -- [Kubernetes pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/) +- [Kubernetes pods](https://kubernetes.io/docs/concepts/workloads/pods/) - [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) - [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) - [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) diff --git a/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png b/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png Binary files differindex 462141ef82a..15e6e71803c 100644 --- a/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png +++ b/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png diff --git a/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png b/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png Binary files differindex 3e6d1605f95..2f708555af1 100644 --- a/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png +++ b/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 32d3eab5e62..81c9008c5b3 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -121,7 +121,7 @@ repositories to secure, shared services, such as CI/CD. Instance administrators can add public deploy keys: -1. Go to **Admin Area** (**{admin}**) **> Deploy Keys**. +1. Go to **Admin Area > Deploy Keys**. 1. Click on **New deploy key**. Make sure your new key has a meaningful title, as it is the primary way for project diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index b7daca567f4..5ca421dda5b 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -25,7 +25,7 @@ You can create as many deploy tokens as you like from the settings of your proje 1. Log in to your GitLab account. 1. Go to the project (or group) you want to create Deploy Tokens for. -1. Go to **{settings}** **Settings** > **Repository**. +1. Go to **Settings > Repository**. 1. Click on "Expand" on **Deploy Tokens** section. 1. Choose a name, expiry date (optional), and username (optional) for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 9069a231db4..ed80e5f6a32 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference, howto +--- + # File Locking **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 260e618ba03..577f0f1f754 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference +--- + # Git Attributes GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index a2740294e62..5f7c754ec75 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference +--- + # Syntax Highlighting GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient. diff --git a/doc/user/project/img/code_intelligence_find_references_v13_3.png b/doc/user/project/img/code_intelligence_find_references_v13_3.png Binary files differnew file mode 100644 index 00000000000..415fe86cc75 --- /dev/null +++ b/doc/user/project/img/code_intelligence_find_references_v13_3.png diff --git a/doc/user/project/img/code_intelligence_v13_1.png b/doc/user/project/img/code_intelligence_v13_1.png Binary files differindex 0dff27bab43..744195caed2 100644 --- a/doc/user/project/img/code_intelligence_v13_1.png +++ b/doc/user/project/img/code_intelligence_v13_1.png diff --git a/doc/user/project/img/sectional_code_owners_v13.2.png b/doc/user/project/img/sectional_code_owners_v13.2.png Binary files differindex 894771c26af..58b331950f4 100644 --- a/doc/user/project/img/sectional_code_owners_v13.2.png +++ b/doc/user/project/img/sectional_code_owners_v13.2.png diff --git a/doc/user/project/img/service_desk_custom_email_address_v13_0.png b/doc/user/project/img/service_desk_custom_email_address_v13_0.png Binary files differindex 6ce8bf45085..3789e039904 100644 --- a/doc/user/project/img/service_desk_custom_email_address_v13_0.png +++ b/doc/user/project/img/service_desk_custom_email_address_v13_0.png diff --git a/doc/user/project/img/status_page_detail_link_v13_1.png b/doc/user/project/img/status_page_detail_link_v13_1.png Binary files differdeleted file mode 100644 index f3d1005447c..00000000000 --- a/doc/user/project/img/status_page_detail_link_v13_1.png +++ /dev/null diff --git a/doc/user/project/img/status_page_detail_v12_10.png b/doc/user/project/img/status_page_detail_v12_10.png Binary files differdeleted file mode 100644 index d8dbbb539e6..00000000000 --- a/doc/user/project/img/status_page_detail_v12_10.png +++ /dev/null diff --git a/doc/user/project/img/status_page_incidents_v12_10.png b/doc/user/project/img/status_page_incidents_v12_10.png Binary files differdeleted file mode 100644 index 3540fbffcf8..00000000000 --- a/doc/user/project/img/status_page_incidents_v12_10.png +++ /dev/null diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 173ba71b167..a825084dd1a 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -27,7 +27,7 @@ The following table illustrates the main differences between ClearCase and Git: | Server | UNIX, Windows legacy systems | UNIX, macOS | | License | Proprietary | GPL | -_Taken from the slides [ClearCase and the journey to Git](https://www.open.collab.net/media/pdfs/ClearCase-and-the-journey-to-Git.pdf) provided by collab.net_ +_Taken from the slides [ClearCase and the journey to Git](https://docplayer.net/42708453-Clearcase-the-journey-to-git-migrating-your-skills-and-vobs-to-git.html) provided by [collab.net](https://www.collab.net/)_ ## Why migrate @@ -47,7 +47,7 @@ While there doesn't exist a tool to fully migrate from ClearCase to Git, here are some useful links to get you started: - [Bridge for Git and ClearCase](https://github.com/charleso/git-cc) -- [Slides "ClearCase and the journey to Git"](https://www.open.collab.net/media/pdfs/ClearCase-and-the-journey-to-Git.pdf) +- [Slides "ClearCase and the journey to Git"](https://docplayer.net/42708453-Clearcase-the-journey-to-git-migrating-your-skills-and-vobs-to-git.html) - [ClearCase to Git](https://therub.org/2013/07/19/clearcase-to-git/) - [Dual syncing ClearCase to Git](https://therub.org/2013/10/22/dual-syncing-clearcase-and-git/) - [Moving to Git from ClearCase](https://sateeshkumarb.wordpress.com/2011/01/15/moving-to-git-from-clearcase/) diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 543fffd33d6..81ab16590dc 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -11,7 +11,7 @@ Import your projects from Gitea to GitLab with minimal effort. ## Overview ->**Note:** +NOTE: **Note:** This requires Gitea `v1.0.0` or newer. - At its current state, Gitea importer can import: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index b7754e60837..531b308111a 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -52,7 +52,7 @@ 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 - [primary email address](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) + [primary email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) that matches their GitLab account's email address. If a user referenced in the project is not found in GitLab's database, the project creator (typically the user @@ -81,7 +81,7 @@ Before you begin, ensure that any GitHub users who you want to map to GitLab use - A GitLab account that has logged in using the GitHub icon \- or - -- A GitLab account with an email address that matches the [public email address](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) of the GitHub user +- A GitLab account with an email address that matches the [public email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with the user account that is performing the import. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index b9aea629e85..6c622ece4ac 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -13,7 +13,7 @@ mind that it is possible only if GitLab.com integration is enabled on your GitLa To get to the importer page you need to go to "New project" page. ->**Note:** +NOTE: **Note:** If you are interested in importing Wiki and Merge Request data to your new instance, you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data) diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png b/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png Binary files differindex d98ad2aaa6e..317a426394c 100644 --- a/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png +++ b/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png Binary files differindex 9cbffe2bb36..8a94d33d47b 100644 --- a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png +++ b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png diff --git a/doc/user/project/import/img/manifest_status.png b/doc/user/project/import/img/manifest_status.png Binary files differdeleted file mode 100644 index b706116a2ac..00000000000 --- a/doc/user/project/import/img/manifest_status.png +++ /dev/null diff --git a/doc/user/project/import/img/manifest_status_v13_3.png b/doc/user/project/import/img/manifest_status_v13_3.png Binary files differnew file mode 100644 index 00000000000..3f0063e6715 --- /dev/null +++ b/doc/user/project/import/img/manifest_status_v13_3.png diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 482e632baa2..7f179865f4f 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -77,10 +77,9 @@ Importing large projects may take several minutes depending on the size of the i In the **Jira-GitLab user mapping template** section, the table shows to which GitLab users your Jira users will be mapped. - If it wasn't possible to match a Jira user with a GitLab user, the dropdown defaults to the user - conducting the import. + When the form appears, the dropdown defaults to the user conducting the import. -1. To change any of the suggested mappings, click the dropdown in the **GitLab username** column and +1. To change any of the mappings, click the dropdown in the **GitLab username** column and select the user you want to map to each Jira user. The dropdown may not show all the users, so use the search bar to find a specific diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 0374e0acf9a..60524f3cc69 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -62,4 +62,4 @@ You can start the import with: to the import status page with projects list based on the manifest file. 1. Check the list and click **Import all repositories** to start the import. -  +  diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 1c9ee7476bd..faa2a9b4927 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -41,6 +41,14 @@ Advantages of migrating to Git/GitLab: ## How to migrate -The best option to migrate from TFVC to Git is to use the [`git-tfs`](https://github.com/git-tfs/git-tfs) -tool. Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) -guide for more details. +Migration options from TFVC to Git depend on your operating system. + +- If you're migrating on Microsoft Windows: + + Use the [`git-tfs`](https://github.com/git-tfs/git-tfs) +tool. + Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) guide for details. + +- If you're on a Unix-based system: + + Follow the procedures described with this [TFVC to Git migration tool](https://github.com/turbo/gtfotfs). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 1e71674c16f..4e5b924a1b7 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference +--- + # Projects In GitLab, you can create projects for hosting @@ -96,9 +103,9 @@ When you create a project in GitLab, you'll have access to a large number of - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of the source, build output, other metadata, and other artifacts associated with a released version of your code. -- [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. **(PREMIUM)** -- [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. **(PREMIUM)** -- [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. **(PREMIUM)** +- [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. +- [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. +- [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. - [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** - [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** @@ -173,22 +180,22 @@ Read through the documentation on [project settings](settings/index.md). - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) -## Remove a project +## Delete a project -To remove a project, first navigate to the home page for that project. +To delete a project, first navigate to the home page for that project. 1. Navigate to **Settings > General**. 1. Expand the **Advanced** section. -1. Scroll down to the **Remove project** section. -1. Click **Remove project** +1. Scroll down to the **Delete project** section. +1. Click **Delete project** 1. Confirm this action by typing in the expected text. -### Delayed removal **(PREMIUM)** +### Delayed deletion **(PREMIUM)** -By default, clicking to remove a project is followed by a seven day delay. Admins can restore the project during this period of time. -This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only). +By default, clicking to delete a project is followed by a seven day delay. Admins can restore the project during this period of time. +This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). -Admins can view all projects pending deletion. If you're an administrator, go to the top navigation bar, click **Projects > Your projects**, and then select the **Removed projects** tab. +Admins can view all projects pending deletion. If you're an administrator, go to the top navigation bar, click **Projects > Your projects**, and then select the **Deleted projects** tab. From this tab an admin can restore any project. ## CI/CD for external repositories **(PREMIUM)** diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 7b21c590c8a..9cade323ed2 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Atlassian Bamboo CI Service GitLab provides integration with Atlassian Bamboo for continuous integration. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 6d44c56743e..2ed14a4c69c 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Bugzilla Service Navigate to the [Integrations page](overview.md#accessing-integrations), diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 7d15ae82b6f..1329f584fdc 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,8 +1,14 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Custom Issue Tracker service To enable the Custom Issue Tracker integration in a project: -1. Go to **{settings}** **Settings > Integrations**. +1. Go to **Settings > Integrations**. 1. Click **Custom Issue Tracker** 1. Fill in the tracker's details, such as title, description, and URLs. You will be able to edit these fields later as well. diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index aa45cc38cb5..f261362eeae 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Discord Notifications service > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22684) in GitLab 11.6. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index b0838690d3b..d8b864e0396 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Enabling emails on push By enabling this service, you will receive email notifications for every change diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 3490a3f2b9e..dc6aa40ea82 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -29,8 +29,8 @@ To obtain credentials for setting up a generic alerts integration: - Sign in to GitLab as a user with maintainer [permissions](../../permissions.md) for a project. - Navigate to the **Operations** page for your project, depending on your installed version of GitLab: - - *In GitLab versions 13.1 and greater,* navigate to **{settings}** **Settings > Operations** in your project. - - *In GitLab versions prior to 13.1,* navigate to **{settings}** **Settings > Integrations** in your project. GitLab will display a banner encouraging you to enable the Alerts endpoint in **{settings}** **Settings > Operations** instead. + - *In GitLab versions 13.1 and greater,* navigate to **Settings > Operations** in your project. + - *In GitLab versions prior to 13.1,* navigate to **Settings > Integrations** in your project. GitLab will display a banner encouraging you to enable the Alerts endpoint in **Settings > Operations** instead. - Click **Alerts endpoint**. - Toggle the **Active** alert setting to display the **URL** and **Authorization Key** for the webhook configuration. @@ -101,7 +101,7 @@ After a [project maintainer or owner](#setting-up-generic-alerts) test alert to confirm your integration works properly. 1. Sign in as a user with Developer or greater [permissions](../../../user/permissions.md). -1. Navigate to **{settings}** **Settings > Operations** in your project. +1. Navigate to **Settings > Operations** in your project. 1. Click **Alerts endpoint** to expand the section. 1. Enter a sample payload in **Alert test payload** (valid JSON is required). 1. Click **Test alert payload**. @@ -116,7 +116,7 @@ In GitLab versions 13.2 and greater, GitLab groups alerts based on their payload When an incoming alert contains the same payload as another alert (excluding the `start_time` and `hosts` attributes), GitLab groups these alerts together and displays a counter on the -[Alert Management List](../operations/alert_management.md#alert-management-list) +[Alert Management List](../../../operations/incident_management/incidents.md) and details pages. If the existing alert is already `resolved`, then a new alert will be created instead. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 416996fb629..29818e862e0 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # GitHub project integration **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab Premium 10.6. @@ -14,7 +20,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ### Complete these steps on GitHub -This integration requires a [GitHub API token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with `repo:status` access granted: 1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 7a827364d41..62fccb22d36 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # GitLab Slack application **(FREE ONLY)** > - Introduced in GitLab 9.4. @@ -36,7 +42,7 @@ docs on [Adding an app to your workspace](https://slack.com/help/articles/202035 To enable GitLab's service for your Slack team: -1. Go to your project's **{settings}** **Settings > Integration > Slack application** (only +1. Go to your project's **Settings > Integration > Slack application** (only visible on GitLab.com). 1. Click **Add to Slack**. @@ -47,7 +53,7 @@ That's all! You can now start using the Slack slash commands. To create a project alias on GitLab.com for Slack integration: 1. Go to your project's home page. -1. Navigate to **{settings}** **Settings > Integrations** (only visible on GitLab.com) +1. Navigate to **Settings > Integrations** (only visible on GitLab.com) 1. On the **Integrations** page, click **Slack application**. 1. The current **Project Alias**, if any, is displayed. To edit this value, click **Edit**. diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index f65b31150a9..54f9bd8d622 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Hangouts Chat service > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 2ed7f13db9b..718f00273bd 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Atlassian HipChat GitLab provides a way to send HipChat notifications upon a number of events, diff --git a/doc/user/project/integrations/img/actions_menu_create_new_dashboard_v13_2.png b/doc/user/project/integrations/img/actions_menu_create_new_dashboard_v13_2.png Binary files differdeleted file mode 100644 index 5d530a80421..00000000000 --- a/doc/user/project/integrations/img/actions_menu_create_new_dashboard_v13_2.png +++ /dev/null diff --git a/doc/user/project/integrations/img/copy_link_to_chart_v12_10.png b/doc/user/project/integrations/img/copy_link_to_chart_v12_10.png Binary files differdeleted file mode 100644 index fc205240ea5..00000000000 --- a/doc/user/project/integrations/img/copy_link_to_chart_v12_10.png +++ /dev/null diff --git a/doc/user/project/integrations/img/embed_metrics_issue_template.png b/doc/user/project/integrations/img/embed_metrics_issue_template.png Binary files differdeleted file mode 100644 index ca39a738d5f..00000000000 --- a/doc/user/project/integrations/img/embed_metrics_issue_template.png +++ /dev/null diff --git a/doc/user/project/integrations/img/embedded_metrics_markdown_v12_8.png b/doc/user/project/integrations/img/embedded_metrics_markdown_v12_8.png Binary files differdeleted file mode 100644 index ffd34705464..00000000000 --- a/doc/user/project/integrations/img/embedded_metrics_markdown_v12_8.png +++ /dev/null diff --git a/doc/user/project/integrations/img/embedded_metrics_rendered_v12_8.png b/doc/user/project/integrations/img/embedded_metrics_rendered_v12_8.png Binary files differdeleted file mode 100644 index b024daaaa8e..00000000000 --- a/doc/user/project/integrations/img/embedded_metrics_rendered_v12_8.png +++ /dev/null diff --git a/doc/user/project/integrations/img/grafana_embedded.png b/doc/user/project/integrations/img/grafana_embedded.png Binary files differdeleted file mode 100644 index c7946aa4b10..00000000000 --- a/doc/user/project/integrations/img/grafana_embedded.png +++ /dev/null diff --git a/doc/user/project/integrations/img/grafana_live_embed.png b/doc/user/project/integrations/img/grafana_live_embed.png Binary files differdeleted file mode 100644 index 91970cd379a..00000000000 --- a/doc/user/project/integrations/img/grafana_live_embed.png +++ /dev/null diff --git a/doc/user/project/integrations/img/grafana_panel_v12_5.png b/doc/user/project/integrations/img/grafana_panel_v12_5.png Binary files differdeleted file mode 100644 index 18c17b910cd..00000000000 --- a/doc/user/project/integrations/img/grafana_panel_v12_5.png +++ /dev/null diff --git a/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png b/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png Binary files differdeleted file mode 100644 index fae62dd50df..00000000000 --- a/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png +++ /dev/null diff --git a/doc/user/project/integrations/img/heatmap_chart_too_much_data_v_13_2.png b/doc/user/project/integrations/img/heatmap_chart_too_much_data_v_13_2.png Binary files differdeleted file mode 100644 index c3a391b06c7..00000000000 --- a/doc/user/project/integrations/img/heatmap_chart_too_much_data_v_13_2.png +++ /dev/null diff --git a/doc/user/project/integrations/img/heatmap_panel_type.png b/doc/user/project/integrations/img/heatmap_panel_type.png Binary files differdeleted file mode 100644 index a2b3911ec68..00000000000 --- a/doc/user/project/integrations/img/heatmap_panel_type.png +++ /dev/null diff --git a/doc/user/project/integrations/img/hide_embedded_metrics_v12_10.png b/doc/user/project/integrations/img/hide_embedded_metrics_v12_10.png Binary files differdeleted file mode 100644 index 1213029d1d1..00000000000 --- a/doc/user/project/integrations/img/hide_embedded_metrics_v12_10.png +++ /dev/null diff --git a/doc/user/project/integrations/img/http_proxy_access_v12_5.png b/doc/user/project/integrations/img/http_proxy_access_v12_5.png Binary files differdeleted file mode 100644 index 0036a916a12..00000000000 --- a/doc/user/project/integrations/img/http_proxy_access_v12_5.png +++ /dev/null diff --git a/doc/user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png b/doc/user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png Binary files differdeleted file mode 100644 index a042fbbcf4e..00000000000 --- a/doc/user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png +++ /dev/null diff --git a/doc/user/project/integrations/img/metrics_settings_button_v13_2.png b/doc/user/project/integrations/img/metrics_settings_button_v13_2.png Binary files differdeleted file mode 100644 index d649f77eded..00000000000 --- a/doc/user/project/integrations/img/metrics_settings_button_v13_2.png +++ /dev/null diff --git a/doc/user/project/integrations/img/panel_context_menu_v13_0.png b/doc/user/project/integrations/img/panel_context_menu_v13_0.png Binary files differdeleted file mode 100644 index 2d7cb923981..00000000000 --- a/doc/user/project/integrations/img/panel_context_menu_v13_0.png +++ /dev/null diff --git a/doc/user/project/integrations/img/project_integrations_v13_3.png b/doc/user/project/integrations/img/project_integrations_v13_3.png Binary files differnew file mode 100644 index 00000000000..9c925d32441 --- /dev/null +++ b/doc/user/project/integrations/img/project_integrations_v13_3.png diff --git a/doc/user/project/integrations/img/project_services.png b/doc/user/project/integrations/img/project_services.png Binary files differdeleted file mode 100644 index 5fed38a349c..00000000000 --- a/doc/user/project/integrations/img/project_services.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_add_metric.png b/doc/user/project/integrations/img/prometheus_add_metric.png Binary files differdeleted file mode 100644 index 9afeb535123..00000000000 --- a/doc/user/project/integrations/img/prometheus_add_metric.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_alert.png b/doc/user/project/integrations/img/prometheus_alert.png Binary files differdeleted file mode 100644 index ffa1008ff51..00000000000 --- a/doc/user/project/integrations/img/prometheus_alert.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_cluster_health_embed_v12_9.png b/doc/user/project/integrations/img/prometheus_cluster_health_embed_v12_9.png Binary files differdeleted file mode 100644 index c669467757f..00000000000 --- a/doc/user/project/integrations/img/prometheus_cluster_health_embed_v12_9.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png Binary files differdeleted file mode 100644 index 5cba6fa9038..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type_v12_8.png b/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type_v12_8.png Binary files differdeleted file mode 100644 index 8c5663fef12..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type_v12_8.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_bar_chart_panel_type_v12.10.png b/doc/user/project/integrations/img/prometheus_dashboard_bar_chart_panel_type_v12.10.png Binary files differdeleted file mode 100644 index 593e31477f4..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_bar_chart_panel_type_v12.10.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_column_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_column_panel_type.png Binary files differdeleted file mode 100644 index 985f2b04ef3..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_column_panel_type.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_edit_metric_link_v_12_9.png b/doc/user/project/integrations/img/prometheus_dashboard_edit_metric_link_v_12_9.png Binary files differdeleted file mode 100644 index b66b1a9f39b..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_edit_metric_link_v_12_9.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png b/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png Binary files differdeleted file mode 100644 index 467deb86881..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_environments_v12_8.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_label_variable_shorthand.png b/doc/user/project/integrations/img/prometheus_dashboard_label_variable_shorthand.png Binary files differdeleted file mode 100644 index 15111a97464..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_label_variable_shorthand.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_label_variables.png b/doc/user/project/integrations/img/prometheus_dashboard_label_variables.png Binary files differdeleted file mode 100644 index 9b94d0c6afa..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_label_variables.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_repeated_label.png b/doc/user/project/integrations/img/prometheus_dashboard_repeated_label.png Binary files differdeleted file mode 100644 index d43a890f0fa..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_repeated_label.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png b/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png Binary files differdeleted file mode 100644 index 2f0309ce664..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png Binary files differdeleted file mode 100644 index 2d7dfb27b49..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_stacked_column_panel_type_v12_8.png b/doc/user/project/integrations/img/prometheus_dashboard_stacked_column_panel_type_v12_8.png Binary files differdeleted file mode 100644 index ba67509bcf3..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_stacked_column_panel_type_v12_8.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard_yaml_validation_v13_1.png b/doc/user/project/integrations/img/prometheus_dashboard_yaml_validation_v13_1.png Binary files differdeleted file mode 100644 index 08d7d6603d2..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard_yaml_validation_v13_1.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v13_1.png b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v13_1.png Binary files differdeleted file mode 100644 index 56a0a508a1d..00000000000 --- a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v13_1.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_service_alerts.png b/doc/user/project/integrations/img/prometheus_service_alerts.png Binary files differdeleted file mode 100644 index 609c5e5196c..00000000000 --- a/doc/user/project/integrations/img/prometheus_service_alerts.png +++ /dev/null diff --git a/doc/user/project/integrations/img/related_links_v13_1.png b/doc/user/project/integrations/img/related_links_v13_1.png Binary files differdeleted file mode 100644 index 4dc141f0e7f..00000000000 --- a/doc/user/project/integrations/img/related_links_v13_1.png +++ /dev/null diff --git a/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png b/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png Binary files differdeleted file mode 100644 index 6cabe4193bd..00000000000 --- a/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png +++ /dev/null diff --git a/doc/user/project/integrations/img/select_query_variables_v12_5.png b/doc/user/project/integrations/img/select_query_variables_v12_5.png Binary files differdeleted file mode 100644 index 23503577327..00000000000 --- a/doc/user/project/integrations/img/select_query_variables_v12_5.png +++ /dev/null diff --git a/doc/user/project/integrations/img/view_embedded_metrics_v12_10.png b/doc/user/project/integrations/img/view_embedded_metrics_v12_10.png Binary files differdeleted file mode 100644 index 95bb148ba71..00000000000 --- a/doc/user/project/integrations/img/view_embedded_metrics_v12_10.png +++ /dev/null diff --git a/doc/user/project/integrations/img/webex_teams_configuration.png b/doc/user/project/integrations/img/webex_teams_configuration.png Binary files differindex 66993e0887d..493b3ea50a0 100644 --- a/doc/user/project/integrations/img/webex_teams_configuration.png +++ b/doc/user/project/integrations/img/webex_teams_configuration.png diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 75565dd2750..0a1db5da61d 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Project integrations You can find the available integrations under your project's diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 2d807d4302b..f2e769dcfc0 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Irker IRC Gateway GitLab provides a way to push update messages to an Irker server. When diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 541c65041ad..f11cd4d9539 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,36 +1,39 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # GitLab Jira integration -GitLab Issues are a powerful tool for discussing ideas and planning and tracking work. -However, many organizations have been using Jira for these purposes and have -extensive data and business processes built into it. +If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficent. + +This page is about the GitLab Jira integration, which is available in every GitLab project by default, allowing you to connect it to any Jira instance, whether Cloud or self-managed. To compare features with the complementary Jira Development Panel integration, see [Jira integrations](jira_integrations.md). -While you can always migrate content and process from Jira to GitLab Issues, -you can also opt to continue using Jira and use it together with GitLab through -our integration. +After you set up this integration, you can cross-reference activity in the GitLab project with any of your projects in Jira. This includes the ability to close or transition Jira issues when work is completed in GitLab. -For a video demonstration of integration with Jira, watch [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ). +Features include: -Once you integrate your GitLab project with your Jira instance, you can automatically -detect and cross-reference activity between the GitLab project and any of your projects -in Jira. This includes the ability to close or transition Jira issues when the work -is completed in GitLab. +- **Mention a Jira issue ID** in a commit message or MR (merge request) and + - GitLab links to the Jira issue. + - The Jira issue adds a comment with details and a link back to the activity in GitLab. +- **Mention that a commit or MR resolves or closes a specific Jira issue** and when it's merged to the default branch: + - GitLab's MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they will close. + - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. +- **View a list of Jira issues directly in GitLab** **(PREMIUM)** -Here's how the integration responds when you take the following actions in GitLab: +For additional features, you can install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). This enables you to: -- **Mention a Jira issue ID** in a commit message or MR (merge request). - - GitLab hyperlinks to the Jira issue. - - The Jira issue adds an issue link to the commit/MR in GitLab. - - The Jira issue adds a comment reflecting the comment made in GitLab, the comment author, and a link to the commit/MR in GitLab, unless this commenting to Jira is [disabled](#disabling-comments-on-jira-issues). -- **Mention that a commit or MR 'closes', 'resolves', or 'fixes' a Jira issue ID**. When the commit is made on the project's default branch (usually master) or the change is merged to the default branch: - - GitLab's merge request page displays a note that it "Closed" the Jira issue, with a link to the issue. (Note: Before the merge, an MR will display that it "Closes" the Jira issue.) - - The Jira issue shows the activity and the Jira issue is closed, or otherwise transitioned. +- In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. +- Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. -You can also use [Jira's Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) -directly from GitLab, as covered in the article -[How and why to integrate GitLab with Jira](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-jira/how-to/2017/04/25). +See the [feature comparison](jira_integrations.md#feature-comparison) for more details. ## Configuration +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). + Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab project can interact with _all_ Jira projects in that instance, once configured. Therefore, you will not have to explicitly associate @@ -68,7 +71,7 @@ Select **Enable integration**. Select a **Trigger** action. This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, should link the Jira issue back to that source commit/MR and transition the Jira issue, if indicated. -To include a comment on the Jira issue when the above referene is made in GitLab, check **Enable comments**. +To include a comment on the Jira issue when the above reference is made in GitLab, check **Enable comments**. Enter the further details on the page as described in the following table. @@ -80,7 +83,9 @@ Enter the further details on the page as described in the following table. | `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | | `Transition ID` | Required for closing Jira issues via commits or merge requests. This is the ID of a transition in Jira that moves issues to a desired state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. | -To enable users to view Jira issues inside GitLab, select **Enable Jira issues** and enter a project key. **(PREMIUM)** +To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** + +You can only display issues from a single Jira project within a given GitLab project. CAUTION: **Caution:** If you enable Jira issues with the setting above, all users that have access to this GitLab project will be able to view all issues from the specified Jira project. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index c7157b6bd0e..14999734c00 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Creating an API token in Jira Cloud An API token is needed when integrating with Jira Cloud, follow the steps diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md new file mode 100644 index 00000000000..90cd9bf3acb --- /dev/null +++ b/doc/user/project/integrations/jira_integrations.md @@ -0,0 +1,35 @@ +--- +stage: Create +group: Ecosystem +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 +--- + +# Jira integrations + +## Introduction + +GitLab Issues are a tool for discussing ideas and planning and tracking work. However, your organization may already use Jira for these purposes, with +extensive, established data and business processes they rely on. + +Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using GitLab's Jira integrations. + +## Integrations + +The following Jira integrations allow different types of cross-referencing between GitLab activity and Jira issues, with additional features: + +- [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud. +- [**Jira development panel integration**](../../../integration/jira_development_panel.md) **(PREMIUM)** - This connects all GitLab projects under a specified group or personal namespace. + - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). + - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration). + +### Feature comparison + +| Capability | Jira integration | Jira Development Panel integration | +|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| Mention of Jira issue ID in GitLab is automatically linked to that issue | Yes | No | +| Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel | +| Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab. | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | +| Mention of Jira issue ID in GitLab branch names is reflected in Jira issue | No | Yes, in the issue’s Development panel | +| Record Jira time tracking info against an issue | No | Yes. Time can be specified via Jira Smart Commits. | +| Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | +| Display a list of Jira issues | Yes **(PREMIUM)** | No | diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index c8278a0f083..38098d7d15b 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Creating a username and password for Jira Server We need to create a user in Jira which will have access to all projects that diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 67d60984c22..c12a969ca3c 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Mattermost Notifications Service The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab. diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 6a202c9a130..5e08767d3f0 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Mattermost slash commands > Introduced in GitLab 8.14 @@ -42,9 +48,9 @@ the administrator console.  -1. Click **Custom integrations** and set **Enable Custom Slash Commands**, - **Enable custom integrations to override usernames**, and **Override - custom integrations to override profile picture icons** to true +1. Click **Integration Management** and set **Enable Custom Slash Commands**, + **Enable integrations to override usernames**, and **Enable + integrations to override profile picture icons** to true  diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 611ae1a01af..b2a2f1c3e7b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Microsoft Teams service ## On Microsoft Teams diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index b06ccda8287..4567d345336 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Mock CI Service **NB: This service is only listed if you are in a development environment!** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 79c55e2d140..f179cd6b98e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Integrations Integrations allow you to integrate GitLab with other applications. They @@ -12,7 +18,7 @@ You can find the available integrations under your project's There are more than 20 integrations to integrate with. Click on the one that you want to configure. - + ## Integrations listing @@ -69,10 +75,18 @@ The number of branches or tags supported can be changed via ## Service templates -Service templates are a way to set predefined values for an integration across +Service templates are a way to set predefined values for a project integration across all new projects on the instance. -Read more about [Service templates in this document](services_templates.md). +Read more about [Service templates](services_templates.md). + +## Project integration management + +Project integraton management lets you control integration settings across all projects +of an instance. On the project level, administrators you can choose whether to inherit the +instance configuraton or provide custom settings. + +Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). ## Troubleshooting integrations diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index f1567208a8f..a19b819c823 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -88,7 +88,7 @@ service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). 1. Navigate to the [Integrations page](overview.md#accessing-integrations) at - **{settings}** **Settings > Integrations**. + **Settings > Integrations**. 1. Click the **Prometheus** service. 1. For **API URL**, provide the domain name or IP address of your server, such as `http://prometheus.example.com/` or `http://192.0.2.1/`. @@ -121,7 +121,8 @@ one of them will be used: [Prometheus manual configuration](#manual-configuration-of-prometheus) and a [managed Prometheus on Kubernetes](#managed-prometheus-on-kubernetes), the manual configuration takes precedence and is used to run queries from - [dashboards](../../../operations/metrics/dashboards/index.md#defining-custom-dashboards-per-project) and [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). + [custom dashboards](../../../operations/metrics/dashboards/index.md) and + [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). - If you have managed Prometheus applications installed on Kubernetes clusters at **different** levels (project, group, instance), the order of precedence is described in [Cluster precedence](../../instance/clusters/index.md#cluster-precedence). diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 911493cdae9..e278c7eb664 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -4,7 +4,7 @@ group: APM 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 --- -# Monitoring AWS Resources +# Monitoring AWS resources > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index c92ddf38ad2..2a85dd9b79b 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Redmine Service 1. To enable the Redmine integration in a project, navigate to the diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index bc2bdde2f64..688643a85a7 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Service templates Using a service template, GitLab administrators can provide default values for configuring integrations at the project level. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 6c5dc787c5e..03ff5f845b6 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Slack Notifications Service The Slack Notifications Service allows your GitLab project to send events @@ -19,7 +25,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). 1. Open your project's page, and navigate to your project's [Integrations page](overview.md#accessing-integrations) at - **{settings}** **Settings > Integrations**. + **Settings > Integrations**. 1. Select the **Slack notifications** integration to configure it. 1. Click **Enable integration**. 1. In **Trigger**, select the checkboxes for each type of GitLab event to send to Slack as a diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index d25a367bd1f..7c2413fce81 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Slack slash commands **(CORE ONLY)** > Introduced in GitLab 8.15. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 98dc6f298d5..c4959a8711b 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Unify Circuit service The Unify Circuit service sends notifications from GitLab to the conversation for which the webhook was created. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 10735e33746..39daa14407f 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # Webex Teams service You can configure GitLab to send notifications to a Webex Teams space. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 5a0ca03a646..800eb1d3359 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,23 +1,10 @@ -# Webhooks +--- +stage: Create +group: Ecosystem +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 +--- -> **Note:** -> Starting from GitLab 8.5: -> -> - the `repository` key is deprecated in favor of the `project` key -> - the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key -> - the `project.http_url` key is deprecated in favor of the `project.git_http_url` key -> -> **Note:** -> Starting from GitLab 11.1, the logs of webhooks are automatically removed after -> one month. -> -> **Note:** -> Starting from GitLab 11.2: -> -> - The `description` field for issues, merge requests, comments, and wiki pages -> is rewritten so that simple Markdown image references (like -> ``) have their target URL changed to an absolute URL. See -> [image URL rewriting](#image-url-rewriting) for more details. +# Webhooks Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events @@ -48,7 +35,25 @@ Navigate to the webhooks page by going to your project's **Settings ➔ Webhooks**. NOTE: **Note:** -On GitLab.com, the [maximum number of webhooks](../../../user/gitlab_com/index.md#maximum-number-of-webhooks) per project, and per group, is limited. +On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. + +## Version history + +Starting from GitLab 8.5: + +- the `repository` key is deprecated in favor of the `project` key +- the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key +- the `project.http_url` key is deprecated in favor of the `project.git_http_url` key + +Starting from GitLab 11.1, the logs of webhooks are automatically removed after +one month. + +Starting from GitLab 11.2: + +- The `description` field for issues, merge requests, comments, and wiki pages + is rewritten so that simple Markdown image references (like + ``) have their target URL changed to an absolute URL. See + [image URL rewriting](#image-url-rewriting) for more details. ## Use-cases @@ -722,7 +727,7 @@ X-Gitlab-Event: Note Hook "type": "ProjectLabel", "group_id": null } - ], + ] } } ``` @@ -1296,6 +1301,58 @@ 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 deployment is finished/failed/canceled. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Deployment Hook +``` + +**Request Body**: + +```json +{ + "object_kind": "deployment", + "status": "success", + "deployable_id": 796, + "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", + "environment": "staging", + "project": { + "id": 30, + "name": "test-deployment-webhooks", + "description": "", + "web_url": "http://10.126.0.2:3000/root/test-deployment-webhooks", + "avatar_url": null, + "git_ssh_url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", + "git_http_url": "http://10.126.0.2:3000/root/test-deployment-webhooks.git", + "namespace": "Administrator", + "visibility_level": 0, + "path_with_namespace": "root/test-deployment-webhooks", + "default_branch": "master", + "ci_config_path": "", + "homepage": "http://10.126.0.2:3000/root/test-deployment-webhooks", + "url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", + "ssh_url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", + "http_url": "http://10.126.0.2:3000/root/test-deployment-webhooks.git" + }, + "short_sha": "279484c0", + "user": { + "name": "Administrator", + "username": "root", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "email": "admin@example.com" + }, + "user_url": "http://10.126.0.2:3000/root", + "commit_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/commit/279484c09fbe69ededfced8c1bb6e6d24616b468", + "commit_title": "Add new file" +} +``` + +Note that `deployable_id` is the ID of the CI job. + ## Image URL rewriting From GitLab 11.2, simple image references are rewritten to use an absolute URL @@ -1339,7 +1396,8 @@ On this page, you can see data that GitLab sends (request headers and body) and From this page, you can repeat delivery with the same data by clicking `Resend Request` button. -> **Note:** If URL or secret token of the webhook were updated, data will be delivered to the new address. +NOTE: **Note:** +If URL or secret token of the webhook were updated, data will be delivered to the new address. ### Receiving duplicate or multiple webhook requests triggered by one event diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index e067ab6071e..d243ffc7a37 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Ecosystem +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 +--- + # YouTrack Service JetBrains [YouTrack](https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Documentation.html) is a web-based issue tracking and project management platform. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 1831563332f..7be58ce4ecb 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -69,7 +69,7 @@ multiple issue boards within the same project. ## Use cases -There are many ways to use GitLab issue boards tailored to your own preferred workflow. +You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. ### Use cases for a single issue board @@ -324,8 +324,9 @@ As in other list types, click the trash icon to remove a list. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 -You can set Work In Progress (WIP) limits per issues list. When a limit is set, the list's header -shows the number of issues in the list and the soft limit of issues. +You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is +set, the list's header shows the number of issues in the list and the soft limit of issues. +You cannot set a WIP limit on the default lists (**Open** and **Closed**). Examples: @@ -337,7 +338,7 @@ Examples: To set a WIP limit for a list: 1. Navigate to a Project or Group board of which you're a member. -1. Click the Settings icon (**{settings}**) in a list's header. +1. Click the settings icon in a list's header. 1. Next to **Work In Progress Limit**, click **Edit**. 1. Enter the maximum number of issues. 1. Press <kbd>Enter</kbd> to save. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 602a6d79848..5bb8805159a 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -46,7 +46,8 @@ system note in the issue's comments. ## Indications of a confidential issue ->**Note:** If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), +NOTE: **Note:** +If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), you won't be able to see the confidential issues at all. There are a few things that visually separate a confidential issue from a diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 618506ea7ee..5e456c7986c 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,7 +1,8 @@ # Design Management > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. +> - Support for SVGs was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. ## Overview @@ -41,10 +42,9 @@ If the requirements are not met, the **Designs** tab displays a message to the u ## Supported files Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, -`gif`, `bmp`, `tiff` or `ico`. +`gif`, `bmp`, `tiff`, `ico`, or `svg`. -Support for [SVG files](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) -and [PDFs](https://gitlab.com/gitlab-org/gitlab/-/issues/32811) is planned for a future release. +Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. ## Limitations @@ -110,7 +110,7 @@ instead of directly on the issue description. To upload Design images, drag files from your computer and drop them in the Design Management section, or click **upload** to select images from your file browser: - + [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, you can drag and drop designs onto the dedicated drop zone to upload them. @@ -197,11 +197,19 @@ Once selected, click the **Delete selected** button to confirm the deletion:  -**Note:** +NOTE: **Note:** Only the latest version of the designs can be deleted. Deleted designs are not permanently lost; they can be viewed by browsing previous versions. +## Reordering designs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. + +You can change the order of designs by dragging them to a new position: + + + ## Starting discussions on designs When a design is uploaded, you can start a discussion by clicking on @@ -268,21 +276,21 @@ This will be rendered as: ### Enable or disable design references **(CORE ONLY)** -Design reference parsing is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +Design reference parsing 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 for your instance. +can disable it for your instance. -To enable it: +To disable it: ```ruby -Feature.enable(:design_management_reference_filter_gfm_pipeline) +Feature.disable(:design_management_reference_filter_gfm_pipeline) ``` -To disable it: +To re-enable it: ```ruby -Feature.disable(:design_management_reference_filter_gfm_pipeline) +Feature.enable(:design_management_reference_filter_gfm_pipeline) ``` ## Design activity records diff --git a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png Binary files differindex d60f1234b6d..25a02eef406 100644 --- a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png +++ b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png diff --git a/doc/user/project/issues/img/design_management_upload_v13.2.png b/doc/user/project/issues/img/design_management_upload_v13.2.png Binary files differdeleted file mode 100644 index 1d4b10307fc..00000000000 --- a/doc/user/project/issues/img/design_management_upload_v13.2.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_management_upload_v13.3.png b/doc/user/project/issues/img/design_management_upload_v13.3.png Binary files differnew file mode 100644 index 00000000000..f7b3f79fb22 --- /dev/null +++ b/doc/user/project/issues/img/design_management_upload_v13.3.png diff --git a/doc/user/project/issues/img/design_management_v13_2.png b/doc/user/project/issues/img/design_management_v13_2.png Binary files differindex 0a6e2be17ab..6d7e03d6f20 100644 --- a/doc/user/project/issues/img/design_management_v13_2.png +++ b/doc/user/project/issues/img/design_management_v13_2.png diff --git a/doc/user/project/issues/img/designs_reordering_v13_3.gif b/doc/user/project/issues/img/designs_reordering_v13_3.gif Binary files differnew file mode 100644 index 00000000000..496eea532e2 --- /dev/null +++ b/doc/user/project/issues/img/designs_reordering_v13_3.gif diff --git a/doc/user/project/issues/img/epic_tree_health_status_v12_10.png b/doc/user/project/issues/img/epic_tree_health_status_v12_10.png Binary files differindex c6d0117b1c4..1a603656fd8 100644 --- a/doc/user/project/issues/img/epic_tree_health_status_v12_10.png +++ b/doc/user/project/issues/img/epic_tree_health_status_v12_10.png diff --git a/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png b/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png Binary files differindex bd9d1f7a77c..8791419b919 100644 --- a/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png +++ b/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png diff --git a/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png b/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png Binary files differindex 5cd005f0799..fc1fff321ba 100644 --- a/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png +++ b/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 9113f5344ba..a6911d183c1 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -109,6 +109,15 @@ Key actions for Issues include: On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md), and modify them if you have the necessary [permissions](../../permissions.md). +#### Real-time sidebar **(CORE ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. +> - It cannot be enabled or disabled per-project. +> - It's not recommended for production use. + +Assignees in the sidebar are updated in real time. This feature is **disabled by default**. +To enable, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). + ### Issues list  diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 7f236d04fb6..77c50f9178c 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -316,4 +316,4 @@ Read more how to [add or remove a zoom meeting](associate_zoom_meeting.md). > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. -If a status page application is associated with the project, you can use the `/publish` [quick action](../quick_actions.md) to publish the issue. Refer to [GitLab Status Page](../status_page/index.md) for more information. +If a status page application is associated with the project, you can use the `/publish` [quick action](../quick_actions.md) to publish the issue. Refer to [GitLab Status Page](../../../operations/incident_management/status_page.md) for more information. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index bcf2ab66978..0e0731528be 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -287,3 +287,7 @@ To add an issue to an [iteration](../../group/iterations/index.md): 1. In an issue sidebar, click **Edit** next to **Iteration**. A dropdown appears. 1. Click an iteration you'd like to associate this issue with. + +You can also use the `/iteration` +[quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) +in a comment or description field. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 445c28492df..954e3771722 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -14,32 +14,39 @@ and projects. The relationship only shows up in the UI if the user can see both issues. +When you try to close an issue that has open blockers, a warning is displayed. + +TIP: **Tip:** +To manage related issues through our API, see the [API documentation](../../../api/issue_links.md). + ## Adding a related issue > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2035) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) to warn when attempting to close an issue that is blocked by others in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. > When you try to close an issue with open blockers, you'll see a warning that you can dismiss. -You can relate one issue to another by clicking the related issues "+" button -in the header of the related issue block. Then, input the issue reference number -or paste in the full URL of the issue. +1. Relate one issue to another by clicking the related issues "+" button +in the header of the related issue block. + +1. Input the issue reference number or paste in the full URL of the issue. -Additionally, you can select whether the current issue relates to, blocks, or is blocked by the issues being entered. +1. Select whether the current issue relates to, blocks, or is blocked by the issues being entered. - +  -Issues of the same project can be specified just by the reference number. -Issues from a different project require additional information like the -group and the project name. For example: + Issues of the same project can be specified just by the reference number. + Issues from a different project require additional information like the + group and the project name. For example: -- same project: `#44` -- same group: `project#44` -- different group: `group/project#44` + - same project: `#44` + - same group: `project#44` + - different group: `group/project#44` -Valid references will be added to a temporary list that you can review. -When you have added all the related issues, click **Add** to submit. + Valid references will be added to a temporary list that you can review. -Once you have finished adding all related issues, you will be able to see +1. When you have added all the related issues, click **Add** to submit. + +When you have finished adding all related issues, you will be able to see them categorized so their relationships can be better understood visually.  @@ -47,11 +54,10 @@ them categorized so their relationships can be better understood visually. ## Removing a related issue In the related issues block, click the "x" icon on the right-side of each issue -token that you wish to remove. Due to the bi-directional relationship, it -will no longer appear in either issue. +token that you wish to remove. + +Due to the bi-directional relationship, it will no longer appear in either issue.  Please access our [permissions](../../permissions.md) page for more information. - -Additionally, you are also able to manage related issues through [our API](../../../api/issue_links.md). diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 9886ef91f16..0d02b89be7e 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -43,7 +43,7 @@ To assign a label to an issue, merge request or epic: click on them. You can search repeatedly and add more labels. 1. Click **X** or anywhere outside the label section and the labels are applied. -You can also assign a label with the [`/assign @username` quick action](quick_actions.md). +You can also assign a label with the [`/label ~label1 ~label2` quick action](quick_actions.md). ## Label management @@ -82,6 +82,9 @@ Once created, you can edit a label by clicking the pencil (**{pencil}**), or del a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button and selecting **Delete**. +CAUTION: **Caution:** +If you delete a label, it is permanently deleted. You will not be able to undo the deletion, and all references to the label will be removed from the system. + #### Promote a project label to a group label If you previously created a project label and now want to make it available for other diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index f90917d0a8b..60d247ccc19 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- 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 0579e3568da..26b3682990e 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts --- diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 6685c50c1ed..d65c005ee34 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 36acba032ff..3c697e22cf5 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -7,7 +7,8 @@ type: reference, howto # Code Quality -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. Ensuring your project's code stays simple, readable and easy to contribute to can be problematic. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your source code quality using GitLab Code Quality. @@ -66,12 +67,10 @@ For instance, consider the following workflow: ## Example configuration -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.11 and later versions. It -also requires the GitLab Runner 11.5 or later. For earlier versions, use the -[previous job definitions](#previous-job-definitions). - This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. +It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are using +GitLab 11.4 or ealier, you can view the deprecated job definitions in the +[documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). First, you need GitLab Runner configured: @@ -131,103 +130,65 @@ definition they will be able to execute privileged Docker commands on the Runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. -### Previous job definitions +### Disabling the code quality job -CAUTION: **Caution:** -Before GitLab 11.5, Code Quality job and artifact had to be named specifically to -automatically extract report data and show it in the merge request widget. While these -old job definitions are still maintained they have been deprecated and are no longer supported on GitLab 12.0 or higher. -You're advised to update your `.gitlab-ci.yml` configuration to reflect that change. +The `code_quality` job will not run if the `$CODE_QUALITY_DISABLED` environment +variable is present. Please refer to the environment variables [documentation](../../../ci/variables/README.md) +to learn more about how to define one. -For GitLab 11.5 and later, the job should look like: +To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom environment +variable. This can be done: -```yaml -code_quality: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') - - docker run - --env SOURCE_CODE="$PWD" - --volume "$PWD":/code - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/ci-cd/codequality:$SP_VERSION" /code - artifacts: - reports: - codequality: gl-code-quality-report.json -``` +- For the whole project, [in the project settings](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) + or [CI/CD configuration](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). +- For a single pipeline run: + + 1. Go to **CI/CD > Pipelines** + 1. Click **Run Pipeline** + 1. Add `CODE_QUALITY_DISABLED` as the variable key, with any value. + +### Using with merge request pipelines + +The configuration provided by the Code Quality template does not let the `code_quality` job +run on [pipelines for merge requests](../../../ci/merge_request_pipelines/index.md). -In GitLab 12.6, Code Quality switched to the -[new versioning scheme](https://gitlab.com/gitlab-org/ci-cd/codequality#versioning-and-release-cycle). -It's highly recommended to include the Code Quality template as shown in the -[example configuration](#example-configuration), which uses the new versioning scheme. -If not using the template, the `SP_VERSION` variable can be hardcoded to use the -new image versions: +If pipelines for merge requests is enabled, the `code_quality:rules` must be redefined. + +The template has these [`rules`](../../../ci/yaml/README.md#rules) for the `code quality` job: ```yaml code_quality: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - SP_VERSION: 0.85.6 - allow_failure: true - services: - - docker:stable-dind - script: - - docker run - --env SOURCE_CODE="$PWD" - --volume "$PWD":/code - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/ci-cd/codequality:$SP_VERSION" /code - artifacts: - reports: - codequality: gl-code-quality-report.json + rules: + - if: '$CODE_QUALITY_DISABLED' + when: never + - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' ``` -For GitLab 11.4 and earlier, the job should look like: +If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflowrules)) +might look like this example: ```yaml -code_quality: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') - - docker run - --env SOURCE_CODE="$PWD" - --volume "$PWD":/code - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/ci-cd/codequality:$SP_VERSION" /code - artifacts: - paths: [gl-code-quality-report.json] +job1: + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run job1 in merge request pipelines + - if: '$CI_COMMIT_BRANCH == "master"' # Run job1 in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` -Alternatively the job name could be `codeclimate` or `codequality` and the artifact -name could be `codeclimate.json`. These names have been deprecated with GitLab 11.0 -and may be removed in the next major release, GitLab 12.0. - -For GitLab 10.3 and earlier, the job should look like: +To make these work together, you will need to overwrite the code quality `rules` +so that they match your current `rules`. From the example above, it could look like: ```yaml -codequality: - image: docker:latest - variables: - DOCKER_DRIVER: overlay - services: - - docker:dind - script: - - docker pull codeclimate/codeclimate:0.69.0 - - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate:0.69.0 init - - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate:0.69.0 analyze -f json > codeclimate.json || true - artifacts: - paths: [codeclimate.json] +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + rules: + - if: '$CODE_QUALITY_DISABLED' + when: never + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run code quality job in merge request pipelines + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_TAG' # Run code quality job in pipelines for tags ``` ## Configuring jobs using variables diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 50d5decc2cc..0495c864335 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto description: "How to create Merge Requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' @@ -18,7 +21,7 @@ or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through- This document describes the several ways to create a merge request. When you start a new merge request, regardless of the method, -you'll be taken to the [**New Merge Request** page](#new-merge-request-page) +you are taken to the [**New Merge Request** page](#new-merge-request-page) to fill it with information about the merge request. If you push a new branch to GitLab, also regardless of the method, @@ -29,8 +32,8 @@ button and start a merge request from there. On the **New Merge Request** page, start by filling in the title and description for the merge request. If there are already -commits on the branch, the title will be prefilled with the first -line of the first commit message, and the description will be +commits on the branch, the title is prefilled with the first +line of the first commit message, and the description is prefilled with any additional lines in the commit message. The title is the only field that is mandatory in all cases. @@ -61,18 +64,18 @@ You can also see the **Create merge request** button in the top-right of the: - **Repository > Files** page. - **Merge Requests** page. -In this case, GitLab will use the most recent branch you pushed +In this case, GitLab uses the most recent branch you pushed changes to as the source branch, and the default branch in the current project as the target. ## New merge request by adding, editing, and uploading a file When you choose to edit, add, or upload a file through the GitLab UI, -at the end of the file you'll see the option to add the **Commit message**, +at the end of the file you see the option to add the **Commit message**, to select the **Target branch** of that commit, and the checkbox to **Start new a merge request with these changes**. -Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you'll see these same options. +Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you see these same options. Once you have added, edited, or uploaded the file: @@ -81,23 +84,23 @@ Once you have added, edited, or uploaded the file: 1. Keep the checkbox checked to start a new merge request straightaway, or, uncheck it to add more changes to that branch before starting the merge request. 1. Click **Commit changes**. -If you chose to start a merge request, you'll be taken to the +If you chose to start a merge request, you are taken to the [**New Merge Request** page](#new-merge-request-page), from which you can fill it in with information and submit the merge request. -The merge request will target the default branch of the repository. +The merge request targets the default branch of the repository. If you want to change it, you can do it later by editing the merge request. ## New merge request from a new branch created through the UI To quickly start working on files through the GitLab UI, navigate to your project's **Repository > Branches** and click -**New branch**. A new branch will be created and you can start +**New branch**. A new branch is created and you can start editing files. Once committed and pushed, you can click on the [**Create Merge Request**](#create-merge-request-button) button to open the [**New Merge Request** page](#new-merge-request-page). -A new merge request will be started using the current branch as the source, +A new merge request is started using the current branch as the source, and the default branch in the current project as the target. ## New merge request from your local environment @@ -123,7 +126,7 @@ Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-usin git push origin my-new-branch ``` -In the output, GitLab will prompt you with a direct link for creating +In the output, GitLab prompts you with a direct link for creating a merge request: ```shell @@ -133,7 +136,7 @@ remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?mer ``` Copy that link and paste it in your browser, and the [**New Merge Request page**](#new-merge-request-page) -will be displayed. +is displayed. There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. @@ -183,10 +186,10 @@ available in GitLab.com. You can create a new merge request by sending an email to a user-specific email address. The address can be obtained on the merge requests page by clicking on -a **Email a new merge request to this project** button. The subject will be +a **Email a new merge request to this project** button. The subject is used as the source branch name for the new merge request and the target branch -will be the default branch for the project. The message body (if not empty) -will be used as the merge request description. You need +is the default branch for the project. The message body (if not empty) +is used as the merge request description. You need ["Reply by email"](../../../administration/reply_by_email.md) enabled to use this feature. If it's not enabled to your instance, you may ask your GitLab administrator to do so. @@ -207,16 +210,16 @@ or contacts to continue working._ You can add commits to the merge request being created by adding patches as attachments to the email. All attachments with a filename -ending in `.patch` will be considered patches and they will be processed +ending in `.patch` are considered patches and they are processed ordered by name. The combined size of the patches can be 2MB. -If the source branch from the subject does not exist, it will be +If the source branch from the subject does not exist, it is created from the repository's HEAD or the specified target branch to apply the patches. The target branch can be specified using the [`/target_branch` quick action](../quick_actions.md). If the source -branch already exists, the patches will be applied on top of it. +branch already exists, the patches are applied on top of it. ## Reviewing and managing Merge Requests diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 619a6d04577..60f81159394 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -45,8 +45,9 @@ This template requires: - Use [Pipelines for Merge Requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) - [Pipelines for Merged Results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results) enabled in the project settings. +- A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. -## Configure Fast RSpec Failure +## Configuring Fast RSpec Failure We'll use the following plain RSpec configuration as a starting point. It installs all the project gems and executes `rspec`, on merge request pipelines only. @@ -69,6 +70,16 @@ include: - template: Verify/FailFast.gitlab-ci.yml ``` +To customize the job, specific options may be set to override the template. For example, to override the default Docker image: + +```yaml +include: + - template: Verify/FailFast.gitlab-ci.yml + +rspec-rails-modified-path-specs: + image: custom-docker-image-with-ruby +``` + ### Example test loads For illustrative purposes, let's say our Rails app spec suite consists of 100 specs per model for ten models. diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 2d59e535ce1..b021fa6f336 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 9ac0f3ee42e..c7cabf3c73b 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: index, reference description: "Getting started with Merge Requests." --- diff --git a/doc/user/project/merge_requests/img/accessibility_mr_widget_v13_0.png b/doc/user/project/merge_requests/img/accessibility_mr_widget_v13_0.png Binary files differindex c52bf9964f1..4ada7e25b65 100644 --- a/doc/user/project/merge_requests/img/accessibility_mr_widget_v13_0.png +++ b/doc/user/project/merge_requests/img/accessibility_mr_widget_v13_0.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v12_7.png b/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v12_7.png Binary files differdeleted file mode 100644 index 164779a8450..00000000000 --- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v12_7.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png b/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png Binary files differnew file mode 100644 index 00000000000..306bf57354d --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png Binary files differdeleted file mode 100644 index 24c8c8f8c11..00000000000 --- a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/browser_performance_testing.png b/doc/user/project/merge_requests/img/browser_performance_testing.png Binary files differindex c270462f7a8..016abb89f7c 100644 --- a/doc/user/project/merge_requests/img/browser_performance_testing.png +++ b/doc/user/project/merge_requests/img/browser_performance_testing.png diff --git a/doc/user/project/merge_requests/img/code_quality.png b/doc/user/project/merge_requests/img/code_quality.png Binary files differindex 3c6c92baad2..1e7dd64baff 100644 --- a/doc/user/project/merge_requests/img/code_quality.png +++ b/doc/user/project/merge_requests/img/code_quality.png diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png Binary files differindex 5b9844bf02f..cff5acb98ef 100644 --- a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png +++ b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png Binary files differindex beb12c581d6..f7968772500 100644 --- a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png +++ b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png diff --git a/doc/user/project/merge_requests/img/load_performance_testing.png b/doc/user/project/merge_requests/img/load_performance_testing.png Binary files differindex 3a58e9c28d4..d5623867ee7 100644 --- a/doc/user/project/merge_requests/img/load_performance_testing.png +++ b/doc/user/project/merge_requests/img/load_performance_testing.png diff --git a/doc/user/project/merge_requests/img/merge_request.png b/doc/user/project/merge_requests/img/merge_request.png Binary files differdeleted file mode 100644 index c0a62bbaba0..00000000000 --- a/doc/user/project/merge_requests/img/merge_request.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/multiline-comment-highlighted.png b/doc/user/project/merge_requests/img/multiline-comment-highlighted.png Binary files differnew file mode 100644 index 00000000000..1bdcc37e274 --- /dev/null +++ b/doc/user/project/merge_requests/img/multiline-comment-highlighted.png diff --git a/doc/user/project/merge_requests/img/multiline-comment-saved.png b/doc/user/project/merge_requests/img/multiline-comment-saved.png Binary files differnew file mode 100644 index 00000000000..cceab36e62b --- /dev/null +++ b/doc/user/project/merge_requests/img/multiline-comment-saved.png diff --git a/doc/user/project/merge_requests/img/squash_squashed_commit.png b/doc/user/project/merge_requests/img/squash_squashed_commit.png Binary files differindex 458361c5490..7def5339d8a 100644 --- a/doc/user/project/merge_requests/img/squash_squashed_commit.png +++ b/doc/user/project/merge_requests/img/squash_squashed_commit.png diff --git a/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png b/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png Binary files differindex 353cf458243..61cf72e7bf9 100644 --- a/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png +++ b/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f68fc7d7b45..a9ee9d8e507 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,17 +1,16 @@ --- +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/#designated-technical-writers type: index, reference --- # Merge requests -Merge requests allow you to visualize and collaborate on the proposed changes -to source code that exist as commits on a given Git branch. +A Merge Request (**MR**) is a _request_ to _merge_ one branch into another. - - -A Merge Request (**MR**) is the basis of GitLab as a code collaboration and version -control platform. It's exactly as the name implies: a _request_ to _merge_ one -branch into another. +Use merge requests to visualize and collaborate on proposed changes +to source code. ## Use cases diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 3239269109d..97f4f202ab3 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -141,7 +141,8 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) as a [Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance-premium). -The latest Load Performance artifact available is always used. +The latest Load Performance artifact available is always used, using the +summary values from the test. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 4e0e609e59e..407fc5db425 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference, concepts --- @@ -10,16 +13,16 @@ process, as it clearly communicates the ability to merge the change. ## Optional Approvals **(CORE ONLY)** -> Introduced in [GitLab Core 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/27426). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. -Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Core. -This provides a consistent mechanism for reviewers to provide approval, and makes it easy for +Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Core and higher tiers. +This provides a consistent mechanism for reviewers to approve merge requests, and makes it easy for maintainers to know when a change is ready to merge. Approvals in Core are optional and do not prevent a merge request from being merged when there is no approval. ## Required Approvals **(STARTER)** -> Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only). +> [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. Available in [GitLab Starter](https://about.gitlab.com/pricing/) and higher tiers. Required approvals enable enforced code review by requiring specified people to approve a merge request before it can be merged. @@ -30,8 +33,8 @@ Required approvals enable multiple use cases: - Specifying reviewers for a given proposed code change, as well as a minimum number of reviewers, through [Approval rules](#approval-rules). - Specifying categories of reviewers, such as backend, frontend, quality assurance, - database, etc., for all proposed code changes. -- Automatically designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers), + database, and so on, for all proposed code changes. +- Designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers), determined by the files changed in a merge request. - [Requiring approval from a security team](#security-approvals-in-merge-requests-ultimate) before merging code that could introduce a vulnerability.**(ULTIMATE)** @@ -47,14 +50,14 @@ be merged, and optionally which users should do the approving. Approvals can be If no approval rules are defined, any user can approve a merge request, though the default minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings). -Approval rules define how many approvals a merge request must receive before it can -be merged, and optionally which users should do the approving. Approvals can be defined: +You can opt to define one single rule to approve a merge request among the available rules +or choose more than one. Single approval rules are available in GitLab Starter and higher tiers, +while [multiple approval rules](#multiple-approval-rules-premium) are available in +[GitLab Premium](https://about.gitlab.com/pricing/) and above. -- [As project defaults](#adding--editing-a-default-approval-rule). -- [Per merge request](#editing--overriding-approval-rules-per-merge-request). - -If no approval rules are defined, any user can approve a merge request, though the default -minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings). +NOTE: **Note:** +On GitLab.com, you can add a group as an approver if you're a member of that group or the +group is public. #### Eligible Approvers @@ -81,6 +84,11 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) are enabled on the project settings. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3, +when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, +indicating who has engaged in the merge request review. Authors and reviewers can also easily identify who they should reach out +to if they have any questions or inputs about the content of the merge request. + ##### Implicit Approvers If the number of required approvals is greater than the number of assigned approvers, @@ -116,7 +124,7 @@ Alternatively, you can **require** To add or edit the default merge request approval rule: -1. Navigate to your project's **{settings}** **Settings > General** and expand **Merge request approvals**. +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. @@ -151,6 +159,15 @@ settings. When creating or editing a merge request, find the **Approval rules** section, then follow the same steps as [Adding / editing a default approval rule](#adding--editing-a-default-approval-rule). +#### Set up an optional approval rule + +MR approvals can be configured to be optional. +This can be useful if you're working on a team where approvals are appreciated, but not required. + +To configure an approval to be optional, set the number of required approvals in **No. approvals required** to `0`. + +You can also set an optional approval rule through the [Merge requests approvals API](../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`. + #### Multiple approval rules **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. @@ -171,7 +188,7 @@ a rule is already defined. When an [eligible approver](#eligible-approvers) approves a merge request, it will reduce the number of approvals left for all rules that the approver belongs to. - + #### Scoped to Protected Branch **(PREMIUM)** @@ -221,7 +238,7 @@ or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). ### Merge request approvals project settings The project settings for Merge request approvals are found by going to -**{settings}** **Settings > General** and expanding **Merge request approvals**. +**Settings > General** and expanding **Merge request approvals**. #### Prevent overriding default approvals diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 65f3cb1e0d5..bca9df9ae2b 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- 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 7d90c9f3cd7..5151b28361a 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -84,7 +84,7 @@ merge-request-pipeline-job: ``` You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#differences-between-rules-and-onlyexcept) +or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#prevent-duplicate-pipelines) for details on avoiding two pipelines for a single merge request. ### Skipped pipelines diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 265e47dd8bb..b6c7ad0ce75 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 75d9702ceb9..bc4fee749e8 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 91ca48f85d5..4e821145339 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: index, reference --- @@ -132,7 +135,7 @@ specific commit page.  ->**Tip:** +TIP: **Tip:** You can append `?w=1` while on the diffs page of a merge request to ignore any whitespace changes. @@ -141,10 +144,53 @@ whitespace changes. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. GitLab provides a way of leaving comments in any part of the file being changed -in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. +in a Merge Request. To do so, click the **{comment}** **comment** icon in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line.  +### Commenting on multiple lines + +> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. +> - It's deployed behind a feature flag, enabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221268) on GitLab 13.3. +> - It's enabled on GitLab.com. +> - It can be disabled or enabled per-project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments-core-only). **(CORE ONLY)** + +GitLab provides a way to select which lines of code a comment refers to. After starting a comment +a dropdown selector is shown to select the first line that this comment refers to. +The last line is the line that the comment icon was initially clicked on. + +New comments default to single line comments by having the first and last lines +the same. Selecting a different starting line turns this into a multiline comment. + + + +Once a multiline comment is saved the lines of code pertaining to that comment are listed directly +above it. + + + +### Enable or disable multiline comments **(CORE ONLY)** + +The multiline comments feature is under development but ready for production use. +It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it for your instance. + +To disable it: + +```ruby +Feature.disable(:multiline_comments) +``` + +To enable it: + +```ruby +Feature.enable(:multiline_comments) +``` + ## Pipeline status in merge requests widgets If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, @@ -235,7 +281,7 @@ Merge Request again. Here are some tips that will help you be more efficient with merge requests in the command line. -> **Note:** +NOTE: **Note:** This section might move in its own document in the future. ### Checkout merge requests locally diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 79eec059293..7f752b2cc39 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- @@ -24,6 +27,10 @@ Into a single commit on merge:  +NOTE: **Note:** +The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in +**Project Settings > General > Merge requests > Merge method > Fast-forward merge**. + The squashed commit's commit message will be either: - Taken from the first multi-line commit message in the merge. @@ -36,9 +43,6 @@ It can be customized before merging a merge request.  -NOTE: **Note:** -The squashed commit in this example is followed by a merge commit, as the merge method for this example repository uses a merge commit. - Squashing also works with the fast-forward merge strategy, see [squashing and fast-forward merge](#squash-and-fast-forward-merge) for more details. ## Use cases @@ -88,10 +92,12 @@ squashing can itself be considered equivalent to rebasing. ## Squash Commits Options > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. -> - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-squash-commit-options-core-only). **(CORE ONLY)** +> - It was deployed behind a feature flag, disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) on GitLab 13.3. +> - It's enabled on GitLab.com. +> - It can be enabled per project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-squash-commit-options-core-only). **(CORE ONLY)** With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. @@ -116,10 +122,10 @@ squash commits locally through the command line and force-push to their remote b ### Enable or disable Squash Commit Options **(CORE ONLY)** -Squash Commit Options is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +Squash Commit Options 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 enable it for your instance. Squash Commit Options can be enabled or disabled per-project. +can opt to disable it. To enable it: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 12194423a00..6751dde155c 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -5,9 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Test Coverage Visualization +# Test Coverage Visualization **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. +> - It's deployed behind a feature flag, disabled by default. +> - It's disabled on GitLab.com. +> - It can be enabled or disabled per-project. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-feature). **(CORE ONLY)** With the help of [GitLab CI/CD](../../../ci/README.md), you can collect the test coverage information of your favorite testing or coverage-analysis tool, and visualize @@ -50,6 +54,10 @@ from any job in any stage in the pipeline. The coverage will be displayed for ea Hovering over the coverage bar will provide further information, such as the number of times the line was checked by tests. +NOTE: **Note:** +The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that +the `filename` of a `class` element contains the full path relative to the project root. + ## Example test coverage configuration The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/) @@ -69,13 +77,25 @@ test: ## Enabling the feature This feature comes with the `:coverage_report_view` feature flag disabled by -default. This feature is disabled due to some performance issues with very large +default. It is disabled on GitLab.com. This feature is disabled due to some performance issues with very large data sets. When [the performance issue](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) -is resolved, the feature will be enabled by default. +is resolved, the feature will be enabled by default. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it for your instance. Test coverage visualization can be enabled or disabled per-project. -To enable this feature, ask a GitLab administrator with Rails console access to -run the following command: +To enable it: ```ruby +# Instance-wide Feature.enable(:coverage_report_view) +# or by project +Feature.enable(:coverage_report_view, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:coverage_report_view) +# or by project +Feature.disable(:coverage_report_view, Project.find(<project id>)) ``` diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index ece5e7868dc..d1833318a85 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, concepts --- diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index e28ba1d2d5f..0c8bba831a9 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -35,7 +35,7 @@ Burndown Charts are generally used for tracking and analyzing the completion of a milestone. Therefore, their use cases are tied to the [use you are assigning your milestone to](index.md). -To exemplify, suppose you lead a team of developers in a large company, +For example, suppose you lead a team of developers in a large company, and you follow this workflow: - Your company set the goal for the quarter to deliver 10 new features for your app diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 3e4b94473bc..0feed7dbf40 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -1,274 +1,5 @@ --- -stage: Monitor -group: Health -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 +redirect_to: '../../../operations/incident_management/index.md' --- -# Alert Management - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. - -Alert Management enables developers to easily discover and view the alerts -generated by their application. By surfacing alert information where the code is -being developed, efficiency and awareness can be increased. - -## Enable Alert Management - -NOTE: **Note:** -You will need at least Maintainer [permissions](../../permissions.md) to enable the Alert Management feature. - -There are several ways to accept alerts into your GitLab project, as outlined below. -Enabling any of these methods will allow the Alerts list to display. After configuring -alerts, visit **{cloud-gear}** **Operations > Alerts** in your project's sidebar -to [view the list](#alert-management-list) of alerts. - -### Opsgenie integration **(PREMIUM)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -A new way of monitoring Alerts via a GitLab integration is with -[Opsgenie](https://www.atlassian.com/software/opsgenie). - -NOTE: **Note:** -If you enable the Opsgenie integration, you cannot have other GitLab alert services, -such as [Generic Alerts](../integrations/generic_alerts.md) or -Prometheus alerts, active at the same time. - -To enable Opsgenie integration: - -1. Sign in as a user with Maintainer or Owner [permissions](../../permissions.md). -1. Navigate to **{cloud-gear}** **Operations > Alerts**. -1. In the **Integrations** select box, select Opsgenie. -1. Click the **Active** toggle. -1. In the **API URL**, enter the base URL for your Opsgenie integration, such - as `https://app.opsgenie.com/alert/list`. -1. Click **Save changes**. - -After enabling the integration, navigate to the Alerts list page at **{cloud-gear}** **Operations > Alerts**, and click **View alerts in Opsgenie**. - -### Enable a Generic Alerts endpoint - -GitLab provides the Generic Alerts endpoint so you can accept alerts from a third-party -alerts service. See the -[instructions for toggling generic alerts](../integrations/generic_alerts.md#setting-up-generic-alerts) -to add this option. After configuring the endpoint, the -[Alerts list](#alert-management-list) is enabled. - -To populate the alerts with data, see [Customizing the payload](../integrations/generic_alerts.md#customizing-the-payload) for requests to the alerts endpoint. - -### Enable GitLab-managed Prometheus alerts - -You can install the GitLab-managed Prometheus application on your Kubernetes -cluster. For more information, see -[Managed Prometheus on Kubernetes](../integrations/prometheus.md#managed-prometheus-on-kubernetes). -When GitLab-managed Prometheus is installed, the [Alerts list](#alert-management-list) -is also enabled. - -To populate the alerts with data, see -[GitLab-Managed Prometheus instances](../../../operations/metrics/alerts.md#managed-prometheus-instances). - -### Enable external Prometheus alerts - -You can configure an externally-managed Prometheus instance to send alerts -to GitLab. To set up this configuration, see the [configuring Prometheus](../../../operations/metrics/alerts.md#external-prometheus-instances) documentation. Activating the external Prometheus -configuration also enables the [Alerts list](#alert-management-list). - -To populate the alerts with data, see -[External Prometheus instances](../../../operations/metrics/alerts.md#external-prometheus-instances). - -## Alert Management severity - -Each level of alert contains a uniquely shaped and color-coded icon to help -you identify the severity of a particular alert. These severity icons help you -immediately identify which alerts you should prioritize investigating: - - - -Alerts contain one of the following icons: - -| Severity | Icon | Color (hexadecimal) | -|---|---|---| -| Critical | **{severity-critical}** | `#8b2615` | -| High | **{severity-high}** | `#c0341d` | -| Medium | **{severity-medium}** | `#fca429` | -| Low | **{severity-low}** | `#fdbc60` | -| Info | **{severity-info}** | `#418cd8` | -| Unknown | **{severity-unknown}** | `#bababa` | - -## Alert Management list - -NOTE: **Note:** -You will need at least Developer [permissions](../../permissions.md) to view the Alert Management list. - -You can find the Alert Management list at **{cloud-gear}** **Operations > Alerts** in your project's sidebar. -Each alert contains the following metrics: - - - -- **Severity** - The current importance of a alert and how much attention it should receive. -- **Start time** - How long ago the alert fired. This field uses the standard GitLab pattern of `X time ago`, but is supported by a granular date/time tooltip depending on the user's locale. -- **Alert description** - The description of the alert, which attempts to capture the most meaningful data. -- **Event count** - The number of times that an alert has fired. -- **Issue** - A link to the incident issue that has been created for the alert. -- **Status** - The [current status](#alert-management-statuses) of the alert. - -### Alert Management list sorting - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1. - -The Alert Management list displays alerts sorted by start time, but you can -change the sort order by clicking the headers in the Alert Management list. - -To see if a column is sortable, point your mouse at the header. Sortable columns -display an arrow next to the column name, as shown in this example: - - - -### Searching alerts - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213884) in GitLab 13.1. - -The alert list supports a simple free text search. - - - -This search filters on the following fields: - -- Title -- Description -- Monitoring tool -- Service - -### Alert Management statuses - -Each alert contains a status dropdown to indicate which alerts need investigation. -Standard alert statuses include `triggered`, `acknowledged`, and `resolved`: - -- **Triggered**: No one has begun investigation. -- **Acknowledged**: Someone is actively investigating the problem. -- **Resolved**: No further work is required. - -## Alert Management details - -NOTE: **Note:** -You will need at least Developer [permissions](../../permissions.md) to view Alert Management details. - -Navigate to the Alert Management detail view by visiting the [Alert Management list](#alert-management-list) and selecting an Alert from the list. - - - - - -### Update an Alert's status - -The Alert Management detail view enables you to update the Alert Status. -See [Alert Management statuses](#alert-management-statuses) for more details. - -### Create an Issue from an Alert - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1. - -The Alert Management detail view enables you to create an issue with a -description automatically populated from an alert. To create the issue, -click the **Create Issue** button. You can then view the issue from the -alert by clicking the **View Issue** button. - -Closing a GitLab issue associated with an alert changes the alert's status to Resolved. -See [Alert Management statuses](#alert-management-statuses) for more details about statuses. - -### Update an Alert's assignee - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. - -The Alert Management detail view allows users to update the Alert assignee. - -In large teams, where there is shared ownership of an alert, it can be difficult -to track who is investigating and working on it. The Alert Management detail view -enables you to update the Alert assignee: - -NOTE: **Note:** -GitLab currently only supports a single assignee per alert. - -1. To display the list of current alerts, click - **{cloud-gear}** **Operations > Alerts**: - -  - -1. Select your desired alert to display its **Alert Management Details View**: - -  - -1. If the right sidebar is not expanded, click - **{angle-double-right}** **Expand sidebar** to expand it. -1. In the right sidebar, locate the **Assignee** and click **Edit**. From the - dropdown menu, select each user you want to assign to the alert. GitLab creates - a [To-Do list item](../../todos.md) for each user. - -  - -To remove an assignee, click **Edit** next to the **Assignee** dropdown menu and -deselect the user from the list of assignees, or click **Unassigned**. - -### Alert system notes - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. - -When you take action on an alert, this is logged as a system note, -which is visible in the Alert Details view. This gives you a linear -timeline of the alert's investigation and assignment history. - -The following actions will result in a system note: - -- [Updating the status of an alert](#update-an-alerts-status) -- [Creating an issue based on an alert](#create-an-issue-from-an-alert) -- [Assignment of an alert to a user](#update-an-alerts-assignee) - - - -### View an Alert's metrics data - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2. - -To view the metrics for an alert: - - 1. Sign in as a user with Developer or higher [permissions](../../permissions.md). - 1. Navigate to **{cloud-gear}** **Operations > Alerts**. - 1. Click the alert you want to view. - 1. Below the title of the alert, click the **Metrics** tab. - - - -For GitLab-managed Prometheus instances, metrics data is automatically available -for the alert, making it easy to see surrounding behavior. See -[Managed Prometheus instances](../../../operations/metrics/alerts.md#managed-prometheus-instances) -for information on setting up alerts. - -For externally-managed Prometheus instances, you can configure your alerting rules to -display a chart in the alert. See -[Embedding metrics based on alerts in incident issues](../../../operations/metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues) -for information on how to appropriately configure your alerting rules. See -[External Prometheus instances](../../../operations/metrics/alerts.md#external-prometheus-instances) -for information on setting up alerts for your self-managed Prometheus instance. - -## Use cases for assigning alerts - -Consider a team formed by different sections of monitoring, collaborating on a -single application. After an alert surfaces, it's extremely important to -route the alert to the team members who can address and resolve the alert. - -Assigning Alerts to multiple assignees eases collaboration and delegation. All -assignees are shown in your team's work-flows, and all assignees receive -notifications, simplifying communication and ownership of the alert. - -After completing their portion of investigating or fixing the alert, users can -unassign their account from the alert when their role is complete. -The [alerts status](#alert-management-statuses) can be updated to -reflect if the alert has been resolved. - -### Slack Notifications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216326) in GitLab 13.1. - -You can be alerted via a Slack message when a new alert has been received. - -See the [Slack Notifications Service docs](../integrations/slack.md) for information on how to set this up. +This document was moved to [another location](../../../operations/incident_management/index.md). diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md index f30ce5024d6..2640f2cf98f 100644 --- a/doc/user/project/operations/dashboard_settings.md +++ b/doc/user/project/operations/dashboard_settings.md @@ -1,52 +1,5 @@ --- -stage: Monitor -group: APM -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 +redirect_to: '../../../operations/metrics/dashboards/settings.md' --- -# Metrics dashboard settings - -You can configure your [Monitoring dashboard](../integrations/prometheus.md) to -display the time zone of your choice, and the links of your choice. - -To configure these settings you must have Manage Project -Operations [permissions](../../permissions.md). - -## Change the dashboard time zone - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214370) in GitLab 13.1. - -By default, your monitoring dashboard displays dates and times in your local -time zone, but you can display dates and times in UTC format. To change the -time zone: - -1. Sign in as a user with Manage Project Operations [permissions](../../permissions.md). -1. Navigate to **{settings}** **Settings > Operations**, and scroll to - **Metrics Dashboard**. -1. In the **Dashboard timezone** select box, select *User's local timezone* - or *UTC*: - -  -1. Click **Save changes**. - -## Link to an external dashboard - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/57171) in GitLab 12.0. - -You can add a button on your monitoring dashboard that links directly to your -existing external dashboards: - -1. Sign in as a user with Manage Project Operations [permissions](../../permissions.md). -1. Navigate to **{settings}** **Settings > Operations**, and scroll to - **Metrics Dashboard**. -1. In **External dashboard URL**, provide the URL to your external dashboard: - -  - -1. Click **Save changes**. - -GitLab displays a **View full dashboard** button in the top right corner of your -[monitoring dashboard](../../../ci/environments/index.md#monitoring-environments) -which opens the URL you provided: - - +This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index a7a16de90e0..3c00c4a6c41 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -1,95 +1,5 @@ --- -stage: Monitor -group: Health -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 +redirect_to: '../../../operations/error_tracking.md' --- -# Error Tracking - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/169) in GitLab 11.8. - -Error tracking allows developers to easily discover and view the errors that their application may be generating. By surfacing error information where the code is being developed, efficiency and awareness can be increased. - -## Sentry error tracking - -[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab. - -### Deploying Sentry - -You may sign up to the cloud hosted <https://sentry.io>, deploy your own [on-premise instance](https://docs.sentry.io/server/installation/) or use GitLab to [install Sentry to a Kubernetes cluster](../../clusters/applications.md#install-sentry-using-gitlab-cicd). - -### Enabling Sentry - -NOTE: **Note:** -You will need at least Maintainer [permissions](../../permissions.md) to enable the Sentry integration. - -GitLab provides an easy way to connect Sentry to your project: - -1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. -1. [Create](https://docs.sentry.io/guides/integrate-frontend/create-new-project/) a new Sentry project. For each GitLab project that you want to integrate, we recommend that you create a new Sentry project. -1. [Find or generate](https://docs.sentry.io/api/auth/) a Sentry auth token for your Sentry project. - Make sure to give the token at least the following scopes: `event:read` and `project:read`. -1. Navigate to your project’s **Settings > Operations**. -1. Ensure that the **Active** checkbox is set. -1. In the **Sentry API URL** field, enter your Sentry hostname. For example, enter `https://sentry.example.com` if this is the address at which your Sentry instance is available. For the SaaS version of Sentry, the hostname will be `https://sentry.io`. -1. In the **Auth Token** field, enter the token you previously generated. -1. Click the **Connect** button to test the connection to Sentry and populate the **Project** dropdown. -1. From the **Project** dropdown, choose a Sentry project to link to your GitLab project. -1. Click **Save changes** for the changes to take effect. -1. You can now visit **Operations > Error Tracking** in your project's sidebar to [view a list](#error-tracking-list) of Sentry errors. - -### Enabling GitLab issues links - -You may also want to enable Sentry's GitLab integration by following the steps in the [Sentry documentation](https://docs.sentry.io/workflow/integrations/global-integrations/#gitlab) - -## Error Tracking List - -NOTE: **Note:** -You will need at least Reporter [permissions](../../permissions.md) to view the Error Tracking list. - -You can find the Error Tracking list at **Operations > Error Tracking** in your project's sidebar. -Here, you can filter errors by title or by status (one of Ignored , Resolved, or Unresolved) and sort in descending order by Frequency, First Seen, or Last Seen. By default, the error list is ordered by Last Seen and filtered to Unresolved errors. - - - -## Error Details - -From error list, users can navigate to the error details page by clicking the title of any error. - -This page has: - -- A link to the Sentry issue. -- A link to the GitLab commit if the Sentry [release ID/version](https://docs.sentry.io/workflow/releases/?platform=javascript#configure-sdk) on the Sentry Issue's first release matches a commit SHA in your GitLab hosted project. -- Other details about the issue, including a full stack trace. -- In [GitLab 12.7 and newer](https://gitlab.com/gitlab-org/gitlab/-/issues/36246), language and urgency are displayed. - -By default, a **Create issue** button is displayed: - - - -If you create a GitLab issue from the error, the **Create issue** button will change to a **View issue** button and a link to the GitLab issue will surface within the error detail section: - - - -## Taking Action on errors - -You can take action on Sentry Errors from within the GitLab UI. - -### Ignoring errors - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39665) in GitLab 12.7. - -From within the [Error Details](#error-details) page you can ignore a Sentry error by simply clicking the **Ignore** button near the top of the page. - -Ignoring an error will prevent it from appearing in the [Error Tracking List](#error-tracking-list), and will silence notifications that were set up within Sentry. - -### Resolving errors - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39825) in GitLab 12.7. - -From within the [Error Details](#error-details) page you can resolve a Sentry error by -clicking the **Resolve** button near the top of the page. - -Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue will be closed. - -If another event occurs, the error reverts to unresolved. +This document was moved to [another location](../../../operations/error_tracking.md). diff --git a/doc/user/project/operations/img/alert_detail_full_v13_1.png b/doc/user/project/operations/img/alert_detail_full_v13_1.png Binary files differdeleted file mode 100644 index 18a6f4fb67b..00000000000 --- a/doc/user/project/operations/img/alert_detail_full_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_detail_metrics_v13_2.png b/doc/user/project/operations/img/alert_detail_metrics_v13_2.png Binary files differdeleted file mode 100644 index 84d83365ea8..00000000000 --- a/doc/user/project/operations/img/alert_detail_metrics_v13_2.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_detail_overview_v13_1.png b/doc/user/project/operations/img/alert_detail_overview_v13_1.png Binary files differdeleted file mode 100644 index 10c945d3810..00000000000 --- a/doc/user/project/operations/img/alert_detail_overview_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_detail_system_notes_v13_1.png b/doc/user/project/operations/img/alert_detail_system_notes_v13_1.png Binary files differdeleted file mode 100644 index 2a6d0320a54..00000000000 --- a/doc/user/project/operations/img/alert_detail_system_notes_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_details_assignees_v13_1.png b/doc/user/project/operations/img/alert_details_assignees_v13_1.png Binary files differdeleted file mode 100644 index dab4eac384a..00000000000 --- a/doc/user/project/operations/img/alert_details_assignees_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_list_assignees_v13_1.png b/doc/user/project/operations/img/alert_list_assignees_v13_1.png Binary files differdeleted file mode 100644 index db1e0d8dcb7..00000000000 --- a/doc/user/project/operations/img/alert_list_assignees_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_list_search_v13_1.png b/doc/user/project/operations/img/alert_list_search_v13_1.png Binary files differdeleted file mode 100644 index ba993fe530b..00000000000 --- a/doc/user/project/operations/img/alert_list_search_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_list_sort_v13_1.png b/doc/user/project/operations/img/alert_list_sort_v13_1.png Binary files differdeleted file mode 100644 index 8e06c3478f7..00000000000 --- a/doc/user/project/operations/img/alert_list_sort_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_management_severity_v13_0.png b/doc/user/project/operations/img/alert_management_severity_v13_0.png Binary files differdeleted file mode 100644 index f996d6e88f4..00000000000 --- a/doc/user/project/operations/img/alert_management_severity_v13_0.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_todo_assignees_v13_1.png b/doc/user/project/operations/img/alert_todo_assignees_v13_1.png Binary files differdeleted file mode 100644 index 637f8be5d25..00000000000 --- a/doc/user/project/operations/img/alert_todo_assignees_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/dashboard_external_link_v13_1.png b/doc/user/project/operations/img/dashboard_external_link_v13_1.png Binary files differdeleted file mode 100644 index 3e8d792c53e..00000000000 --- a/doc/user/project/operations/img/dashboard_external_link_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/dashboard_local_timezone_v13_1.png b/doc/user/project/operations/img/dashboard_local_timezone_v13_1.png Binary files differdeleted file mode 100644 index 8d45607a940..00000000000 --- a/doc/user/project/operations/img/dashboard_local_timezone_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_v12_7.png b/doc/user/project/operations/img/error_details_v12_7.png Binary files differdeleted file mode 100644 index 1c7ace35e2a..00000000000 --- a/doc/user/project/operations/img/error_details_v12_7.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_with_issue_v12_8.png b/doc/user/project/operations/img/error_details_with_issue_v12_8.png Binary files differdeleted file mode 100644 index 0536861b070..00000000000 --- a/doc/user/project/operations/img/error_details_with_issue_v12_8.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_tracking_list_v12_6.png b/doc/user/project/operations/img/error_tracking_list_v12_6.png Binary files differdeleted file mode 100644 index b99c83c14d3..00000000000 --- a/doc/user/project/operations/img/error_tracking_list_v12_6.png +++ /dev/null diff --git a/doc/user/project/operations/img/external_dashboard_link.png b/doc/user/project/operations/img/external_dashboard_link.png Binary files differdeleted file mode 100644 index 82c5e05e467..00000000000 --- a/doc/user/project/operations/img/external_dashboard_link.png +++ /dev/null diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md index ff609a3720e..2640f2cf98f 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -1,5 +1,5 @@ --- -redirect_to: 'dashboard_settings.md' +redirect_to: '../../../operations/metrics/dashboards/settings.md' --- -This document was moved to [another location](dashboard_settings.md). +This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 6e48afad96a..735d27ec04d 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -32,7 +32,7 @@ for the most popular hosting services: - [Amazon](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) -- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) +- [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) - [cPanel](https://documentation.cpanel.net/display/84Docs/Edit+DNS+Zone) - [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) - [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) 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 0425ca56285..8e8f75be82d 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,5 +1,5 @@ --- -last_updated: 2019-07-04 +last_updated: 2020-07-25 type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' stage: Release @@ -129,11 +129,11 @@ They require: | ------------------------------------------------- | ---------- | ---------------------- | | `example.com` | A | `35.185.44.232` | | `_gitlab-pages-verification-code.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -|--------------------------------------------+--------------------------------------------| +|---------------------------------------------------+------------+------------------------| | `www.example.com` | CNAME | `namespace.gitlab.io` | | `_gitlab-pages-verification-code.www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -If you're using CloudFlare, check +If you're using Cloudflare, check [Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare). > **Notes**: @@ -236,7 +236,9 @@ To secure your custom domain with GitLab Pages you can opt by: - Manually adding SSL/TLS certificates to GitLab Pages websites by following the steps below. -### Requirements +### Manual addition of SSL/TLS certificates + +You can use any certificate satisfying the following requirements: - A GitLab Pages website up and running accessible via a custom domain. - **A PEM certificate**: it is the certificate generated by the CA, @@ -245,12 +247,15 @@ To secure your custom domain with GitLab Pages you can opt by: the part of the encryption keychain that identifies the CA. Usually it's combined with the PEM certificate, but there are some cases in which you need to add them manually. - [CloudFlare certs](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) + [Cloudflare certs](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) are one of these cases. - **A private key**, it's an encrypted key which validates your PEM against your domain. -### Steps +NOTE: **Note:** +[Cloudflare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), for example, meet these requirements. + +#### Steps - To add the certificate at the time you add a new domain, go to your project's **Settings > Pages > New Domain**, add the domain name and the certificate. @@ -288,7 +293,7 @@ To enable this setting: 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. NOTE: **Note:** -If you use CloudFlare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [CloudFlare CDN directions](https://support.cloudflare.com/hc/en-us/articles/200170416-End-to-end-HTTPS-with-Cloudflare-Part-3-SSL-options#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). +If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://support.cloudflare.com/hc/en-us/articles/200170416-End-to-end-HTTPS-with-Cloudflare-Part-3-SSL-options#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). <!-- ## Troubleshooting diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index e307b807aaa..f30361e6669 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -56,7 +56,7 @@ reiterating the importance of HTTPS. ## Issuing Certificates -GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by +GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis) format, issued by [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) or as [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) for public websites for security reasons and to ensure that browsers trust your site's certificate. @@ -72,7 +72,7 @@ to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), which issues certificates trusted by most of browsers, it's open source, and free to use. See [GitLab Pages integration with Let's Encrypt](../custom_domains_ssl_tls_certification/lets_encrypt_integration.md) to enable HTTPS on your custom domain. -Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), +Similarly popular are [certificates issued by Cloudflare](https://www.cloudflare.com/ssl/), which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/). Their certs are valid up to 15 years. See the tutorial on -[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). +[how to add a Cloudflare Certificate to your GitLab Pages website](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 7278c734b07..cabaf734d77 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -160,8 +160,9 @@ When it succeeds, go to **Settings > Pages** to view the URL where your site is now available. If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file -with [any of the available settings](../../../../ci/yaml/README.md). You can check -your CI syntax with the [GitLab CI/CD Lint Tool](../../../../ci/yaml/README.md#validate-the-gitlab-ciyml). +with [any of the available settings](../../../../ci/yaml/README.md). See +[Validate the `.gitlab-ci.yml`](../../../../ci/yaml/README.md#validate-the-gitlab-ciyml) +for instructions on validating your YAML file with the Lint tool included with GitLab. The following topics show other examples of other options you can add to your CI/CD file. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index c0bdd4b7f0b..949a6c16c1b 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -13,7 +13,7 @@ according to your intended website's URL. ## GitLab Pages default domain names ->**Note:** +NOTE: **Note:** If you use your own GitLab instance to deploy your site with GitLab Pages, check with your sysadmin what's your Pages wildcard domain. This guide is valid for any GitLab instance, diff --git a/doc/user/project/pages/img/change_path_v12_10.png b/doc/user/project/pages/img/change_path_v12_10.png Binary files differindex 9b5c17f1dda..b6ed011c6d9 100644 --- a/doc/user/project/pages/img/change_path_v12_10.png +++ b/doc/user/project/pages/img/change_path_v12_10.png 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 differindex 84dd9fe2e0f..a0c25ba1642 100644 --- a/doc/user/project/pages/img/choose_ci_template_v13_1.png +++ b/doc/user/project/pages/img/choose_ci_template_v13_1.png diff --git a/doc/user/project/pages/img/pages_project_templates_v13_1.png b/doc/user/project/pages/img/pages_project_templates_v13_1.png Binary files differindex 3f6d1ecd786..d67a82f0623 100644 --- a/doc/user/project/pages/img/pages_project_templates_v13_1.png +++ b/doc/user/project/pages/img/pages_project_templates_v13_1.png diff --git a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png Binary files differindex 1bc7bcd253b..84aa2e571c7 100644 --- a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png +++ b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index b116c28d94b..eff80a4c9bd 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -59,7 +59,6 @@ To update a GitLab Pages website: | [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. | | [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. | | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | -| [CloudFlare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. | Learn more and see examples: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index d0baf57f169..3d0cb1bf3a5 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference, howto --- diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index bb5bca39398..5dd2a72c91e 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference, howto --- diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index ca658c06647..db9e2f270e0 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,5 +1,8 @@ --- -type: reference +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/#designated-technical-writers" +type: reference, howto --- # Push Options diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index def05bf94e4..518cf472b50 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -44,7 +44,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(CORE)** Also, mark both as related. **(STARTER)** | | `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | | `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | -| `/iteration *iteration:iteration` | ✓ | | | Set iteration ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)) **(STARTER)** | +| `/iteration *iteration:"iteration name"` | ✓ | | | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). **(STARTER)** | | `/label ~label1 ~label2` | ✓ | ✓ | ✓ | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | | `/lock` | ✓ | ✓ | | Lock the thread. | | `/merge` | | ✓ | | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md), etc. | @@ -52,7 +52,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/move <path/to/project>` | ✓ | | | Move this issue to another project. | | `/parent_epic <epic>` | | | ✓ | 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)). **(ULTIMATE)** | | `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | -| `/publish` | ✓ | | | Publish issue to an associated [Status Page](status_page/index.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | +| `/publish` | ✓ | | | 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)) **(ULTIMATE)** | | `/reassign @user1 @user2` | ✓ | ✓ | | Change assignee. **(STARTER)** | | `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace existing labels with those specified. | | `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | @@ -60,7 +60,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/remove_due_date` | ✓ | | | Remove due date. | | `/remove_epic` | ✓ | | | Remove from epic. **(PREMIUM)** | | `/remove_estimate` | ✓ | ✓ | | Remove time estimate. | -| `/remove_iteration` | ✓ | | | Remove iteration ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)) **(STARTER)** | +| `/remove_iteration` | ✓ | | | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)) **(STARTER)** | | `/remove_milestone` | ✓ | ✓ | | Remove milestone. | | `/remove_parent_epic` | | | ✓ | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). **(ULTIMATE)** | | `/remove_time_spent` | ✓ | ✓ | | Remove time spent. | diff --git a/doc/user/project/releases/img/deploy_freeze_v13_2.png b/doc/user/project/releases/img/deploy_freeze_v13_2.png Binary files differnew file mode 100644 index 00000000000..27d3a6044a1 --- /dev/null +++ b/doc/user/project/releases/img/deploy_freeze_v13_2.png diff --git a/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png b/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png Binary files differindex efe48058d9a..b9eb18e9279 100644 --- a/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png +++ b/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png diff --git a/doc/user/project/releases/img/release_with_milestone_v12_9.png b/doc/user/project/releases/img/release_with_milestone_v12_9.png Binary files differindex c828e36114a..4a904a854f1 100644 --- a/doc/user/project/releases/img/release_with_milestone_v12_9.png +++ b/doc/user/project/releases/img/release_with_milestone_v12_9.png diff --git a/doc/user/project/releases/img/releases_count_v13_2.png b/doc/user/project/releases/img/releases_count_v13_2.png Binary files differindex 1c0493326d1..d2d77e016bc 100644 --- a/doc/user/project/releases/img/releases_count_v13_2.png +++ b/doc/user/project/releases/img/releases_count_v13_2.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 258601574ca..20880d0c4fa 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -53,25 +53,26 @@ Read more about [Release permissions](../../../user/permissions.md#project-membe You can create a release in the user interface, or by using the [Releases API](../../../api/releases/index.md#create-a-release). -We recommend using the API to add release notes as one of the last steps in your CI/CD release pipeline. +We recommend using the API to create releases as one of the last steps in your +CI/CD pipeline. To create a new release through the GitLab UI: -1. Navigate to **Project overview > Releases** and click the **New release** button. +1. Navigate to **Project overview > Releases** and click the **New release** + button. 1. In the [**Tag name**](#tag-name) box, enter a name. -1. In the **Create from** list, select the branch or enter a tag or commit SHA. -1. In the **Message** box, enter a message associated with the tag. -1. Optionally, in the [**Release notes**](#release-notes-description) - field, enter the release's description. You can use Markdown and drag and drop files to this field. - - If you leave this field empty, only a tag will be created. - - If you populate it, both a tag and a release will be created. -1. Click **Create tag**. -If you created a release, you can view it at **Project overview > Releases**. -If you created a tag, you can view it at **Repository > Tags**. + NOTE: **Note:** + Creating a release based on an existing tag using the user + interface is not yet supported. However, this is possible using the + [Releases API](../../../api/releases/index.md#create-a-release). -You can now edit the release to [add milestones](#associate-milestones-with-a-release) -and [release assets](#release-assets). +1. In the **Create from** list, select a branch, tag, or commit SHA to use when + creating the new tag. +1. Optionally, fill out any additional information about the release, such as its + [title](#title), [milestones](#associate-milestones-with-a-release), + [release notes](#release-notes-description), or [assets links](#links). +1. Click **Create release**. ### Schedule a future release @@ -176,7 +177,7 @@ Prevent unintended production releases during a period of time you specify by setting a [*deploy freeze* period](../../../ci/environments/deployment_safety.md). Deploy freezes help reduce uncertainty and risk when automating deployments. -Use the [Freeze Periods API](../../../api/freeze_periods.md) to set a `freeze_start` and a `freeze_end`, which +A maintainer can set a deploy freeze window in the user interface or by using the [Freeze Periods API](../../../api/freeze_periods.md) to set a `freeze_start` and a `freeze_end`, which are defined as [crontab](https://crontab.guru/) entries. If the job that's executing is within a freeze period, GitLab CI/CD creates an environment @@ -193,6 +194,22 @@ deploy_to_production: - if: $CI_DEPLOY_FREEZE == null ``` +To set a deploy freeze window in the UI, complete these steps: + +1. Sign in to GitLab as a user with project Maintainer [permissions](../../permissions.md). +1. Navigate to **Project overview**. +1. In the left navigation menu, navigate to **Settings > CI / CD**. +1. Scroll to **Deploy freezes**. +1. Click **Expand** to see the deploy freeze table. +1. Click **Add deploy freeze** to open the deploy freeze modal. +1. Enter the start time, end time, and timezone of the desired deploy freeze period. +1. Click **Add deploy freeze** in the modal. + + + +CAUTION: **Caution:** +To edit or delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). + If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the complete overlapping period. @@ -202,6 +219,21 @@ For more information, see [Deployment safety](../../../ci/environments/deploymen The following fields are available when you create or edit a release. +### Title + +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. + +NOTE: **Note:** +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 [Permissions](../../permissions.md#project-members-permissions) page for +more information about permissions. + ### Tag name The release tag name should include the release version. GitLab uses [Semantic Versioning](https://semver.org/) @@ -241,12 +273,12 @@ as pre-built packages, compliance/security evidence, or container images. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. The assets associated with a release are accessible through a permanent URL. -GitLab will always redirect this URL to the actual asset +GitLab always redirects this URL to the actual asset location, so even if the assets move to a different location, you can continue to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link). Each asset has a name, a URL of the *actual* asset location, and optionally, a -`filepath` parameter, which, if you specify it, will create a URL pointing +`filepath` parameter, which, if you specify it, creates a URL pointing to the asset for the Release. The format of the URL is: ```plaintext @@ -270,7 +302,7 @@ This asset has a direct link of: https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 ``` -The physical location of the asset can change at any time and the direct link will remain unchanged. +The physical location of the asset can change at any time and the direct link remains unchanged. ### Source code @@ -372,7 +404,7 @@ When a release is created, release evidence is automatically collected. To initi Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. -### Include report artifacts as release evidence **(ULTIMATE ONLY)** +### Include report artifacts as release evidence **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index f94ca7ac106..54979d1c4ce 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: concepts, howto --- @@ -63,7 +66,7 @@ By default, when you create a new project in GitLab, the initial branch is calle For self-managed instances, a GitLab administrator can customize the initial branch name to something else. This way, every new project created from then on will start from the custom branch name rather than `master`. To do so: -1. Go to the **{admin}** **Admin Area > Settings > Repository** and expand **Default initial +1. Go to the **Admin Area > Settings > Repository** and expand **Default initial branch name**. 1. Change the default initial branch to a custom name of your choice. 1. **Save Changes**. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index ac10071e578..99319efbb7f 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,4 +1,7 @@ --- +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/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- @@ -37,6 +40,7 @@ the `app/controllers/admin/deploy_keys_controller.rb` file. Using a fuzzy search, we start by typing letters that get us closer to the file. -**Tip:** To narrow down your search, include `/` in your search terms. +TIP: **Tip:** +To narrow down your search, include `/` in your search terms.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 75a84e36169..e90f0a7354c 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- @@ -26,7 +29,7 @@ Forking a project is, in most cases, a two-step process. NOTE: **Note:** The project path must be unique within the namespace. -  +  The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. @@ -50,7 +53,7 @@ Without mirroring, to work locally you'll have to use `git pull` to update your with the upstream project, then push the changes back to your fork to update it. CAUTION: **Caution:** -With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommend. +With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommended. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -61,7 +64,7 @@ When you are ready to send your code back to the upstream project, choose your forked project's branch. For **Target branch**, choose the original project's branch. NOTE: **Note:** -When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing private code of the forked project. +When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing the private code of the forked project.  diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index e63b57747ef..6636463722e 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto description: "Documentation on Git file blame." --- diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index b7375602a78..6cc05d2192f 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 68b5c2651e1..5526828c969 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: concepts, howto --- diff --git a/doc/user/project/repository/img/file_finder_find_button_v12_10.png b/doc/user/project/repository/img/file_finder_find_button_v12_10.png Binary files differindex e93db946005..51545f63fde 100644 --- a/doc/user/project/repository/img/file_finder_find_button_v12_10.png +++ b/doc/user/project/repository/img/file_finder_find_button_v12_10.png diff --git a/doc/user/project/repository/img/file_finder_find_file_v12_10.png b/doc/user/project/repository/img/file_finder_find_file_v12_10.png Binary files differindex 1404ccc6d0b..e54de6a3065 100644 --- a/doc/user/project/repository/img/file_finder_find_file_v12_10.png +++ b/doc/user/project/repository/img/file_finder_find_file_v12_10.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace.png b/doc/user/project/repository/img/forking_workflow_choose_namespace.png Binary files differdeleted file mode 100644 index eb023ca85f2..00000000000 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png Binary files differnew file mode 100644 index 00000000000..4843cc671ae --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 0cf375009a0..a57806cf3ff 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts, howto --- diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 1948b12aacd..fe432e0d553 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,3 +1,9 @@ +--- +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/#designated-technical-writers" +type: reference +--- # Jupyter Notebook Files > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index baad5027703..8247f69c61a 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -32,15 +32,24 @@ Git LFS files can only be removed by an Administrator using a ## Purge files from repository history -To make cloning your project faster, rewrite branches and tags to remove unwanted files. +To reduce the size of your repository in GitLab, you must remove references to large files from branches, tags, and +other internal references (refs) that are automatically created by GitLab. These refs include: + +- `refs/merge-requests/*` for merge requests. +- `refs/pipelines/*` for + [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). +- `refs/environments/*` for environments. + +Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to +download all the advertised refs. 1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) using a supported package manager or from source. -1. Clone a fresh copy of the repository using `--bare`: +1. Clone a fresh copy of the repository using `--bare` and `--mirror`: ```shell - git clone --bare https://example.gitlab.com/my/project.git + git clone --bare --mirror https://example.gitlab.com/my/project.git ``` 1. Using `git filter-repo`, purge any files from the history of your repository. @@ -74,16 +83,10 @@ To make cloning your project faster, rewrite branches and tags to remove unwante [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) for more examples and the complete documentation. -1. Running `git filter-repo` removes all remotes. To restore the remote for your project, run: - - ```shell - git remote add origin https://example.gitlab.com/<namespace>/<project_name>.git - ``` - 1. Force push your changes to overwrite all branches on GitLab: ```shell - git push origin --force --all + git push origin --force 'refs/heads/*' ``` [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must @@ -92,13 +95,21 @@ To make cloning your project faster, rewrite branches and tags to remove unwante 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: ```shell - git push origin --force --tags + git push origin --force 'refs/tags/*' ``` [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. -1. Manually run [project housekeeping](../../../administration/housekeeping.md#manual-housekeeping) +1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. + + ```shell + git push origin --force 'refs/replace/*' + ``` + + Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. + +1. Run a [repository cleanup](#repository-cleanup). NOTE: **Note:** Project statistics are cached for performance. You may need to wait 5-10 minutes @@ -106,26 +117,9 @@ to see a reduction in storage utilization. ## Purge files from GitLab storage -To reduce the size of your repository in GitLab, you must remove GitLab internal references to -commits that contain large files. Before completing these steps, -[purge files from your repository history](#purge-files-from-repository-history). +In addition to the refs mentioned above, GitLab also creates hidden `refs/keep-around/*`to prevent commits being deleted. Hidden refs are not advertised, which means we can't download them using Git, but these refs are included in a project export. -As well as [branches](branches/index.md) and tags, which are a type of Git ref, GitLab automatically -creates other refs. These refs prevent dead links to commits, or missing diffs when viewing merge -requests. [Repository cleanup](#repository-cleanup) can be used to remove these from GitLab. - -The following internal refs are not advertised: - -- `refs/merge-requests/*` for merge requests. -- `refs/pipelines/*` for - [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). -- `refs/environments/*` for environments. - -This means they are not usually included when fetching, which makes fetching faster. In addition, -`refs/keep-around/*` are hidden refs to prevent commits with discussion from being deleted and -cannot be fetched at all. - -However, these refs can be accessed from the Git bundle inside a project export. +To purge files from GitLab storage: 1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) using a supported package manager or from source. @@ -173,6 +167,39 @@ However, these refs can be accessed from the Git bundle inside a project export. [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) for more examples and the complete documentation. +1. Because cloning from a bundle file sets the `origin` remote to the local bundle file, delete this `origin` remote, and set it to the URL to your repository: + + ```shell + git remote remove origin + git remote add origin https://gitlab.example.com/<namespace>/<project_name>.git + ``` + +1. Force push your changes to overwrite all branches on GitLab: + + ```shell + git push origin --force 'refs/heads/*' + ``` + + [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + remove branch protection, push, and then re-enable protected branches. + +1. To remove large files from tagged releases, force push your changes to all tags on GitLab: + + ```shell + git push origin --force 'refs/tags/*' + ``` + + [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + protection, push, and then re-enable protected tags. + +1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. + + ```shell + git push origin --force 'refs/replace/*' + ``` + + Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. + 1. Run a [repository cleanup](#repository-cleanup). ## Repository cleanup @@ -187,16 +214,27 @@ references to these objects. You can use To clean up a repository: 1. Go to the project for the repository. -1. Navigate to **{settings}** **Settings > Repository**. -1. Upload a list of objects. For example, a `commit-map` file. +1. Navigate to **Settings > Repository**. +1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the + `filter-repo` directory. + + If your `commit-map` file is larger than 10MB, the file can be split and uploaded piece by piece: + + ```shell + split -l 100000 filter-repo/commit-map filter-repo/commit-map- + ``` + 1. Click **Start cleanup**. This will: - Remove any internal Git references to old commits. -- Run `git gc` against the repository. +- Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily + cause the size of your repository to increase significantly, because the old pack files are not removed until the + new pack files have been created. +- Recalculate the size of your repository on disk. -You will receive an email once it has completed. +You will receive an email notification with the recalculated repository size after the cleanup has completed. When using repository cleanup, note: diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index bdf13100a6a..bbb673b74b0 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- @@ -114,14 +117,92 @@ After the mirror is created, this option can currently only be modified via the To set up a mirror from GitLab to GitHub, you need to follow these steps: -1. Create a [GitHub personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. +1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. 1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. 1. Fill in **Password** field with your GitHub personal access token. 1. Click the **Mirror repository** button. The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. -The repository will push soon. To force a push, click the appropriate button. +The repository will push soon. To force a push, click the **Update now** (**{retry}**) button. + +## Setting up a push mirror from GitLab to AWS CodeCommit + +AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. + +Each new AWS Codepipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. + +If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. + +NOTE: **Note:** +GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. + +To set up a mirror from GitLab to AWS CodeCommit: + +1. In the AWS IAM console, create an IAM user. +1. Add the following least privileges permissions for repository mirroring as an "inline policy". + + The Amazon Resource Names (ARNs) must explicitly include the region and account. The IAM policy + below grants privilege for mirroring access to two sample repositories. These permissions have + been tested to be the minimum (least privileged) required for mirroring: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "MinimumGitLabPushMirroringPermissions", + "Effect": "Allow", + "Action": [ + "codecommit:GitPull", + "codecommit:GitPush" + ], + "Resource": [ + "arn:aws:codecommit:us-east-1:111111111111:MyDestinationRepo", + "arn:aws:codecommit:us-east-1:111111111111:MyDemo*" + ] + } + ] + } + ``` + +1. After the user was created, click the AWS IAM user name. +1. Click the **Security credentials** tab. +1. Under **HTTPS Git credentials for AWS CodeCommit** click **Generate credentials**. + + NOTE: **Note:** + This Git user ID and password is specific to communicating with CodeCommit. Do + not confuse it with the IAM user ID or AWS keys of this user. + +1. Copy or download special Git HTTPS user ID and password. +1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repo. +1. Open your new repository and click **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). +1. In GitLab, open the repository to be push-mirrored. +1. Click **Settings > Repository** and expand **Mirroring repositories**. +1. Fill in the **Git repository URL** field using this format: + + ```plaintext + https://<your_aws_git_userid>@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + ``` + + Replace `<your_aws_git_userid>` with the AWS **special HTTPS Git user ID** from the IAM Git + credentials created earlier. Replace `<your_codecommit_repo>` with the name of your repo in CodeCommit. + +1. For **Mirror direction**, select **Push**. +1. For **Authentication method**, select **Password** and fill in the **Password** field with the special IAM Git clone user ID **password** created earlier in AWS. +1. The option **Only mirror protected branches** should be good for CodeCommit as it pushes more + frequently (from every five minutes to every minute). + CodePipeline requires individual pipeline setups for named branches you wish to have a AWS CI setup for. Since feature branches that have dynamic names will not be supported anyway, configuring **Only mirror protected branches** does not cause flexibility problems with CodePipeline integration as long as you are also willing to protect all the named branches you want to build CodePipelines for. + +1. Click **Mirror repository**. You should see the mirrored repository appear: + + ```plaintext + https://*****:*****@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + ``` + +To test mirroring by forcing a push, click the half-circle arrows button (hover text is **Update now**). +If **Last successful update** shows a date, you have configured mirroring correctly. +If it is not working correctly a red `error` tag appears and shows the error message as hover text. ## Setting up a push mirror to another GitLab instance with 2FA activated @@ -232,7 +313,7 @@ fingerprints in the open 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/) -- [GitHub](https://help.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) - [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 59fedacb2ca..452955b327c 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,4 +1,7 @@ --- +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/#designated-technical-writers type: howto --- @@ -46,7 +49,7 @@ has already been created, which creates a link to the license itself.  ->**Note:** +NOTE: **Note:** The **Set up CI/CD** button will not appear on an empty repository. You have to at least add a file in order for the button to show up. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index ffbad4e0989..972a46ee7a3 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: concepts, howto --- diff --git a/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png b/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png Binary files differindex aafc8543bae..04cb011ff89 100644 --- a/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png +++ b/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png diff --git a/doc/user/project/requirements/img/requirements_list_v13_1.png b/doc/user/project/requirements/img/requirements_list_v13_1.png Binary files differindex 3d2adfac074..0ebda571928 100644 --- a/doc/user/project/requirements/img/requirements_list_v13_1.png +++ b/doc/user/project/requirements/img/requirements_list_v13_1.png diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index cb6f8e2221d..e9b07f54b91 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -111,7 +111,7 @@ The **Thank you email** is the email sent to a user after they submit an issue. The file name of the template has to be `thank_you.md`. You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue IID in the email and `%{ISSUE_PATH}` placeholder which will be replaced by project path and the issue IID. -As the service desk issues are created as confidential (only project members can see them) +As the Service Desk issues are created as confidential (only project members can see them) the response email does not provide the issue link. #### New note email diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index cb9f0491b44..478d9b3b948 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference, howto +--- + # Project import/export > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. @@ -17,7 +24,7 @@ See also: To set up a project import/export: - 1. Navigate to **{admin}** **Admin Area >** **{settings}** **Settings > Visibility and access controls**. + 1. Navigate to **Admin Area > Settings > Visibility and access controls**. 1. Scroll to **Import sources** 1. Enable desired **Import sources** @@ -34,7 +41,7 @@ Note the following: - Group members are exported as project members, as long as the user has maintainer or admin access to the group where the exported project lives. - Project members with owner access will be imported as maintainers. -- Using an admin account to import will map users by email address (self-managed only). +- Using an admin account to import will map users by primary email address (self-managed only). Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues will be owned by the importer. - If an imported project contains merge requests originating from forks, @@ -124,7 +131,7 @@ For more details on the specific data persisted in a project export, see the 1. Go to your project's homepage. -1. Click **{settings}** **Settings** in the sidebar. +1. Click **Settings** in the sidebar. 1. Scroll down to find the **Export project** button: diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 7fe6e702d1c..a65e48d5d56 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +type: reference, index, howto +--- + # Project settings NOTE: **Note:** @@ -57,7 +64,7 @@ Use the switches to enable or disable the following features: | **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | | **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | -| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration-premium-only) functionality | +| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | | **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/) | @@ -128,13 +135,13 @@ no longer actively maintained. Projects that have been archived can also be unarchived. Only project Owners and Admin users have the [permissions](../../permissions.md#project-members-permissions) to archive a project. -When a project is archived, the repository, issues, merge requests, and all +When a project is archived, the repository, packages, issues, merge requests, and all other features are read-only. Archived projects are also hidden in project listings. To archive a project: -1. Navigate to your project's **{settings}** **Settings > General**. +1. Navigate to your project's **Settings > General**. 1. Under **Advanced**, click **Expand**. 1. In the **Archive project** section, click the **Archive project** button. 1. Confirm the action when asked to. @@ -158,7 +165,7 @@ To find an archived project: Next, to unarchive the project: -1. Navigate to your project's **{settings}** **Settings > General**. +1. Navigate to your project's **Settings > General**. 1. Under **Advanced**, click **Expand**. 1. In the **Unarchive project** section, click the **Unarchive project** button. 1. Confirm the action when asked to. @@ -175,7 +182,7 @@ project via a browser) and its place on the file disk where GitLab is installed. To rename a repository: -1. Navigate to your project's **{settings}** **Settings > General**. +1. Navigate to your project's **Settings > General**. 1. Under **Advanced**, click **Expand**. 1. Under "Rename repository", change the "Path" to your liking. 1. Hit **Rename project**. @@ -198,7 +205,7 @@ You can transfer an existing project into a [group](../../group/index.md) if: To transfer a project: -1. Navigate to your project's **{settings}** **Settings > General**. +1. Navigate to your project's **Settings > General**. 1. Under **Advanced**, click **Expand**. 1. Under "Transfer project", choose the namespace you want to transfer the project to. @@ -212,25 +219,25 @@ NOTE: **Note:** GitLab administrators can use the admin interface to move any project to any namespace if needed. -#### Remove a project +#### Delete a project NOTE: **Note:** -Only project owners and admins have [permissions](../../permissions.md#project-members-permissions) to remove a project. +Only project owners and admins have [permissions](../../permissions.md#project-members-permissions) to delete a project. -To remove a project: +To delete a project: -1. Navigate to your project, and select **{settings}** **Settings > General > Advanced**. -1. In the Remove project section, click the **Remove project** button. +1. Navigate to your project, and select **Settings > General > Advanced**. +1. In the "Delete project" section, click the **Delete project** button. 1. Confirm the action when asked to. This action: -- Removes a project including all associated resources (issues, merge requests etc). +- Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, group admins can [configure](../../group/index.md#enabling-delayed-project-removal-premium) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only). +specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). CAUTION: **Warning:** The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to @@ -242,7 +249,7 @@ The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org To restore a project marked for deletion: -1. Navigate to your project, and select **{settings}** **Settings > General > Advanced**. +1. Navigate to your project, and select **Settings > General > Advanced**. 1. In the Restore project section, click the **Restore project** button. #### Removing a fork relationship @@ -270,7 +277,7 @@ to remove a fork relationship. ### Error Tracking -Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md). +Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). ### Jaeger tracing **(ULTIMATE)** @@ -278,5 +285,5 @@ Add the URL of a Jaeger server to allow your users to [easily access the Jaeger ### Status Page -[Add Storage credentials](../status_page/#syncing-incidents-to-the-status-page) -to enable the syncing of public Issues to a [deployed status page](../status_page/#status-page-project). +[Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) +to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 42ba2654b42..cbc4895f014 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,17 +1,24 @@ -# Project access tokens (Alpha) **(CORE ONLY)** +--- +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/#designated-technical-writers" +type: reference, howto +--- -CAUTION: **Warning:** -This is an [Alpha](https://about.gitlab.com/handbook/product/#alpha) feature, and it is subject to change at any time without -prior notice. +# Project access tokens **(CORE ONLY)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. -> - It's deployed behind a feature flag, disabled by default. +> - It was [deployed](https://gitlab.com/groups/gitlab-org/-/epics/2587) behind a feature flag, disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/218722) in GitLab 13.3. > - It's disabled on GitLab.com. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-project-access-tokens). +> - It can be enabled or disabled by project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can [disable it](#enable-or-disable-project-access-tokens). Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). -You can also use project access tokens with Git to authenticate over HTTP or SSH. +<!-- Commented out until https://gitlab.com/gitlab-org/gitlab/-/issues/219551 is fixed --> +<!-- You can also use project access tokens with Git to authenticate over HTTP or SSH. --> Project access tokens expire on the date you define, at midnight UTC. @@ -21,7 +28,7 @@ For examples of how you can use a project access token to authenticate with the 1. Log in to GitLab. 1. Navigate to the project you would like to create an access token for. -1. In the **{settings}** **Settings** menu choose **Access Tokens**. +1. In the **Settings** menu choose **Access Tokens**. 1. Choose a name and optional expiry date for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token). 1. Click the **Create project access token** button. @@ -31,8 +38,14 @@ For examples of how you can use a project access token to authenticate with the ## Project bot users For each project access token created, a bot user will also be created and added to the project with -["Maintainer" level permissions](../../permissions.md#project-members-permissions). API calls made with a -project access token will be associated to the corresponding bot user. +["Maintainer" level permissions](../../permissions.md#project-members-permissions). + +For the bot: + +- The name is set to the name of the token. +- The username is set to `project_{project_id}_bot`, such as `project_123_bot`. + +API calls made with a project access token are associated with the corresponding bot user. These users will appear in **Members** but can not be modified. Furthermore, the bot user can not be added to any other project. @@ -41,10 +54,12 @@ When the project access token is [revoked](#revoking-a-project-access-token) the records will be moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). +Project bot users are a [GitLab-created service account](../../../subscriptions/index.md#self-managed) and do not count as a licensed seat. + ## Revoking a project access token At any time, you can revoke any project access token by clicking the -respective **Revoke** button in **{settings}** **Settings > Access Tokens**. +respective **Revoke** button in **Settings > Access Tokens**. ## Limiting scopes of a project access token @@ -63,19 +78,30 @@ the following table. ### Enable or disable project access tokens -Project access tokens is an [Alpha](https://about.gitlab.com/handbook/product/#alpha) feature and is not recommended for production use. -It is deployed behind a feature flag that is **disabled by default**. +Project access tokens are 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 for your instance. +can disable it for your instance, globally or by project. + +To disable it globally: + +```ruby +Feature.disable(:resource_access_token) +``` -To enable it: +To disable it for a specific project: + +```ruby +Feature.disable(:resource_access_token, project) +``` + +To enable it globally: ```ruby Feature.enable(:resource_access_token) ``` -To disable it: +To enable it for a specific project: ```ruby -Feature.disable(:resource_access_token) +Feature.enable(:resource_access_token, project) ``` diff --git a/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_0.png b/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_0.png Binary files differdeleted file mode 100644 index a2f5248bf39..00000000000 --- a/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_0.png +++ /dev/null diff --git a/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_3.png b/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_3.png Binary files differnew file mode 100644 index 00000000000..52776c6a290 --- /dev/null +++ b/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_3.png diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 8653bb5001a..4e401014122 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -1,4 +1,7 @@ --- +stage: Create +group: Static Site 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/#designated-technical-writers" type: reference, how-to description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands." --- @@ -10,6 +13,7 @@ description: "The static site editor enables users to edit content on static web > - Support for adding images through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216640) in GitLab 13.1. > - Markdown front matter hidden on the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216834) in GitLab 13.1. > - Support for `*.md.erb` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223171) in GitLab 13.2. +> - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. DANGER: **Danger:** In GitLab 13.0, we [introduced breaking changes](https://gitlab.com/gitlab-org/gitlab/-/issues/213282) @@ -50,15 +54,15 @@ the bottom-left corner of its pages:  -When clicking it, GitLab will open up an editor window from which the content +When you click it, GitLab opens up an editor window from which the content can be directly edited. When you're ready, you can submit your changes in a click of a button: - + When an editor submits their changes, in the background, GitLab automatically creates a new branch, commits their changes, and opens a merge request. The -editor will land directly on the merge request, and then they can assign it to +editor lands directly on the merge request, and then they can assign it to a colleague for review. ## Getting started @@ -73,7 +77,7 @@ easily edit your content. template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates). 1. Edit the `data/config.yml` file adding your project's path. -1. Editing the file will trigger a CI/CD pipeline to deploy your project with GitLab Pages. +1. Editing the file triggers a CI/CD pipeline to deploy your project with GitLab Pages. 1. When the pipeline finishes, from your project's left-side menu, go to **Settings > Pages** to find the URL of your new website. 1. Visit your website and look at the bottom-left corner of the screen to see the new **Edit this page** button. diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index 1c885ae043f..20bb23f1d6b 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -1,134 +1,5 @@ --- -stage: Monitor -group: Health -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 +redirect_to: '../../../operations/incident_management/status_page.md' --- -# GitLab Status Page **(ULTIMATE)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2479) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. - -GitLab Status Page allows you to create and deploy a static website to communicate efficiently to users during an incident. - -## How to set up - -NOTE: **Note:** -Only AWS S3 is supported as a deploy target. - -```mermaid -graph TB - subgraph GitLab Instance - issues(issue updates) -- trigger --> middleware(Background job: JSON generation) - end - subgraph Cloud Provider - middleware --saves data --> c1(Cloud Bucket stores JSON file) - end - subgraph Status Page - d(Static Site on CDN) -- fetches data --> c1 - end -``` - -Setting up a Status Page is pretty painless but there are a few things you need to do. - -### Cloud account set up - -To use GitLab Status Page you first need to set up your account details for your cloud provider in the operations settings page. Today, only AWS is supported. - -#### AWS Setup - -1. Within your AWS acccout, create two new IAM policies. - - [Create bucket](https://gitlab.com/gitlab-org/status-page/-/blob/master/deploy/etc/s3_create_policy.json). - - [Update bucket contents](https://gitlab.com/gitlab-org/status-page/-/blob/master/deploy/etc/s3_update_bucket_policy.json) (Remember replace `S3_BUCKET_NAME` with your bucket name). -1. Create a new AWS access key with the permissions policies created in the first step. - -### Status Page project - -To deploy the Status Page to AWS S3 you need to add the Status Page project & configure the necessary CI variables. - -1. Fork the [Status Page](https://gitlab.com/gitlab-org/status-page) project. This can also be done via [Repository Mirroring](https://gitlab.com/gitlab-org/status-page#repository-mirroring) which will ensure you get the up-to-date Status Page features. -1. Add the following variables in **Settings > CI/CD > Variables**. (To get these variables from Amazon, use your Amazon Console): - - `S3_BUCKET_NAME` - name of the Amazon S3 bucket (If a bucket with the provided name doesn't exist, the first pipeline run will create one and configure it for [static website hosting](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html)) - - `AWS_DEFAULT_REGION` - the AWS region - - `AWS_ACCESS_KEY_ID` - the AWS access key ID - - `AWS_SECRET_ACCESS_KEY` - the AWS secret -1. Run the pipeline to deploy the Status Page to S3. - -### Syncing incidents to the Status Page - -Once the CI/CD variables are set, you'll need to set up the Project you want to use for Incident issues: - -1. To view the [Operations Settings](../settings/#operations-settings) page, navigate to **{settings}** **Settings > Operations > Status Page**. -1. Fill in your cloud provider's credentials and make sure the **Active** checkbox is checked. -1. Click **Save changes**. - -## Status Page UI - -The Status Page landing page shows you an overview of the recent incidents. Clicking on an incident will take you to the incident's detail page. - - - -### Incident detail page - -The incident detail page shows detailed information about a particular incident. For example: - -- Status on the incident, including when the incident was last updated. -- The incident title, including any emojis. -- The description of the incident, including emojis. -- Any file attachments provided in the incident description or comments with a valid image extension. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205166) in GitLab 13.1. -- A chronological ordered list of updates to the incident. - - - -## How it works - -### Publishing Incidents - -To publish an Incident, you first need to create an issue in the Project you enabled the Status Page settings in. - -Issues are not published to the Status Page by default. Use the `/publish` [quick action](../quick_actions.md) in an issue to publish the issue. Only [project or group owners](../../permissions.md) are permitted to publish issues. - -After the quick action is used, a background worker publishes the issue onto the Status Page using the credentials you provided during setup. - -Since all incidents are published publicly, user and group mentions are anonymized with `Incident Responder`, -and titles of non-public [GitLab references](../../markdown.md#special-gitlab-references) are removed. - -When an Incident is published in the GitLab project, you can access the -details page of the Incident by clicking the **Published on status page** button -displayed under the Incident's title. - - - -NOTE: **Note:** -Confidential issues can't be published. If you make a published issue confidential, it will be unpublished. - -### Publishing updates - -To publish an update to the Incident, update the incident issue's description. - -CAUTION: **Caution:** -When referenced issues are changed (e.g. title, confidentiality) the incident they were referenced in are not updated automatically. - -### Adding comments - -To add comments to the Status Page Incident, create a comment on the incident issue. - -When you're ready to publish the comment, add a microphone [award emoji](../../../user/award_emojis.md) reaction (`:microphone` 🎤) to the comment. This marks the comment as one which should be deployed to the Status Page. - -CAUTION: **Caution:** -Anyone with access to view the Issue can add an Emoji Award to a comment, so you may want to keep your Issues limited to team members only. - -### Changing the Incident status - -To change the incident status from `open` to `closed`, close the incident issue within GitLab. This will then be updated shortly on the Status Page website. - -## Attachment storage - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205166) in GitLab 13.1. - -Beginning with GitLab 13.1, files attached to incident issue descriptions or -comments are published and unpublished to the status page storage as part of -the [publication flow](#how-it-works). - -### Limit - -Only 5000 attachments per issue will be transferred to the status page. +This document was moved to [status_page.md](../../../operations/incident_management/status_page.md). diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index abead8afdc8..12ba55cafdc 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,3 +1,10 @@ +--- +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/#designated-technical-writers" +type: reference, how-to +--- + # Web IDE > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. @@ -24,8 +31,6 @@ file path fragments to start seeing results. ## Syntax highlighting -> Support for `.gitlab-ci.yml` validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. - As expected from an IDE, syntax highlighting for many languages within the Web IDE will make your direct editing even easier. @@ -37,14 +42,6 @@ The Web IDE currently provides: - IntelliSense and validation support (displaying errors and warnings, providing smart completions, formatting, and outlining) for some languages. For example: TypeScript, JavaScript, CSS, LESS, SCSS, JSON, and HTML. -- Validation support for certain JSON and YAML files using schemas based on the - [JSON Schema Store](https://www.schemastore.org/json/). This feature - is only supported for the `.gitlab-ci.yml` file. - - NOTE: **Note:** - Validation support based on schemas is hidden behind - the feature flag `:schema_linting` on self-managed installations. To enable the - feature, you can [turn on the feature flag in Rails console](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags). Because the Web IDE is based on the [Monaco Editor](https://microsoft.github.io/monaco-editor/), you can find a more complete list of supported languages in the @@ -56,6 +53,37 @@ If you are missing Syntax Highlighting support for any language, we prepared a s NOTE: **Note:** Single file editing is based on the [Ace Editor](https://ace.c9.io). +### Schema based validation + +> - Support for `.gitlab-ci.yml` validation [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-schema-based-validation-core-only). + +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/). This feature is +only supported for the `.gitlab-ci.yml` file. + +#### Enable or disable Schema based validation **(CORE ONLY)** + +Schema based validation 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) +``` + ### Themes > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 9044ee0765f..5503cd97628 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,3 +1,10 @@ +--- +stage: Create +group: Knowledge +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" +type: reference, how-to +--- + # Wiki A separate system for documentation called Wiki, is built right into each diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index 0613e9b8e34..820d66e4cd6 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -1,3 +1,10 @@ +--- +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/#designated-technical-writers" +type: reference +--- + # Advanced Global Search **(STARTER)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. @@ -15,20 +22,20 @@ visit the [administrator documentation](../../integration/elasticsearch.md). The Advanced Global Search in GitLab is a powerful search service that saves you time. Instead of creating duplicate code and wasting time, you can -now search for code within other teams that can help your own project. +now search for code within other projects that can help your own project. GitLab leverages the search capabilities of [Elasticsearch](https://www.elastic.co/elasticsearch/) and enables it when searching in: - Projects -- Repositories -- Commits - Issues - Merge requests - Milestones -- Notes (comments) -- Snippets +- Comments +- Code +- Commits - Wiki +- Users ## Use cases diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index 5dc1f8fe779..d8fce3223ed 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -1,3 +1,10 @@ +--- +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/#designated-technical-writers" +type: reference +--- + # Advanced Syntax Search **(STARTER)** > - Introduced in [GitLab Enterprise Starter](https://about.gitlab.com/pricing/) 9.2 @@ -66,3 +73,20 @@ Examples: - Finding the text 'def create' inside files with the `.rb` extension: `def create extension:rb` - Finding the text `sha` inside files in a folder called `encryption`: `sha path:encryption` - Finding any file starting with `hello` containing `world` and with the `.js` extension: `world filename:hello* extension:js` + +#### Excluding filters + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31684) in GitLab Starter 13.3. + +Filters can be inversed to **filter out** results from the result set, by prefixing the filter name with a `-` (hyphen) character, such as: + +- `-filename` +- `-path` +- `-extension` + +Examples: + +- Finding `rails` in all files but `Gemfile.lock`: `rails -filename:Gemfile.lock` +- Finding `success` in all files excluding `.po|pot` files: `success -filename:*.po*` +- Finding `import` excluding minified JavaScript (`.min.js`) files: `import -extension:min.js` +- Finding `docs` for all files outside the `docs/` folder: `docs -path:docs/` diff --git a/doc/user/search/img/filter_approved_by_merge_requests_v13_0.png b/doc/user/search/img/filter_approved_by_merge_requests_v13_0.png Binary files differindex ef4c65aea4b..5020da90297 100644 --- a/doc/user/search/img/filter_approved_by_merge_requests_v13_0.png +++ b/doc/user/search/img/filter_approved_by_merge_requests_v13_0.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index b616b606b64..98b34fe8383 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,3 +1,10 @@ +--- +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/#designated-technical-writers" +type: index, reference, howto +--- + # Search through GitLab ## Issues and merge requests diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 4d8f47ee3be..15391f034a8 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,3 +1,10 @@ +--- +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/#designated-technical-writers" +type: reference +--- + # Snippets With GitLab Snippets you can store and share bits of code and text with other users. diff --git a/doc/user/todos.md b/doc/user/todos.md index ef0e75bc197..02fef07a89a 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -43,9 +43,15 @@ A To Do appears on your To-Do List when: - Commit - Design - The CI/CD pipeline for your merge request failed -- An open merge request becomes unmergeable due to conflict, and you are either: - - The author - - Have set it to automatically merge once the pipeline succeeds +- An open merge request becomes unmergeable due to conflict, and one of the following is true: + - You are the author + - You are the user that set it to automatically merge once the pipeline succeeds +- [Since GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12136), a merge request + is removed from a [merge train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) + and you are the user that added it. **(PREMIUM)** + +When multiple trigger actions occur for the same user on the same object (for example, an issue) +only the first is displayed as a single to-do on their To-Do List. To-do triggers are not affected by [GitLab Notification Email settings](profile/notifications.md). diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md new file mode 100644 index 00000000000..027f7337228 --- /dev/null +++ b/doc/user/upgrade_email_bypass.md @@ -0,0 +1,123 @@ +# Updating to GitLab 13.2: Email confirmation issues + +In the [GitLab 13.0.1 security release](https://about.gitlab.com/releases/2020/05/27/security-release-13-0-1-released/), +we described a security issue that allowed users to bypass the email verification process. +In that notice, we strongly recommended that you upgrade all affected installations to the +latest version as soon as possible. + +There is a chance that users with multiple email addresses on a self-managed instance may +be unable to commit code and sign in. For more information, see the following resolved and closed +[security issue](https://gitlab.com/gitlab-org/gitlab/-/issues/121664). + +This page can help you identify the users at risk, as well as potential issues of the update. + +## The risk: users get emails that require confirmation + +During the update process to GitLab 13.2, a background migration is run for accounts that meet the +conditions for the security issue. Such users are marked as _unconfirmed_. + +An initial email is sent to _unconfirmed_ users to describe the issue. A second email is then +sent within five minutes, with a link for users to re-confirm the subject email address. + +## Do the confirmation emails expire? + +The links in these re-confirmation emails expire after one day by default. Users who click an expired link will be asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. + +## Generate a list of affected users + +You can generate this list before and after the upgrade using different methods. + +### Before an upgrade to GitLab 13.2 + +Use the following code to search for users who: + +- Are currently confirmed. +- Include identical `confirmed_at` times. +- Also have a secondary email address. + +```ruby +emails_and_users_that_will_be_unconfirmed = Email.joins(:user).merge(User.active).where('emails.confirmed_at IS NOT NULL').where('emails.confirmed_at = users.confirmed_at').where('emails.email <> users.email') +``` + +### After an upgrade to GitLab 13.2 + +Use the following code to search for users who: + +- Are currently **not** confirmed. +- Are also pending confirmation on or after the date of upgrade. + +```ruby +User.where(confirmed_at: nil).where('LENGTH(confirmation_token) = 32') +``` + +## What does it look like when a user is blocked? + +A regular user might receive a message that says "You have to confirm your email address before continuing". This message could includes a 404 or 422 error code, when the user tries to sign in. + +NOTE: **Note:** +We hope to improve the [sign-in experience for an unverified user](https://gitlab.com/gitlab-org/gitlab/-/issues/29279) in a future release. + +When an affected user commits code to a Git repository, that user may see the following message: + +```shell +Your account has been blocked. Fatal: Could not read from remote repository + +# or + +Your primary email address is not confirmed. +``` + +You can assure your users that they have not been [Blocked](admin_area/blocking_unblocking_users.md) by an administrator. +When affected users see this message, they must confirm their email address before they can commit code. + +## What do I need to know as an administrator of a GitLab self-managed Instance? + +You have the following options to help your users: + +- They can confirm their address through the email that they received. +- They can confirm the subject email address themselves by navigating to `https://gitlab.example.com/users/confirmation/new`. + +As an administrator, you may also confirm a user in the [Admin Area](admin_area/#administering-users). + +## What do I do if I am an administrator and I am locked out? + +If you are an administrator and cannot otherwise verify your email address, sign in to your GitLab +instance with a [Rails console session](../administration/troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session). +Once connected, run the following commands to confirm your administrator account: + +```ruby +admin = User.find_by_username "root" # replace with your admin username +admin.confirmed_at = Time.zone.now +admin.save! +``` + +## How do I force-confirm all users on my self-managed instance? + +If you are an administrator and would like to force-confirm all users on your system, sign in to your GitLab +instance with a [Rails console session](../administration/troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session). +Once connected, run the following commands to confirm all user accounts: + +```ruby +User.where('LENGTH(confirmation_token) = 32').where(confirmed_at: nil).find_each { |u| u.confirmed_at = Time.now; u.save } +``` + +CAUTION: **Caution:** +The command described in this section may activate users who have not properly confirmed their email addresses. + +## What about LDAP users? + +LDAP Users will remain confirmed if all of the following conditions are met: + +- The ["User email confirmation at sign-up" option](../security/user_email_confirmation.md) is set to false. +- The first sign-in is based on user LDAP credentials. +- The user has added and verified [a secondary email address](profile/index.md#profile-settings) some time later. + +NOTE: **Note:** +Confirmation timestamps (primary vs. secondary) will be different. + +Users will be unconfirmed by the background migration if any of the following conditions are met: + +- They [create an account through GitLab](profile/account/create_accounts.md). +- They [swap their primary email address](profile/index.md#profile-settings) and verify it. +- If they have two email addresses with the same `confirmed_at` timestamp due to the linked [security issue](https://gitlab.com/gitlab-org/gitlab/-/issues/121664). +- [LDAP is introduced](../administration/auth/ldap/index.md), and users' primary email address matches that in LDAP. |
