diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-06-18 11:18:50 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-06-18 11:18:50 +0000 |
| commit | 8c7f4e9d5f36cff46365a7f8c4b9c21578c1e781 (patch) | |
| tree | a77e7fe7a93de11213032ed4ab1f33a3db51b738 /doc/user | |
| parent | 00b35af3db1abfe813a778f643dad221aad51fca (diff) | |
| download | gitlab-ce-8c7f4e9d5f36cff46365a7f8c4b9c21578c1e781.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-1-stable-ee
Diffstat (limited to 'doc/user')
288 files changed, 4641 insertions, 2369 deletions
diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 77f4a84cf6f..783aadc0974 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -1,4 +1,7 @@ --- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 7c8ab18ccef..06a26737495 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -1,4 +1,7 @@ --- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- @@ -8,7 +11,7 @@ GitLab administrators can deactivate and activate users. ## Deactivating a user -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22257) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. In order to temporarily prevent access by a GitLab user that has no recent activity, administrators can choose to deactivate the user. @@ -45,7 +48,7 @@ A deactivated user does not consume a [seat](../../subscriptions/index.md#choosi ## Activating a user -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22257) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. A deactivated user can be activated from the Admin Area. @@ -63,4 +66,4 @@ Activating a user will change the user's state to active and it consumes a [seat](../../subscriptions/index.md#choosing-the-number-of-users). TIP: **Tip:** -A deactivated user can also activate their account by themselves by simply logging back via the UI. +A deactivated user can also activate their account themselves by simply logging back in via the UI. diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 80440b63f71..55dabce7342 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -15,7 +15,7 @@ By default, the navigation bar has the GitLab logo, but this can be customized w any image desired. It is optimized for images 28px high (any width), but any image can be used (less than 1MB) and it will automatically be resized. - + Once you select and upload an image, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. @@ -38,8 +38,8 @@ of the page to activate it in the GitLab instance. ## System header and footer messages -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab-foss/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. +> - [Added](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. You can add a small header message, a small footer message, or both, to the interface of your GitLab instance. These messages will appear on all projects and pages of the diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index e3b9cd1218c..2f98709a089 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -1,4 +1,7 @@ --- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 5427b0c5200..7e1a4faee75 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -24,7 +24,7 @@ Banners are shown on the top of a page and in Git remote responses.  -```bash +```shell $ git push ... remote: diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 79e9cbc5b14..5eecfbb73c6 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,3 +1,10 @@ +--- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto +--- + # Credentials inventory **(ULTIMATE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20912) in GitLab 12.6. diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index f9a4dad2500..d194ca42215 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,10 +1,13 @@ --- +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 type: reference --- # Custom instance-level project templates **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. GitLab administrators can configure the group where all the custom project templates are sourced. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index bc6f93891df..b9bd94e65be 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.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/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index bb4ca8ca618..d17e0f7430c 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -1,4 +1,7 @@ --- +stage: Enablement +group: Geo +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 --- diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index 1d15be89bd5..3c35276b843 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -1,4 +1,7 @@ --- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 59b71b05b16..1ffaf4e0678 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -1,4 +1,7 @@ --- +stage: Growth +group: Conversion +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 --- @@ -64,12 +67,12 @@ export GITLAB_LICENSE_FILE="/path/to/license/file" Omnibus installations should add this entry to `gitlab.rb`: ```ruby -gitlab_rails['license_file'] = "/path/to/license/file" +gitlab_rails['initial_license_file'] = "/path/to/license/file" ``` CAUTION: **Caution:** These methods will only add a license at the time of installation. Use the -Admin Area in the web ui to renew or upgrade licenses. +Admin Area in the web user interface to renew or upgrade licenses. --- diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 0c7beadad48..153ccfc128a 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -1,10 +1,13 @@ --- +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 --- # Instance-level merge request approval rules **(PREMIUM ONLY)** -> Introduced in [GitLab Premium](https://gitlab.com/gitlab-org/gitlab/issues/39060) 12.8. +> Introduced in [GitLab Premium](https://gitlab.com/gitlab-org/gitlab/-/issues/39060) 12.8. Merge request approvals rules prevent users overriding certain settings on a project level. When configured, only administrators can change these settings on a project level 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 83b29597bec..b4fb7a524da 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -15,6 +15,17 @@ 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. +## Max import size + +You can change the maximum file size for imports in GitLab. +Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. +From here, you can increase or decrease by changing the value in `Maximum import size (MB)`. + +NOTE: **Note:** +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: @@ -99,7 +110,7 @@ nginx['client_max_body_size'] = "200m" ## Limiting lifetime of personal access tokens **(ULTIMATE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3649) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. Users can optionally specify an expiration date for [personal access tokens](../../profile/personal_access_tokens.md). @@ -131,7 +142,7 @@ Once a lifetime for personal access tokens is set, GitLab will: ## Disabling user profile name changes **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24605) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24605) in GitLab 12.7. To maintain integrity of user details in [Audit Events](../../../administration/audit_events.md), GitLab administrators can choose to disable a user's ability to change their profile name. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 4a401210928..3a287f29a0a 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -1,4 +1,7 @@ --- +stage: Verify +group: Continuous Integration +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 --- @@ -32,7 +35,7 @@ The maximum size of the [job artifacts](../../../administration/job_artifacts.md can be set at: - The instance level. -- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/21688), the project and group level. +- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/21688), the project and group level. The value is: @@ -169,7 +172,7 @@ but commented out to help encourage others to add to it in the future. --> CAUTION: **Caution:** This feature is being re-evaluated in favor of a different -[compliance solution](https://gitlab.com/gitlab-org/gitlab/issues/34830). +[compliance solution](https://gitlab.com/gitlab-org/gitlab/-/issues/34830). We recommend that users who haven't yet implemented this feature wait for the new solution. diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index a99897657ae..d956364b3ea 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -1,7 +1,11 @@ --- type: reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- + # Email **(CORE ONLY)** You can customize some of the content in emails sent from your GitLab instance. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 3a03e46fa1f..c5c5f08aea1 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -4,7 +4,7 @@ type: reference # External authorization control **(CORE ONLY)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4216) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4216) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. In highly controlled environments, it may be necessary for access policy to be @@ -31,7 +31,7 @@ functionality that render cross-project data. That includes: This is to prevent performing to many requests at once to the external authorization service. -Whenever access is granted or denied this is logged in a logfile called +Whenever access is granted or denied this is logged in a log file called `external-policy-access-control.log`. Read more about logs GitLab keeps in the [omnibus documentation](https://docs.gitlab.com/omnibus/settings/logs.html). @@ -60,7 +60,7 @@ The available required properties are: requesting authorization if no specific label is defined on the project When using TLS Authentication with a self signed certificate, the CA certificate -needs to be trusted by the openssl installation. When using GitLab installed using +needs to be trusted by the OpenSSL installation. When using GitLab installed using Omnibus, learn to install a custom CA in the [omnibus documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). Alternatively learn where to install custom certificates using `openssl version -d`. diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 775a99d7574..68f359368f0 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -4,7 +4,7 @@ type: reference # Gitaly timeouts - + 3 timeout types can be configured to make sure that long running Gitaly calls don't needlessly take up resources. diff --git a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation.png b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation.png Binary files differdeleted file mode 100644 index 5aa9b95f835..00000000000 --- a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v13_1.png b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v13_1.png Binary files differnew file mode 100644 index 00000000000..9edc916c7fb --- /dev/null +++ b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v13_1.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 761d640c535..df087722fcf 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -32,7 +32,7 @@ Access the default page for admin area settings by navigating to | Option | Description | | ------ | ----------- | | [Elasticsearch](../../../integration/elasticsearch.md#enabling-elasticsearch) | Elasticsearch integration. Elasticsearch AWS IAM. | -| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in Asciidoc documents. | +| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc documents. | | [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE ONLY)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | | [Snowplow](../../../development/telemetry/snowplow.md) | Configure the Snowplow integration. | diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index bef4e31259f..ae56c67f0ab 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -4,7 +4,7 @@ type: reference # Instance template repository **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5986) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. ## Overview 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 9850de0f4b3..bbc5ed04202 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -4,7 +4,7 @@ type: reference # Push event activities limit and bulk push events -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31007) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31007) in GitLab 12.4. This allows you to set the number of changes (branches or tags) in a single push to determine whether individual push events or bulk push event will be created. diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index dc23865e730..bae60aba15f 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -1,5 +1,8 @@ --- type: reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Rate limits on issue creation @@ -14,7 +17,7 @@ For example, requests using the [Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/raw/master/app/controllers/projects/issues_controller.rb) action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. - + This limit is: 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 95748f68a55..d9ca4a0881a 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -66,7 +66,7 @@ To ensure only admin users can delete projects: ## Default deletion adjourned period **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32935) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. By default, a project or group marked for removal will be permanently removed after 7 days. This period may be changed, and setting this period to 0 will enable immediate removal diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index e0aa01c29b2..8c4c54153bb 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -2,14 +2,13 @@ description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Manage group: Analytics -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 +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 --- # Code Review Analytics **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/38062) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38062) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.7. Code Review Analytics makes it easy to view the longest-running reviews among open merge requests, enabling you to take action on individual merge requests and reduce overall cycle time. 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 differnew file mode 100644 index 00000000000..073976fd740 --- /dev/null +++ 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 48df7bc340a..18f6d79ef23 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,15 +1,14 @@ --- stage: Manage group: Analytics -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 +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 --- # Analytics ## Analytics workspace -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12077) in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab 12.2. The Analytics workspace will make it possible to aggregate analytics across GitLab, so that users can view information across multiple projects and groups @@ -19,7 +18,7 @@ To access the Analytics workspace, click on **More > Analytics** in the top navi ## Group-level analytics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/195979) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. The following analytics features are available at the group level: diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index d0fda61d6a5..653836de8be 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,17 +1,16 @@ --- stage: Manage group: Analytics -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 +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 --- # Productivity Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12079) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12079) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. Track development velocity with Productivity Analytics. -For many companies, the development cycle is a blackbox and getting an estimate of how +For many companies, the development cycle is a black box and getting an estimate of how long, on average, it takes to deliver features is an enormous endeavor. While [Value Stream Analytics](../project/cycle_analytics.md) focuses on the entire @@ -49,7 +48,7 @@ The following metrics and visualizations are available on a project or group lev ## Date ranges -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13188) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13188) in GitLab 12.4. GitLab has the ability to filter analytics based on a date range. To filter results: diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 17032990b09..6d2de951a55 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,8 +1,7 @@ --- stage: Manage group: Analytics -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 +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 --- # Repository Analytics @@ -34,6 +33,7 @@ The data in the charts are updated soon after each commit in the default branch. Available charts: - Programming languages used in the repository +- Code coverage history (last 3 months) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1) - Commit statistics (last month) - Commits per day of month - Commits per weekday diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 90a4f96f00b..0efe28ac5f7 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,14 +1,13 @@ --- stage: Manage group: Analytics -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 +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 --- # Value Stream Analytics > - Introduced as Cycle Analytics prior to GitLab 12.3 at the project level. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 at the group level. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 at the group level. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from Cycle Analytics to Value Stream Analytics in GitLab 12.8. Value Stream Analytics measures the time spent to go from an @@ -47,11 +46,11 @@ There are seven stages that are tracked as part of the Value Stream Analytics ca - **Staging** (Continuous Deployment) - Time between merging and deploying to production - **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**. + - 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 -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13216) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. GitLab provides the ability to filter analytics based on a date range. To filter results: @@ -59,9 +58,20 @@ GitLab provides the ability to filter analytics based on a date range. To filter 1. Optionally select a project. 1. Select a date range using the available date pickers. -## How the data is measured +## How Time metrics are measured -Value Stream Analytics records cycle time and data based on the project issues with the +The "Time" metrics near the top of the page are measured as follows: + +- **Lead time**: median time from issue created to issue closed. +- **Cycle time**: median time from first commit to issue closed. + +Note: A commit is associated with an issue by [crosslinking](../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. + + + +## How the stages are measured + +Value Stream Analytics records stage time and data based on the project issues with the exception of the staging and total stages, where only data deployed to production are measured. @@ -79,7 +89,7 @@ Each stage of Value Stream Analytics is further described in the table below. | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | | Review | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. | | Staging | Measures the median time between merging the merge request with a closing issue pattern until the very first deployment to production. It's tracked by the environment set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI/CD configuration. If there isn't a production environment, this is not tracked. | -| Total | The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. [Previously known](https://gitlab.com/gitlab-org/gitlab/issues/38317) as **Production**. | +| Total | The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. [Previously known](https://gitlab.com/gitlab-org/gitlab/-/issues/38317) as **Production**. | How this works, behind the scenes: @@ -274,7 +284,7 @@ from within the chart itself. ### Chart median line -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36675) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36675) in GitLab 12.7. The median line on the chart displays data that is offset by the number of days selected. For example, if 30 days worth of data has been selected (for example, 2019-12-16 to 2020-01-15) the diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index dfddbde379d..f0fcd0c4419 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Security Configuration **(ULTIMATE)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 6e52d7dbdcf..0ffe83cdfc9 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Defend +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Container Scanning **(ULTIMATE)** @@ -8,35 +11,28 @@ type: reference, howto ## Overview -If you are using [GitLab CI/CD](../../../ci/README.md), you can check your Docker -images (or more precisely the containers) for known vulnerabilities by using -[Clair](https://github.com/quay/clair) and [klar](https://github.com/optiopay/klar), -two open source tools for Vulnerability Static Analysis for containers. +Your application's Docker image may itself be based on Docker images that contain known +vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and +displays them in a merge request, you can use GitLab to audit your Docker-based apps. +By default, container scanning in GitLab is based on [Clair](https://github.com/quay/clair) and +[Klar](https://github.com/optiopay/klar), which are open-source tools for vulnerability static analysis in +containers. [GitLab's Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) +scans the containers and serves as a wrapper for Clair. -You can take advantage of Container Scanning by either [including the CI job](#configuration) in -your existing `.gitlab-ci.yml` file or by implicitly using -[Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning-ultimate) -that is provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the Container Scanning report, compares the found vulnerabilities -between the source and target branches, and shows the information right on the -merge request. - - - -## Contribute your scanner +NOTE: **Note:** +To integrate security scanners other than Clair and Klar into GitLab, see +[Security scanner integration](../../../development/integrations/secure.md). -The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. +You can enable container scanning by doing one of the following: -## Use cases +- [Include the CI job](#configuration) in your existing `.gitlab-ci.yml` file. +- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning-ultimate) + provided by [Auto DevOps](../../../topics/autodevops/index.md). -If you distribute your application with Docker, then there's a great chance -that your image is based on other Docker images that may in turn contain some -known vulnerabilities that could be exploited. +GitLab compares the found vulnerabilities between the source and target branches, and shows the +information directly in the merge request. -Having an extra job in your pipeline that checks for those vulnerabilities, -and the fact that they are displayed inside a merge request, makes it very easy -to perform audits for your Docker-based apps. + <!-- NOTE: The container scanning tool references the following heading in the code, so if you make a change to this heading, make sure to update the documentation URLs used in the @@ -44,33 +40,28 @@ to perform audits for your Docker-based apps. ## Requirements -To enable Container Scanning in your pipeline, 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. -- Docker `18.09.03` or higher installed on the machine where the Runners are - running. If you're using the shared Runners on GitLab.com, this is already - the case. -- To [build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd) - your Docker image to your project's Container Registry. - The name of the Docker image should use the following - [predefined environment variables](../../../ci/variables/predefined_variables.md) - as defined below: +To enable Container Scanning in your pipeline, you need the following: + +- [GitLab Runner](https://docs.gitlab.com/runner/) with the [Docker](https://docs.gitlab.com/runner/executors/docker.html) + or [Kubernetes](https://docs.gitlab.com/runner/install/kubernetes.html) executor. +- Docker `18.09.03` or higher installed on the same computer as the Runner. If you're using the + shared Runners on GitLab.com, then this is already the case. +- [Build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd) + your Docker image to your project's container registry. The name of the Docker image should use + the following [predefined environment variables](../../../ci/variables/predefined_variables.md): ```plaintext $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA ``` - These can be used directly in your `.gitlab-ci.yml` file: + You can use these directly in your `.gitlab-ci.yml` file: ```yaml build: - image: docker:19.03.8 + image: docker:19.03.11 stage: build services: - - docker:19.03.8-dind + - docker:19.03.11-dind variables: IMAGE_TAG: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: @@ -81,45 +72,40 @@ To enable Container Scanning in your pipeline, you need: ## Configuration -For GitLab 11.9 and later, to enable Container Scanning, you must -[include](../../../ci/yaml/README.md#includetemplate) the -[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) -that's provided as a part of your GitLab installation. -For GitLab versions earlier than 11.9, you can copy and use the job as defined -in that template. +How you enable Container Scanning depends on your GitLab version: -Add the following to your `.gitlab-ci.yml` file: +- GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) the + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) + that comes with your GitLab installation. +- GitLab versions earlier than 11.9: Copy and use the job from the + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + +To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the +following to your `.gitlab-ci.yml` file: ```yaml include: - template: Container-Scanning.gitlab-ci.yml ``` -The included template will: +The included template: -1. Create a `container_scanning` job in your CI/CD pipeline. -1. Pull the already built Docker image from your project's - [Container Registry](../../packages/container_registry/index.md) (see [requirements](#requirements)) - and scan it for possible vulnerabilities. +- Creates a `container_scanning` job in your CI/CD pipeline. +- Pulls the built Docker image from your project's [Container Registry](../../packages/container_registry/index.md) + (see [requirements](#requirements)) and scans it for possible vulnerabilities. -The results will be saved as a +GitLab saves the results as a [Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning-ultimate) -that you can later download and analyze. -Due to implementation limitations, we always take the latest Container Scanning -artifact available. Behind the scenes, the -[GitLab Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) -is used and runs the scans. +that you can download and analyze later. When downloading, you always receive the most-recent +artifact. -The following is a sample `.gitlab-ci.yml` that will build your Docker image, -push it to the Container Registry, and run Container Scanning: +The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the Container +Registry, and scans the containers: ```yaml variables: DOCKER_DRIVER: overlay2 -services: - - docker:19.03.8-dind - stages: - build - test @@ -127,6 +113,8 @@ stages: build: image: docker:stable stage: build + services: + - docker:19.03.11-dind variables: IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: @@ -141,11 +129,15 @@ include: ### Customizing the Container Scanning settings -You can change container scanning settings by using the [`variables`](../../../ci/yaml/README.md#variables) -parameter in your `.gitlab-ci.yml` to change [environment variables](#available-variables). +There may be cases where you want to customize how GitLab scans your containers. For example, you +may want to enable more verbose output from Clair or Klar, access a Docker registry that requires +authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables) +parameter in your `.gitlab-ci.yml` to set [environment variables](#available-variables). +The environment variables you set in your `.gitlab-ci.yml` overwrite those in +`Container-Scanning.gitlab-ci.yml`. -In the following example, we [include](../../../ci/yaml/README.md#include) the template and also -set the `CLAIR_OUTPUT` variable to `High`: +This example [includes](../../../ci/yaml/README.md#include) the Container Scanning template and +enables verbose output from Clair by setting the `CLAIR_OUTPUT` environment variable to `High`: ```yaml include: @@ -155,9 +147,6 @@ variables: CLAIR_OUTPUT: High ``` -The `CLAIR_OUTPUT` variable defined in the main `gitlab-ci.yml` will overwrite what's -defined in `Container-Scanning.gitlab-ci.yml`, changing the Container Scanning behavior. - <!-- NOTE: The container scanning tool references the following heading in the code, so if you" make a change to this heading, make sure to update the documentation URLs used in the" container scanning tool (https://gitlab.com/gitlab-org/security-products/analyzers/klar)" --> @@ -188,13 +177,9 @@ using environment variables. ### Overriding the Container Scanning template -CAUTION: **Deprecation:** -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. - -If you want to override the job definition (for example, change properties like -`variables`), you need to declare a `container_scanning` job after the -template inclusion and specify any additional keys under it. For example: +If you want to override the job definition (for example, to change properties like `variables`), you +must declare a `container_scanning` job after the template inclusion, and then +specify any additional keys. For example: ```yaml include: @@ -205,15 +190,20 @@ container_scanning: GIT_STRATEGY: fetch ``` +CAUTION: **Deprecated:** +GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic). +When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) +instead. + ### Vulnerability whitelisting -If you want to whitelist specific vulnerabilities, you'll need to: +To whitelist specific vulnerabilities, follow these steps: -1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions described in the - [overriding the Container Scanning template](#overriding-the-container-scanning-template) section of this document. -1. Define the whitelisted vulnerabilities in a YAML file named `clair-whitelist.yml` which must use the format described - in the [whitelist example file](https://github.com/arminc/clair-scanner/blob/v12/example-whitelist.yaml). -1. Add the `clair-whitelist.yml` file to the Git repository of your project. +1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in + [overriding the Container Scanning template](#overriding-the-container-scanning-template). +1. Define the whitelisted vulnerabilities in a YAML file named `clair-whitelist.yml`. This must use + the format described in the [whitelist example file](https://github.com/arminc/clair-scanner/blob/v12/example-whitelist.yaml). +1. Add the `clair-whitelist.yml` file to your project's Git repository. ### Running Container Scanning in an offline environment @@ -286,14 +276,13 @@ this with a pipeline means you won't have to do it manually each time. You can u ```yaml image: docker:stable -services: - - docker:19.03.8-dind - stages: - build build_latest_vulnerabilities: stage: build + services: + - docker:19.03.11-dind script: - docker pull arminc/clair-db:latest - docker tag arminc/clair-db:latest $CI_REGISTRY/namespace/clair-vulnerabilities-db @@ -339,11 +328,10 @@ The results are stored in `gl-container-scanning-report.json`. ## Reports JSON format -CAUTION: **Caution:** -The JSON report artifacts are not a public API of Container Scanning and their format may change in the future. +The Container Scanning tool emits a JSON report file. For more information, see the +[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json). -The Container Scanning tool emits a JSON report file. Here is an example of the report structure with all important parts of -it highlighted: +Here's an example Container Scanning report: ```json-doc { @@ -400,49 +388,6 @@ it highlighted: } ``` -CAUTION: **Deprecation:** -Beginning with GitLab 12.9, container scanning no longer reports `undefined` severity and confidence levels. - -Here is the description of the report file structure nodes and their meaning. All fields are mandatory to be present in -the report JSON unless stated otherwise. Presence of optional fields depends on the underlying analyzers being used. - -| Report JSON node | Description | -|------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `version` | Report syntax version used to generate this JSON. | -| `vulnerabilities` | Array of vulnerability objects. | -| `vulnerabilities[].id` | Unique identifier of the vulnerability. | -| `vulnerabilities[].category` | Where this vulnerability belongs (for example, SAST or Container Scanning). For Container Scanning, it will always be `container_scanning`. | -| `vulnerabilities[].message` | A short text that describes the vulnerability, it may include occurrence's specific information. Optional. | -| `vulnerabilities[].description` | A long text that describes the vulnerability. Optional. | -| `vulnerabilities[].cve` | (**DEPRECATED - use `vulnerabilities[].id` instead**) A fingerprint string value that represents a concrete occurrence of the vulnerability. It's used to determine whether two vulnerability occurrences are same or different. May not be 100% accurate. **This is NOT a [CVE](https://cve.mitre.org/)**. | -| `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. **Note:** Our current container scanning tool based on [klar](https://github.com/optiopay/klar) only provides the following levels: `Unknown`, `Low`, `Medium`, `High`, `Critical`. | -| `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. **Note:** Our current container scanning tool based on [klar](https://github.com/optiopay/klar) does not provide a confidence level, so this value is currently hardcoded to `Unknown`. | -| `vulnerabilities[].solution` | Explanation of how to fix the vulnerability. Optional. | -| `vulnerabilities[].scanner` | A node that describes the analyzer used to find this vulnerability. | -| `vulnerabilities[].scanner.id` | ID of the scanner as a snake_case string. | -| `vulnerabilities[].scanner.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | -| `vulnerabilities[].location.dependency` | A node that describes the dependency of a project where the vulnerability is located. | -| `vulnerabilities[].location.dependency.package` | A node that provides the information on the package where the vulnerability is located. | -| `vulnerabilities[].location.dependency.package.name` | Name of the package where the vulnerability is located. | -| `vulnerabilities[].location.dependency.version` | Version of the vulnerable package. Optional. | -| `vulnerabilities[].location.operating_system` | The operating system that contains the vulnerable package. | -| `vulnerabilities[].location.image` | The Docker image that was analyzed. | -| `vulnerabilities[].identifiers` | An ordered array of references that identify a vulnerability on internal or external DBs. | -| `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`). | -| `vulnerabilities[].identifiers[].name` | Name of the identifier for display purpose. | -| `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purpose. | -| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. | -| `vulnerabilities[].links` | An array of references to external documentation pieces or articles that describe the vulnerability further. Optional. | -| `vulnerabilities[].links[].name` | Name of the vulnerability details link. Optional. | -| `vulnerabilities[].links[].url` | URL of the vulnerability details document. Optional. | -| `remediations` | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. Empty if no remediations provided by an underlying analyzer. | -| `remediations[].fixes` | An array of strings that represent references to vulnerabilities fixed by this particular remediation. | -| `remediations[].fixes[].id` | The ID of a fixed vulnerability. | -| `remediations[].fixes[].cve` | (**DEPRECATED - use `remediations[].fixes[].id` instead**) A string value that describes a fixed vulnerability in the same format as `vulnerabilities[].cve`. | -| `remediations[].summary` | Overview of how the vulnerabilities have been fixed. | -| `remediations[].diff` | base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). | - ## Security Dashboard The [Security Dashboard](../security_dashboard/index.md) shows you an overview of all @@ -473,7 +418,7 @@ Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vu ## Troubleshooting -### docker: Error response from daemon: failed to copy xattrs +### `docker: Error response from daemon: failed to copy xattrs` When the GitLab Runner uses the Docker executor and NFS is used (for example, `/var/lib/docker` is on an NFS mount), Container Scanning might fail with @@ -486,4 +431,4 @@ docker: Error response from daemon: failed to copy xattrs: failed to set xattr " This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt"). To prevent the error, ensure the Docker version that the Runner is using is `18.09.03` or higher. For more information, see -[issue #10241](https://gitlab.com/gitlab-org/gitlab/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). +[issue #10241](https://gitlab.com/gitlab-org/gitlab/-/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index cfc679f13a7..256daae46d7 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,10 +1,13 @@ --- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- # Dynamic Application Security Testing (DAST) **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. NOTE: **4 of the top 6 attacks were application based.** Download our whitepaper, @@ -142,7 +145,14 @@ the site during a scan could lead to inaccurate results. ### Authentication -It's also possible to authenticate the user before performing the DAST checks: +It's also possible to authenticate the user before performing the DAST checks. + +Create masked variables to pass the credentials that DAST will use. +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`. + +Other variables that are related to authenticated scans are: ```yaml include: @@ -151,8 +161,6 @@ include: variables: DAST_WEBSITE: https://example.com DAST_AUTH_URL: https://example.com/sign-in - DAST_USERNAME: john.doe@example.com - DAST_PASSWORD: john-doe-password DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form 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 @@ -439,7 +447,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | Environment variable | Required | Description | |-----------------------------| -----------|--------------------------------------------------------------------------------| -| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address from which to download the analyzer. | +| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address from which to download the analyzer. | | `DAST_WEBSITE` | no| The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_API_SPECIFICATION` | no | The API specification to import. `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_AUTH_URL` | no | The authentication URL of the website to scan. Not supported for API scans. | @@ -455,7 +463,15 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_API_HOST_OVERRIDE` | no | Used to override domains defined in API specification files. | | `DAST_EXCLUDE_RULES` | no | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from the scan report. Currently, excluded rules will get executed but the alerts from them will be suppressed. 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`. | | `DAST_REQUEST_HEADERS` | no | Set to a comma-separated list of request header names and values. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_ZAP_USE_AJAX_SPIDER` | no | Use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_DEBUG` | no | Enable debug message output. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_SPIDER_MINS` | no | The maximum duration of the spider scan in minutes. Set to zero for unlimited. Defaults to one minute, or unlimited when the scan is a full scan. | +| `DAST_HTML_REPORT` | no | The file name of the HTML report written at the end of a scan. | +| `DAST_MARKDOWN_REPORT` | no | The file name of the Markdown report written at the end of a scan. | +| `DAST_XML_REPORT` | no | The file name of the XML report written at the end of a scan. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | no | Include alpha passive and active scan rules. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_USE_AJAX_SPIDER` | no | Use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_ZAP_CLI_OPTIONS` | no | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | +| `DAST_ZAP_LOG_CONFIGURATION` | no | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG` | ### DAST command-line options @@ -472,8 +488,9 @@ dast: - /analyze --help ``` -You must then overwrite the `script` command to pass in the appropriate argument. -For example, debug messages can be enabled by using `-d`, as shown in the following configuration: +You must then overwrite the `script` command to pass in the appropriate +argument. For example, passive scanning can be delayed using option `-D`. The following +configuration delays passive scanning by five minutes: ```yaml include: @@ -482,14 +499,14 @@ include: dast: script: - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -d -t $DAST_WEBSITE + - /analyze -D 300 -t $DAST_WEBSITE ``` ### Custom ZAProxy configuration -The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_245801885). +The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_245801885). Many key/values for `-config` remain undocumented, but there is an untested list of -[possible keys](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_244981023). +[possible keys](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_244981023). Note that these options are not supported by DAST, and may break the DAST scan when used. An example of how to rewrite the Authorization header value with `TOKEN` follows: @@ -497,10 +514,8 @@ when used. An example of how to rewrite the Authorization header value with `TOK include: template: DAST.gitlab-ci.yml -dast: - script: - - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -z"-config replacer.full_list\(0\).description=auth -config replacer.full_list\(0\).enabled=true -config replacer.full_list\(0\).matchtype=REQ_HEADER -config replacer.full_list\(0\).matchstr=Authorization -config replacer.full_list\(0\).regex=false -config replacer.full_list\(0\).replacement=TOKEN" -t $DAST_WEBSITE +variables: + DAST_ZAP_CLI_OPTIONS: "-config replacer.full_list(0).description=auth -config replacer.full_list(0).enabled=true -config replacer.full_list(0).matchtype=REQ_HEADER -config replacer.full_list(0).matchstr=Authorization -config replacer.full_list(0).regex=false -config replacer.full_list(0).replacement=TOKEN" ``` ### Cloning the project's repository @@ -508,6 +523,29 @@ dast: The DAST job does not require the project's repository to be present when running, so by default [`GIT_STRATEGY`](../../../ci/yaml/README.md#git-strategy) is set to `none`. +### Debugging DAST jobs + +A DAST job has two executing processes: + +- The ZAP server. +- 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. +For details on using variables, see [Overriding the DAST template](#overriding-the-dast-template). + +Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. +The following table outlines examples of values that can be set and the effect that they have on the output that is logged. +Multiple values can be specified, separated by semicolons. + +| Log configuration value | Effect | +|-------------------------------------------------- | ----------------------------------------------------------------- | +| `log4j.rootLogger=DEBUG` | Enable all debug logging statements. | +| `log4j.logger.org.apache.commons.httpclient=DEBUG` | Log every HTTP request and response made by the ZAP server. | +| `log4j.logger.com.crawljax=DEBUG` | Enable Ajax Crawler debug logging statements. | +| `log4j.logger.org.parosproxy.paros=DEBUG` | Enable ZAP server proxy debug logging statements. | +| `log4j.logger.org.zaproxy.zap=DEBUG` | Enable debug logging statements of the general ZAP server code. | + ## Running DAST in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access @@ -568,7 +606,8 @@ Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override th ## Reports -The DAST job can emit various reports. +The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in +Markdown, HTML, and XML. For more information, see the [schema for DAST reports](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json). ### List of URLs scanned @@ -593,24 +632,22 @@ There are two formats of data in the JSON report that are used side by side: ### Other formats -Reports can also be generated in Markdown, HTML, and XML. - -Reports can be published as artifacts using the following configuration: +Reports can also be generated in Markdown, HTML, and XML. These can be published as artifacts using the following configuration: ```yaml include: template: DAST.gitlab-ci.yml dast: - script: - - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -r report.html -w report.md -x report.xml -t $DAST_WEBSITE - - cp /zap/wrk/report.{html,md,xml} "$PWD" + variables: + DAST_HTML_REPORT: report.html + DAST_MARKDOWN_REPORT: report.md + DAST_XML_REPORT: report.xml artifacts: paths: - - report.html - - report.md - - report.xml + - $DAST_HTML_REPORT + - $DAST_MARKDOWN_REPORT + - $DAST_XML_REPORT - gl-dast-report.json ``` @@ -622,18 +659,18 @@ vulnerabilities in your groups, projects and pipelines. Read more about the ## Bleeding-edge vulnerability definitions -ZAProxy first creates rules in the `alpha` class. After a testing period with the -community, they are promoted to `beta`. DAST uses `beta` definitions by default. -To request `alpha` definitions, use `-a` as shown in the following configuration: +ZAP first creates rules in the `alpha` class. After a testing period with +the community, they are promoted to `beta`. DAST uses `beta` definitions by +default. To request `alpha` definitions, use the +`DAST_INCLUDE_ALPHA_VULNERABILITIES` environment variable as shown in the +following configuration: ```yaml include: template: DAST.gitlab-ci.yml -dast: - script: - - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -a -t $DAST_WEBSITE +variables: + DAST_INCLUDE_ALPHA_VULNERABILITIES: true ``` ## Interacting with the vulnerabilities @@ -685,16 +722,14 @@ This results in the following error: ``` Fortunately, it's straightforward to increase the amount of memory available -for DAST by overwriting the `script` key in the DAST template: +for DAST by using the `DAST_ZAP_CLI_OPTIONS` environment variable: ```yaml include: - template: DAST.gitlab-ci.yml -dast: - script: - - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -t $DAST_WEBSITE -z"-Xmx3072m" +variables: + DAST_ZAP_CLI_OPTIONS: "-Xmx3072m" ``` Here, DAST is being allocated 3072 MB. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 73d2cfeaf00..1f730e5f205 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -1,6 +1,13 @@ +--- +type: reference, howto +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Dependency List **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. The Dependency list allows you to see your project's dependencies, and key details about them, including their known vulnerabilities. To see it, @@ -24,8 +31,8 @@ Dependencies are displayed with the following information: | Field | Description | | --------- | ----------- | | Component | The dependency's name and version | -| Packager | The packager used to install the depedency | -| Location | A link to the packager-specific lockfile in your project that declared the dependency | +| Packager | The packager used to install the dependency | +| Location | A link to the packager-specific lock file in your project that declared the dependency | | License | Links to dependency's software licenses | Dependencies shown are initially sorted by the severity of their known vulnerabilities, if any. They @@ -39,7 +46,7 @@ vulnerability, its severity and description then appears below it. ## Licenses -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10536) in GitLab Ultimate 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) will be displayed on this page. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 53462cf232e..84ec0ec976d 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,10 +1,13 @@ --- type: reference, howto +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Dependency Scanning **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. +> [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 while you're developing and testing your applications, such as when your @@ -50,20 +53,27 @@ Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [ ## Supported languages and package managers -The following languages and dependency managers are supported. - -| Language (package managers) | Supported | Scan tool(s) | -|----------------------------- | --------- | ------------ | -| Java ([Gradle](https://gradle.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| Java ([Maven](https://maven.apache.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | -| PHP ([Composer](https://getcomposer.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| Python ([pip](https://pip.pypa.io/en/stable/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| Python ([Pipfile](https://pipenv.kennethreitz.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available | -| Python ([poetry](https://python-poetry.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/7006 "Support Poetry in Dependency Scanning")) | not available | -| Ruby ([gem](https://rubygems.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | -| Scala ([sbt](https://www.scala-sbt.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| Go ([Go Modules](https://github.com/golang/go/wiki/Modules)) | yes ([alpha](https://gitlab.com/gitlab-org/gitlab/issues/7132)) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +GitLab relies on [`rules`](../../../ci/yaml/README.md#rules) to start relevant analyzers depending on the languages detected in the repository. +The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. + +The following languages and dependency managers are supported: + +| Language (package managers) | Supported files | Scan tool(s) | +|----------------------------- | --------------- | ------------ | +| 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://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) | +| PHP ([Composer](https://getcomposer.org/)) | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Python ([setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/)) | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Ruby ([Bundler](https://bundler.io/)) | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | +| Scala ([sbt](https://www.scala-sbt.org/)) | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | + +Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. + +| Language (package managers) | Supported files | Scan tool(s) | Issue | +|----------------------------- | --------------- | ------------ | ----- | +| Python ([Poetry](https://poetry.eustace.io/)) | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/issues/7006) | +| Python ([Pipenv](https://pipenv.pypa.io/en/latest/)) | `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#11756](https://gitlab.com/gitlab-org/gitlab/-/issues/11756) | ## Contribute your scanner @@ -145,7 +155,7 @@ The following variables allow configuration of global dependency scanning settin | `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | | `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. | +| `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"` | #### Configuring Docker-in-Docker orchestrator @@ -173,9 +183,9 @@ The following variables are used for configuring specific analyzers (used for a | `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. | | `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. | | `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | -| `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_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)| | `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`. | @@ -195,7 +205,7 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m ### Enabling Docker-in-Docker -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12487) in GitLab Ultimate 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12487) in GitLab Ultimate 12.5. If needed, you can enable Docker-in-Docker to restore the Dependency Scanning behavior that existed prior to GitLab 13.0. Follow these steps to do so: @@ -244,11 +254,10 @@ the [Dependency List](../dependency_list/index.md). ## Reports JSON format -CAUTION: **Caution:** -The JSON report artifacts are not a public API of Dependency Scanning and their format may change in the future. +The Dependency Scanning tool emits a JSON report file. For more information, see the +[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json). -The Dependency Scanning tool emits a JSON report file. Here is an example of the report structure with all important parts of -it highlighted: +Here's an example Dependency Scanning report: ```json-doc { @@ -357,49 +366,6 @@ it highlighted: } ``` -CAUTION: **Deprecation:** -Beginning with GitLab 12.9, dependency scanning no longer reports `undefined` severity and confidence levels. - -This table describes the report file structure nodes and their meaning. All fields are mandatory to be present in -the report JSON, unless stated otherwise. The presence of optional fields depends on the underlying analyzers used. - -| Report JSON node | Description | -|------------------------------------------------------|-------------| -| `version` | Report syntax version used to generate this JSON. | -| `vulnerabilities` | Array of vulnerability objects. | -| `vulnerabilities[].id` | Unique identifier of the vulnerability. | -| `vulnerabilities[].category` | Where this vulnerability belongs, such as SAST or Dependency Scanning. For Dependency Scanning, it will always be `dependency_scanning`. | -| `vulnerabilities[].name` | Name of the vulnerability. Must not include the occurrence's specific information. Optional. | -| `vulnerabilities[].message` | A short text that describes the vulnerability. May include occurrence's specific information. Optional. | -| `vulnerabilities[].description` | A long text that describes the vulnerability. Optional. | -| `vulnerabilities[].cve` | (**DEPRECATED - use `vulnerabilities[].id` instead**) A fingerprint string value that represents a concrete occurrence of the vulnerability. Used to determine whether two vulnerability occurrences are same or different. May not be 100% accurate. **This is NOT a [CVE](https://cve.mitre.org/)**. | -| `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. | -| `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. | -| `vulnerabilities[].solution` | Explanation of how to fix the vulnerability. Optional. | -| `vulnerabilities[].scanner` | A node that describes the analyzer used to find this vulnerability. | -| `vulnerabilities[].scanner.id` | ID of the scanner as a `snake_case` string. | -| `vulnerabilities[].scanner.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | -| `vulnerabilities[].location.file` | Path to the dependencies file (such as `yarn.lock`). Optional. | -| `vulnerabilities[].location.dependency` | A node that describes the dependency of a project where the vulnerability is located. | -| `vulnerabilities[].location.dependency.package` | A node that provides the information on the package where the vulnerability is located. | -| `vulnerabilities[].location.dependency.package.name` | Name of the package where the vulnerability is located. Optional. | -| `vulnerabilities[].location.dependency.version` | Version of the vulnerable package. Optional. | -| `vulnerabilities[].identifiers` | An ordered array of references that identify a vulnerability on internal or external DBs. | -| `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (such as `gemnasium` for [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/)). | -| `vulnerabilities[].identifiers[].name` | Name of the identifier for display purpose. | -| `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purpose. | -| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. | -| `vulnerabilities[].links` | An array of references to external documentation pieces or articles that describe the vulnerability further. Optional. | -| `vulnerabilities[].links[].name` | Name of the vulnerability details link. Optional. | -| `vulnerabilities[].links[].url` | URL of the vulnerability details document. Optional. | -| `remediations` | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. Empty if no remediations provided by an underlying analyzer. | -| `remediations[].fixes` | An array of strings that represent references to vulnerabilities fixed by this particular remediation. | -| `remediations[].fixes[].id` | The ID of a fixed vulnerability. | -| `remediations[].fixes[].cve` | (**DEPRECATED - use `remediations[].fixes[].id` instead**) A string value that describes a fixed vulnerability in the same format as `vulnerabilities[].cve`. | -| `remediations[].summary` | Overview of how the vulnerabilities have been fixed. | -| `remediations[].diff` | Base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). | - ## Versioning and release process Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). @@ -498,42 +464,6 @@ BUNDLER_AUDIT_ADVISORY_DB_REF_NAME: "master" BUNDLER_AUDIT_ADVISORY_DB_URL: "gitlab.example.com/ruby-advisory-db.git" ``` -#### Java (Maven) projects - -When using self-signed certificates, add the following job section to the `.gitlab-ci.yml`: - -```yaml -gemnasium-maven-dependency_scanning: - variables: - MAVEN_CLI_OPTS: "-s settings.xml -Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.ignore.validity.dates=true" -``` - -#### Java (Gradle) projects - -When using self-signed certificates, add the following job section to the `.gitlab-ci.yml`: - -```yaml -gemnasium-maven-dependency_scanning: - before_script: - - echo -n | openssl s_client -connect maven-repo.example.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/internal.crt - - keytool -importcert -file /tmp/internal.crt -cacerts -storepass changeit -noprompt -``` - -This adds the self-signed certificates of your Maven repository to the Java KeyStore of the analyzer's Docker image. - -#### Scala (sbt) projects - -When using self-signed certificates, add the following job section to the `.gitlab-ci.yml`: - -```yaml -gemnasium-maven-dependency_scanning: - before_script: - - echo -n | openssl s_client -connect maven-repo.example.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/internal.crt - - keytool -importcert -file /tmp/internal.crt -cacerts -storepass changeit -noprompt -``` - -This adds the self-signed certificates of your Maven repository to the Java KeyStore of the analyzer's Docker image. - #### Python (setuptools) When using self-signed certificates for your private PyPi repository, no extra job configuration (aside @@ -543,23 +473,23 @@ ensure that it can reach your private repository. Here is an example configurati 1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each dependency in the `install_requires` list: - ```python - install_requires=['pyparsing>=2.0.3'], - dependency_links=['https://pypi.example.com/simple/pyparsing'], - ``` + ```python + install_requires=['pyparsing>=2.0.3'], + dependency_links=['https://pypi.example.com/simple/pyparsing'], + ``` 1. Fetch the certificate from your repository URL and add it to the project: - ```bash - echo -n | openssl s_client -connect pypi.example.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt - ``` + ```shell + echo -n | openssl s_client -connect pypi.example.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt + ``` 1. Point `setup.py` at the newly downloaded certificate: - ```python - import setuptools.ssl_support - setuptools.ssl_support.cert_paths = ['internal.crt'] - ``` + ```python + import setuptools.ssl_support + setuptools.ssl_support.cert_paths = ['internal.crt'] + ``` ## Limitations @@ -579,9 +509,9 @@ As a workaround, remove the [`retire.js`](analyzers.md#selecting-specific-analyz ## Troubleshooting -### Error response from daemon: error processing tar file: docker-tar: relocation error +### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the Dependency Scanning job is `19.03.00`. Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in -[this issue](https://gitlab.com/gitlab-org/gitlab/issues/13830#note_211354992 "Current SAST container fails"). +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). diff --git a/doc/user/application_security/img/security_configuration_page_v13_1.png b/doc/user/application_security/img/security_configuration_page_v13_1.png Binary files differindex 0147084f705..176c64a9e87 100644 --- a/doc/user/application_security/img/security_configuration_page_v13_1.png +++ b/doc/user/application_security/img/security_configuration_page_v13_1.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 differnew file mode 100644 index 00000000000..536fc4f10f7 --- /dev/null +++ b/doc/user/application_security/img/vulnerability-check_v13_0.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index eefa52eb5c3..49580f494a2 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -17,14 +17,15 @@ For an overview of application security with GitLab, see ## Quick start -Get started quickly with Dependency Scanning, License Scanning, and Static Application Security -Testing (SAST) by adding the following to your `.gitlab-ci.yml`: +Get started quickly with Dependency Scanning, License Scanning, Static Application Security +Testing (SAST), and Secret Detection by adding the following to your `.gitlab-ci.yml`: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml - template: License-Scanning.gitlab-ci.yml - template: SAST.gitlab-ci.yml + - template: Secret-Detection.gitlab-ci.yml ``` To add Dynamic Application Security Testing (DAST) scanning, add the following to your @@ -64,14 +65,27 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [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. | +## Security Scanning with Auto DevOps + +When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. + +- [Auto SAST](../../topics/autodevops/stages.md#auto-sast-ultimate) +- [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection-ultimate) +- [Auto DAST](../../topics/autodevops/stages.md#auto-dast-ultimate) +- [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning-ultimate) +- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance-ultimate) +- [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning-ultimate) + +While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customizing-gitlab-ciyml). + ## Maintenance and update of the vulnerabilities database The scanning tools and vulnerabilities database are updated regularly. | Secure scanning tool | Vulnerabilities database updates | |:-------------------------------------------------------------|-------------------------------------------| -| [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Rubygems), `retire.js` (for NPM packages), and `gemnasium` (GitLab's own tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` Docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (GitLab's own tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | @@ -82,7 +96,7 @@ tools overrides these tags. The Docker images are updated to match the previous GitLab releases, so users automatically get the latest versions of the scanning tools without having to do anything. There are some known issues with this approach, however, and there is a -[plan to resolve them](https://gitlab.com/gitlab-org/gitlab/issues/9725). +[plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). ## Interacting with the vulnerabilities @@ -95,7 +109,7 @@ information with several options: - [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability styles it in strikethrough. - [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and - description prepopulated with information from the vulnerability report. By default, such issues + description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../project/issues/confidential_issues.md). - [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities, a solution is provided for how to fix the vulnerability. @@ -142,7 +156,7 @@ button from within the vulnerability modal, or by using the action buttons to th a vulnerability row in the group security dashboard. This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and prepopulates it with some useful information taken from the vulnerability +vulnerability came from, and pre-populates it with some useful information taken from the vulnerability report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on it. @@ -153,7 +167,7 @@ to the name. ### Solutions for vulnerabilities (auto-remediation) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. The following scanners are supported: @@ -178,7 +192,7 @@ generated by GitLab. To apply the fix: #### Creating a merge request from a vulnerability -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. In certain cases, GitLab allows you to create a merge request that automatically remediates the vulnerability. Any vulnerability that has a @@ -192,7 +206,7 @@ Click this button to create a merge request to apply the solution onto the sourc ## Security approvals in merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. Merge Request Approvals can be configured to require approval from a member of your security team when a merge request would introduce one of the following security issues: @@ -216,9 +230,15 @@ rating. ### Enabling Security Approvals within a project -To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) +To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#adding--editing-a-default-approval-rule) 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. +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. Click **Add approval rule**, or **Edit**. + - Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). + + Once this group is added to your project, the approval rule is enabled for all merge requests. @@ -236,7 +256,7 @@ An approval is optional when a security report: ## Enabling License Approvals within a project -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. To enable License Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) must be created with the case-sensitive name `License-Check`. This approval group must be set @@ -299,7 +319,7 @@ under your project's settings: ## Outdated security reports -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4913) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4913) in GitLab 12.7. When a security report generated for a merge request becomes outdated, the merge request shows a warning message in the security widget and prompts you to take an appropriate action. diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 3deb38902f2..9a2f8768fc0 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Offline environments @@ -49,7 +52,7 @@ you must update each of the scanners to either reference a different, internally-hosted registry or provide access to the individual scanner images. You must also ensure that your app has access to common package repositories -that are not hosted on GitLab.com, such as npm, yarn, or rubygems. Packages +that are not hosted on GitLab.com, such as npm, yarn, or Ruby gems. Packages from these repos can be obtained by temporarily connecting to a network or by mirroring the packages inside your own offline network. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 08078a66719..0aa20bf4373 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -1,3 +1,9 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # SAST Analyzers **(ULTIMATE)** SAST relies on underlying third party tools that are wrapped into what we call @@ -139,7 +145,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Analyzers Data -| Property \ Tool | Apex | Bandit | Brakeman | ESLint security | Find Sec Bugs | Flawfinder | Gosec | Kubesec Scanner | NodeJsScan | Php CS Security Audit | Security code Scan (.NET) | Sobelow | TSLint Security | +| Property \ Tool | Apex | Bandit | Brakeman | ESLint security | Find Sec Bugs | Flawfinder | Gosec | Kubesec Scanner | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | TSLint Security | | --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | :-------------: | | Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | ✓ | | Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 370c6d0e8e7..a5497e3d38c 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,10 +1,13 @@ --- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- # Static Application Security Testing (SAST) **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. NOTE: **4 of the top 6 attacks were application based.** Download our whitepaper, @@ -71,10 +74,11 @@ The following table shows which languages, package managers and frameworks are s | .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://dwheeler.com/flawfinder/) | 10.7 | +| 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 | | Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | @@ -196,7 +200,7 @@ jobs. #### Enabling Kubesec analyzer -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12752) in GitLab Ultimate 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab Ultimate 12.6. You need to set `SCAN_KUBERNETES_MANIFESTS` to `"true"` to enable the Kubesec analyzer. In `.gitlab-ci.yml`, define: @@ -285,8 +289,8 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | Environment variable | Default value | Description | |-------------------------|---------------|-------------| -| `SAST_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. | -| `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) | +| `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/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | | `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. | @@ -313,19 +317,22 @@ Some analyzers can be customized with environment variables. | Environment variable | Analyzer | Description | |-----------------------------|----------|-------------| -| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `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). | +| `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. | +| `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. | #### Custom environment variables @@ -342,11 +349,10 @@ analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, ## Reports JSON format -CAUTION: **Caution:** -The JSON report artifacts are not a public API of SAST and their format may change in the future. +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 SAST tool emits a JSON report file. Here is an example of the report structure with all important parts of -it highlighted: +Here's an example SAST report: ```json-doc { @@ -421,40 +427,6 @@ it highlighted: } ``` -CAUTION: **Deprecation:** -Beginning with GitLab 12.9, SAST no longer reports `undefined` severity and confidence levels. - -Here is the description of the report file structure nodes and their meaning. All fields are mandatory in -the report JSON unless stated otherwise. Presence of optional fields depends on the underlying analyzers being used. - -| Report JSON node | Function | -|-----------------------------------------|----------| -| `version` | Report syntax version used to generate this JSON. | -| `vulnerabilities` | Array of vulnerability objects. | -| `vulnerabilities[].id` | Unique identifier of the vulnerability. | -| `vulnerabilities[].category` | Where this vulnerability belongs (such as SAST, Dependency Scanning). For SAST, it will always be `sast`. | -| `vulnerabilities[].name` | Name of the vulnerability. Must not include the occurrence's specific information. Optional. | -| `vulnerabilities[].message` | A short text that describes the vulnerability, it may include the occurrence's specific information. Optional. | -| `vulnerabilities[].description` | A long text that describes the vulnerability. Optional. | -| `vulnerabilities[].cve` | (**DEPRECATED - use `vulnerabilities[].id` instead**) A fingerprint string value that represents a concrete occurrence of the vulnerability. It's used to determine whether two vulnerability occurrences are same or different. May not be 100% accurate. **This is NOT a [CVE](https://cve.mitre.org/)**. | -| `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. | -| `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. | -| `vulnerabilities[].solution` | Explanation of how to fix the vulnerability. Optional. | -| `vulnerabilities[].scanner` | A node that describes the analyzer used to find this vulnerability. | -| `vulnerabilities[].scanner.id` | ID of the scanner as a snake_case string. | -| `vulnerabilities[].scanner.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | -| `vulnerabilities[].location.file` | Path to the file where the vulnerability is located. Optional. | -| `vulnerabilities[].location.start_line` | The first line of the code affected by the vulnerability. Optional. | -| `vulnerabilities[].location.end_line` | The last line of the code affected by the vulnerability. Optional. | -| `vulnerabilities[].location.class` | If specified, provides the name of the class where the vulnerability is located. Optional. | -| `vulnerabilities[].location.method` | If specified, provides the name of the method where the vulnerability is located. Optional. | -| `vulnerabilities[].identifiers` | An ordered array of references that identify a vulnerability on internal or external databases. | -| `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (like `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). | -| `vulnerabilities[].identifiers[].name` | Name of the identifier for display purposes. | -| `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purposes. | -| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. | - ## Secret detection Learn more about [Secret Detection](../secret_detection). @@ -513,7 +485,6 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2 registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2 registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2 registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/go-ast-scanner:2 registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2 registry.gitlab.com/gitlab-org/security-products/analyzers/kubesec:2 registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2 @@ -553,9 +524,9 @@ security reports without requiring internet access. ## Troubleshooting -### Error response from daemon: error processing tar file: docker-tar: relocation error +### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the SAST job is `19.03.0`. Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in -[this issue](https://gitlab.com/gitlab-org/gitlab/issues/13830#note_211354992 "Current SAST container fails"). +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 74dd3c89984..85933c31a34 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Secret Detection **(ULTIMATE)** @@ -26,18 +29,30 @@ GitLab displays identified secrets as part of the SAST reports visibly in a few ## Use cases -- Detecting accidental commit of secrets like keys, passwords, and API tokens. +- Detecting unintentional commit of secrets like keys, passwords, and API tokens. - Performing a single or recurring scan of the full history of your repository for secrets. +## Requirements + +To run Secret Detection jobs, by default, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. +If you're using the shared Runners on GitLab.com, this is enabled by default. + +CAUTION: **Caution:** Our Secret Detection jobs currently expect a Linux container type. Windows containers are not yet supported. + +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. + ## Configuration -If you already have SAST enabled for your app, you don’t need to take any action to benefit from this -new feature. It is also included in the Auto DevOps default configuration. +NOTE: **Note:** +With GitLab 13.1 Secret Detection was split into its own CI/CD template. -Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L180) -during the `sast` job. It runs regardless of the programming -language of your app, and you don't need to change your -CI/CD configuration file to enable it. Results are available in the SAST report. +Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) +during the `secret-detection` job. It runs regardless of the programming +language of your app. The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) checks. @@ -47,15 +62,99 @@ with a dollar sign (`$`) as this likely indicates the password being used is an variable. For example, `https://username:$password@example.com/path/to/repo` won't be detected, whereas `https://username:password@example.com/path/to/repo` would be detected. +NOTE: **Note:** +You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection-ultimate) +provided by [Auto DevOps](../../../topics/autodevops/index.md). + +To enable Secret Detection for GitLab 13.1 and later, you must include the `Secret-Detection.gitlab-ci.yml` template that’s provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined in that template. + +Add the following to your `.gitlab-ci.yml` file: + +```yaml +include: + - template: Secret-Detection.gitlab-ci.yml +``` + +The included template creates Secret Detection jobs in your CI/CD pipeline and scans +your project's source code for secrets. + +The results are saved as a +[Secret Detection report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssecret_detection-ultimate) +that you can later download and analyze. Due to implementation limitations, we +always take the latest Secret Detection artifact available. + +### Using the SAST Template + +Prior to GitLab 13.1, Secret Detection was part of [SAST configuration](../sast#configuration). +If you already have SAST enabled for your app configured before GitLab 13.1, +you don't need to manually configure it. + +CAUTION: **Planned Deprecation:** +In a future GitLab release, configuring Secret Detection with the SAST template will be deprecated. Please begin using `Secret-Detection.gitlab-ci.yml` +to prevent future issues. We have made a +[video to guide you through the process of transitioning](https://www.youtube.com/watch?v=W2tjcQreDwQ) +to this new template. + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=W2tjcQreDwQ">Walkthrough of historical secret scan</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/W2tjcQreDwQ" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +When using the SAST template, Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L180) +during the `sast` job. It runs regardless of the programming +language of your app, and you don't need to change your +CI/CD configuration file to enable it. Results are available in the SAST report. + +### Customizing settings + +The Secret Detection scan settings can be changed through [environment variables](#available-variables) +by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. + +To override a job definition, (for example, change properties like `variables` or `dependencies`), +declare a job with the same name as the SAST job to override. Place this new job after the template +inclusion and specify any additional keys under it. + +In the following example, we include the Secret Detection template and at the same time we +override the `secret-scan` job with the `SECRET_DETECTION_HISTORIC_SCAN` variable to `true`: + +```yaml +include: + - template: Secret-Detection.gitlab-ci.yml + +secrets-scan: + variables: + SECRET_DETECTION_HISTORIC_SCAN: true +``` + +Because the template is [evaluated before](../../../ci/yaml/README.md#include) +the pipeline configuration, the last mention of the variable takes precedence. + +CAUTION: **Deprecation:** +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. + +#### Available variables + +Secret Detection can be customized by defining available variables: + +| Environment variable | Default value | Description | +|-------------------------|---------------|-------------| +| `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | +| `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | +| `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | + ## Full History Secret Scan -GitLab 12.11 introduced support for scanning the full history of a reposity. This new functionality +GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality is particularly useful when you are enabling Secret Detection in a repository for the first time and you want to perform a full secret scan. Running a secret scan on the full history can take a long time, especially for larger repositories with lengthy Git histories. We recommend not setting this variable -as part of your normal job defintion. +as part of your normal job definition. -A new configuration variable ([`SAST_GITLEAKS_HISTORIC_SCAN`](../sast/#vulnerability-filters)) +A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](../sast/#vulnerability-filters)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a 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 differnew file mode 100644 index 00000000000..0dfe7b637cd --- /dev/null +++ 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_0.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_0.png Binary files differindex c788e2165ad..4c7b5cc724f 100644 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_0.png +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_0.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png Binary files differindex bb88b7f371c..878bb83c2a2 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 2988b3642ef..60798b9c921 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -36,7 +36,7 @@ To use the instance, group, project, or pipeline security dashboard: ## Pipeline Security -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against. @@ -49,7 +49,7 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j ## Project Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. At the project level, the Security Dashboard displays the latest security reports for your project. Use it to find and fix vulnerabilities. @@ -70,7 +70,7 @@ of thousands of vulnerabilities. Do not close the page until the download finish ## Group Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. The group Security Dashboard gives an overview of the vulnerabilities of all the projects in a group and its subgroups. @@ -120,9 +120,24 @@ vulnerabilities are not included either. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +### Export vulnerabilities + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +You can export all your vulnerabilities as CSV by clicking the **{upload}** **Export** button +located at the top right of the **Group Security Dashboard**. After the report builds, the CSV +report downloads to your local machine. The report contains all vulnerabilities for the projects +defined in the **Group Security Dashboard**, as filters don't apply to the export function. + +NOTE: **Note:** +It may take several minutes for the download to start if your project contains thousands of +vulnerabilities. Don't close the page until the download finishes. + + + ## Instance Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6953) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6953) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. At the instance level, the Security Dashboard displays the vulnerabilities present in all of the projects that you have added to it. It includes all diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 7bd148edd15..434048896fe 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -1,14 +1,18 @@ --- type: reference, howto +stage: Defend +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Threat Monitoring **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -The **Threat Monitoring** page provides metrics for the GitLab -application runtime security features. You can access these metrics by -navigating to your project's **Security & Compliance > Threat Monitoring** page. +The **Threat Monitoring** page provides metrics and policy management +for the GitLab application runtime security features. You can access +these by navigating to your project's **Security & Compliance > Threat +Monitoring** page. GitLab supports statistics for the following security features: @@ -42,7 +46,7 @@ investigate it for potential threats by ## Container Network Policy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. The **Container Network Policy** section provides packet flow metrics for your application's Kubernetes namespace. This section has the following @@ -74,3 +78,41 @@ about your packet flow: If a significant percentage of packets is dropped, you should investigate it for potential threats by [examining the Cilium logs](../../clusters/applications.md#install-cilium-using-gitlab-cicd). + +## Container Network Policy management + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3328) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +The **Threat Monitoring** page's **Policy** tab displays deployed +network policies for all available environments. You can check a +network policy's `yaml` manifest and toggle the policy's enforcement +status. This section has the following prerequisites: + +- Your project contains at least one [environment](../../../ci/environments/index.md) +- You've [installed Cilium](../../clusters/applications.md#install-cilium-using-gitlab-cicd) + +Network policies are fetched directly from the selected environment's +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. + +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 +doesn't update. Auto DevOps users must make changes by following +the [Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). + +### Changing enforcement status + +To change a network policy's enforcement status: + +- Click the network policy you want to update. +- Click the **Enforcement status** toggle to update the selected policy. +- Click the **Apply changes** button to deploy network policy changes. + +NOTE: **Note:** +Disabled network policies have the +`network-policy.gitlab.com/disabled_by: gitlab` selector inside the +`podSelector` block. This narrows the scope of such a policy and as a +result it doesn't affect any pods. The policy itself is still deployed +to the corresponding deployment namespace. 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/standalone_vulnerability_page_download_patch_button_v13_1.png Binary files differnew file mode 100644 index 00000000000..b925c342a11 --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_download_patch_button_v13_1.png 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 differnew file mode 100644 index 00000000000..2063762d3eb --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_dropdown_v13_1.png 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 differnew file mode 100644 index 00000000000..ee4e97bcafe --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index b691a97fc32..b3128e49980 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -1,10 +1,13 @@ --- type: reference, howto +stage: Secure +group: Vulnerability Research +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Standalone Vulnerability pages -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. Each security vulnerability in the [Vulnerability List](../dependency_list/index.md) has its own standalone page. @@ -17,7 +20,7 @@ several different ways: - [Change the Vulnerability Status](#changing-vulnerability-status) - You can change the status of a vulnerability to **Detected**, **Confirmed**, **Dismissed**, or **Resolved**. - [Create issue](#creating-an-issue-for-a-vulnerability) - Create a new issue with the - title and description prepopulated with information from the vulnerability report. + title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../../project/issues/confidential_issues.md). - [Solution](#automatic-remediation-solutions-for-vulnerabilities) - For some vulnerabilities, a solution is provided for how to fix the vulnerability. @@ -39,7 +42,7 @@ the following values: You can create an issue for a vulnerability by selecting the **Create issue** button. This creates a [confidential issue](../../project/issues/confidential_issues.md) in the -project the vulnerability came from, and prepopulates it with useful information from +project the vulnerability came from, and pre-populates it with useful information from the vulnerability report. After the issue is created, GitLab redirects you to the issue page so you can edit, assign, or comment on the issue. @@ -52,14 +55,19 @@ generates for you. GitLab supports the following scanners: is only available for Node.js projects managed with `yarn`. - [Container Scanning](../container_scanning/index.md). +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. + ### Manually applying a suggested patch -To apply a patch automatically generated by GitLab to fix a vulnerability: +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: + + -1. Open the issue created in [Create issue](#creating-an-issue-for-a-vulnerability). -1. In the **Issue description**, scroll to **Solution** and download the linked patch file. -1. Ensure your local project has the same commit checked out that was used to generate the patch. -1. Run `git apply remediation.patch` to apply the patch. -1. Verify and commit the changes to your branch. +This will change the button text to "Download patch to resolve". Click on it to download the patch: - + diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 5a82712c055..47249a44bc1 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -1,9 +1,15 @@ +--- +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 +--- + # Award emoji -> - First [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/1825) in GitLab 8.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/1825) in GitLab 8.2. > - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9570) the usage of native emoji if the platform -> supports them and falls back to images or CSS sprites. This change greatly -> improved award emoji performance overall. +> supports them and falls back to images or CSS sprites. This change greatly +> improved award emoji performance overall. When you're collaborating online, you get fewer opportunities for high-fives and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md), diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 9ede9d9fdef..86624d12bcf 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -332,7 +332,7 @@ Updating [Ingress](#ingress) to the most recent version enables you to take adva ##### Viewing Web Application Firewall traffic -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can view Web Application Firewall traffic by navigating to your project's **Security & Compliance > Threat Monitoring** page. @@ -458,7 +458,7 @@ file. ### Crossplane -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34702) in GitLab 12.5 for project-level clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. [Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane useful for managing applications and infrastructure across multiple clouds. It extends the @@ -483,7 +483,7 @@ For information on configuring Crossplane installed on the cluster, see [Crossplane configuration](crossplane.md). NOTE: **Note:** -[`alpha/crossplane`](https://charts.crossplane.io/alpha/) chart v0.4.1 is used to +[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to install Crossplane using the [`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) file. @@ -615,6 +615,8 @@ Supported applications: - [Crossplane](#install-crossplane-using-gitlab-cicd) - [Fluentd](#install-fluentd-using-gitlab-cicd) - [Knative](#install-knative-using-gitlab-cicd) +- [PostHog](#install-posthog-using-gitlab-cicd) +- [Prometheus](#install-prometheus-using-gitlab-cicd) ### Usage @@ -779,6 +781,77 @@ postgresql: postgresqlPassword: example-postgresql-password ``` +### Install PostHog using GitLab CI/CD + +[PostHog](https://www.posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. + +To install PostHog into the `gitlab-managed-apps` namespace of your cluster, +define the `.gitlab/managed-apps/config.yaml` file with: + +```yaml +posthog: + installed: true +``` + +You can customize the installation of PostHog by defining `.gitlab/managed-apps/posthog/values.yaml` +in your cluster management project. Refer to the [Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog) +for the available configuration options. + +NOTE: **Note:** +You must provide a PostgreSQL password in `postgresql.postgresqlPassword` +or you will receive authentication errors. +See the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) for more information. + +Redis pods are restarted between upgrades. To prevent downtime, provide a Redis +password using the `redis.password` key. This prevents a new password from +being generated on each restart. + +Here is an example configuration for PostHog: + +```yaml +ingress: + enabled: true + hostname: "<posthog.example.com>" + +# This will be autogenerated if you skip it. Include if you have 2 or more web replicas +posthogSecret: 'long-secret-key-used-to-sign-cookies' + +# Needs to be here between runs. +# See https://github.com/helm/charts/tree/master/stable/postgresql#upgrade for more info +postgresql: + postgresqlPassword: example-postgresql-password + +# Recommended to set this to a value to redis prevent downtime between upgrades +redis: + password: example-redis-password +``` + +NOTE: **Note:** +Support for the PostHog managed application is provided by the PostHog team. +If you run into issues, please [open a support ticket](https://github.com/PostHog/posthog/issues/new/choose) directly. + +### Install Prometheus using GitLab CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25138) in GitLab 12.8. + +[Prometheus](https://prometheus.io/docs/introduction/overview/) is an +open-source monitoring and alerting system for supervising your +deployed applications. + +To install Prometheus into the `gitlab-managed-apps` namespace of your cluster, +define the `.gitlab/managed-apps/config.yaml` file with: + +```yaml +prometheus: + installed: true +``` + +You can customize the installation of Prometheus by defining +`.gitlab/managed-apps/prometheus/values.yaml` in your cluster management +project. Refer to the +[Configuration section of the Prometheus chart's README](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) +for the available configuration options. + ### Install GitLab Runner using GitLab CI/CD GitLab Runner is installed using GitLab CI/CD by defining configuration in @@ -857,10 +930,10 @@ Major upgrades might require additional setup steps, please consult the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/) for more information. -By default, Cilium will drop all non-whitelisted packets upon policy +By default, Cilium will drop all disallowed packets upon policy deployment. The audit mode is scheduled for release in [Cilium 1.8](https://github.com/cilium/cilium/pull/9970). In the audit -mode, non-whitelisted packets will not be dropped, and audit +mode, disallowed packets will not be dropped, and audit notifications will be generated instead. GitLab provides alternative Docker images for Cilium with the audit patch included. You can switch to the custom build and enable the audit mode by adding the following to @@ -915,7 +988,7 @@ metrics: ### Install Vault using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9982) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9982) in GitLab 12.9. [Hashicorp Vault](https://www.vaultproject.io/) is a secrets management solution which can be used to safely manage and store passwords, credentials, certificates and more. A Vault @@ -940,17 +1013,17 @@ when upgrading the Vault application. To optimally use Vault in a production environment, it's ideal to have a good understanding of the internals of Vault and how to configure it. This can be done by reading the -[the Vault documentation](https://www.vaultproject.io/docs/internals/) as well as +[the Vault documentation](https://www.vaultproject.io/docs/internals) as well as the Vault Helm chart [`values.yaml` file](https://github.com/hashicorp/vault-helm/blob/v0.3.3/values.yaml). At a minimum you will likely set up: -- A [seal](https://www.vaultproject.io/docs/configuration/seal/) for extra encryption +- A [seal](https://www.vaultproject.io/docs/configuration/seal) for extra encryption of the master key. -- A [storage backend](https://www.vaultproject.io/docs/configuration/storage/) that is +- A [storage backend](https://www.vaultproject.io/docs/configuration/storage) that is suitable for environment and storage security requirements. -- [HA Mode](https://www.vaultproject.io/docs/concepts/ha/). -- [The Vault UI](https://www.vaultproject.io/docs/configuration/ui/). +- [HA Mode](https://www.vaultproject.io/docs/concepts/ha). +- [The Vault UI](https://www.vaultproject.io/docs/configuration/ui). The following is an example values file (`.gitlab/managed-apps/vault/values.yaml`) that configures Google Key Management Service for auto-unseal, using a Google Cloud Storage backend, enabling @@ -1048,12 +1121,12 @@ You can customize the installation of JupyterHub by defining a `.gitlab/managed-apps/jupyterhub/values.yaml` file in your cluster management project. Refer to the -[chart reference](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference.html) for the +[chart reference](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html) for the available configuration options. ### Install Elastic Stack using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/45) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25138) in GitLab 12.8. Elastic Stack is installed using GitLab CI/CD by defining configuration in `.gitlab/managed-apps/config.yaml`. @@ -1080,7 +1153,7 @@ In this alpha implementation of installing Elastic Stack through CI, reading the ### Install Crossplane using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/35675) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35675) in GitLab 12.9. Crossplane is installed using GitLab CI/CD by defining configuration in `.gitlab/managed-apps/config.yaml`. @@ -1157,7 +1230,7 @@ GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#inv 1. Knative and Prometheus managed applications installed on your cluster. 1. Manually applied the custom metrics on your cluster by running the following command: - ```bash + ```shell kubectl apply -f https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/raw/02c8231e30ef5b6725e6ba368bc63863ceb3c07d/src/default-data/knative/istio-metrics.yaml ``` @@ -1166,7 +1239,7 @@ GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#inv To uninstall Knative, you must first manually remove any custom metrics you have added by running the following command: -```bash +```shell kubectl delete -f https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/raw/02c8231e30ef5b6725e6ba368bc63863ceb3c07d/src/default-data/knative/istio-metrics.yaml ``` @@ -1197,7 +1270,7 @@ chart plus the values set by ## Uninstalling applications -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/60665) in GitLab 11.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60665) in GitLab 11.11. The applications below can be uninstalled. diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index a9a5f768ec8..3a430ad55bd 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -151,7 +151,7 @@ kubectl describe globaladdress.compute.gcp.crossplane.io gitlab-ad-globaladdress Resource classes are a way of defining a configuration for the required managed service. We will define the PostgreSQL Resource class -- Define a `gcp-postgres-standard.yaml` resourceclass which contains +- Define a `gcp-postgres-standard.yaml` resource class which contains 1. A default CloudSQLInstanceClass. 1. A CloudSQLInstanceClass with labels. diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index a2adf238dda..2b342ceb06d 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cluster Environments **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13392) for group-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14809) for instance-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) for group-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) for instance-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. Cluster environments provide a consolidated view of which CI [environments](../../ci/environments/index.md) are deployed to the Kubernetes cluster and it: diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 03b4dc45015..c8755af29a3 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -10,7 +10,7 @@ CAUTION: **Warning:** This is an _alpha_ feature, and it is subject to change at any time without prior notice. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32810) in GitLab 12.5 +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5 A project can be designated as the management project for a cluster. A management project can be used to run deployment jobs with diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index 25feb6e56bc..08a26a45b17 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -1,10 +1,13 @@ --- type: reference, howto +stage: Manage +group: Compliance +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 --- # Compliance Dashboard **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36524) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. The Compliance Dashboard gives you the ability to see a group's Merge Request activity by providing a high-level view for all projects in the group. For example, code approved diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index fd4af74e086..d0e73b47358 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -1,3 +1,10 @@ +--- +type: reference +stage: Manage +group: Compliance +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 +--- + # Compliance **(ULTIMATE)** The compliance tools provided by GitLab let you keep an eye on various aspects of your project. The diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index cbabed00283..4ceb393af8c 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -1,10 +1,13 @@ --- type: reference, howto +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # License Compliance **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. ## Overview @@ -61,10 +64,14 @@ The following languages and package managers are supported. | 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.readthedocs.io/en/1.1/requirements.html) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock).) |[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/1.1/requirements/) 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. + ### Experimental support The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types), @@ -135,14 +142,18 @@ License Compliance can be configured using environment variables. | Environment variable | Required | Description | |-----------------------------|----------|-------------| -| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | | `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and NPM projects). | +| `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | +| `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | +| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | +| `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | | `GRADLE_CLI_OPTS` | no | Additional arguments for the gradle executable. If not supplied, defaults to `--exclude-task=test`. | | `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if your project has both Golang and Ruby code stored in different directories and you want to only scan the Ruby code, you can update your `.gitlab-ci-yml` template to specify which project directories to scan, like `LICENSE_FINDER_CLI_OPTS: '--debug --aggregate-paths=. ruby'`. | | `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | | `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | | `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | | `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | +| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | | `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | ### Installing custom dependencies @@ -242,7 +253,7 @@ generate a key store file, see the ### Selecting the version of Python > - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - In [GitLab 12.2](https://gitlab.com/gitlab-org/gitlab/issues/12032), Python 3.5 became the default. +> - In [GitLab 12.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12032), Python 3.5 became the default. > - In [GitLab 12.7](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/101), Python 3.8 became the default. License Compliance uses Python 3.8 and pip 19.1 by default. @@ -328,7 +339,7 @@ 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 @@ -339,7 +350,7 @@ setting to specify its location. For example: -```text +```plaintext npmRegistryServer: "https://npm.example.com" ``` @@ -348,6 +359,137 @@ npmRegistryServer: "https://npm.example.com" You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +### Configuring Bower projects + +You can configure Bower projects by using a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) +file. + +#### Using private Bower registries + +If you have a private Bower registry you can use the +[`registry`](https://bower.io/docs/config/#bowerrc-specification) +setting to specify its location. + +For example: + +```plaintext +{ + "registry": "https://registry.bower.io" +} +``` + +#### Custom root certificates for Bower + +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 `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) +file. + +### Configuring Conan projects + +You can configure [Conan](https://conan.io/) projects by adding a `.conan` directory to your +project root. The project root serves as the [`CONAN_USER_HOME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-user-home). + +Consult the [Conan](https://docs.conan.io/en/latest/reference/config_files/conan.conf.html#conan-conf) +documentation for a list of settings that you can apply. + +The `license_scanning` job runs in a [Debian 10](https://www.debian.org/releases/buster/) Docker +image. The supplied image ships with some build tools such as [CMake](https://cmake.org/) and [GCC](https://gcc.gnu.org/). +However, not all project types are supported by default. To install additional tools needed to +compile dependencies, use a [`before_script`](../../../ci/yaml/README.md#before_script-and-after_script) +to install the necessary build tools using the [`apt`](https://wiki.debian.org/PackageManagementTools) +package manager. For a comprehensive list, consult [the Conan documentation](https://docs.conan.io/en/latest/introduction.html#all-platforms-all-build-systems-and-compilers). + +The default [Conan](https://conan.io/) configuration sets [`CONAN_LOGIN_USERNAME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) +to `ci_user`, and binds [`CONAN_PASSWORD`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-password-conan-password-remote-name) +to the [`CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) +for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/#fetching-conan-package-information-from-the-gitlab-package-registry) +if a GitLab remote is specified in the `.conan/remotes.json` file. + +To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) +matching the name of the remote specified in the `.conan/remotes.json` file. + +NOTE: **Note:** +[MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild) projects aren't supported. The +`license_scanning` image ships with [Mono](https://www.mono-project.com/) and [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild). +Additional setup may be required to build packages for this project configuration. + +#### Using private Conan registries + +By default, [Conan](https://conan.io/) uses the `conan-center` remote. For example: + +```json +{ + "remotes": [ + { + "name": "conan-center", + "url": "https://conan.bintray.com", + "verify_ssl": true + } + ] +} +``` + +To fetch dependencies from an alternate remote, specify that remote in a `.conan/remotes.json`. For +example: + +```json +{ + "remotes": [ + { + "name": "gitlab", + "url": "https://gitlab.com/api/v4/packages/conan", + "verify_ssl": true + } + ] +} +``` + +If credentials are required to authenticate then you can configure a [protected variable](../../../ci/variables/README.md#protect-a-custom-variable) +following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). + +#### Custom root certificates for Conan + +You can provide custom certificates by adding a `.conan/cacert.pem` file to the project root and +setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) +to `.conan/cacert.pem`. + +If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), this +variable's X.509 certificates are installed in the Docker image's default trust store and Conan is +configured to use this as the default `CA_CERT_PATH`. + +### Configuring Go projects + +To configure [Go modules](https://github.com/golang/go/wiki/Modules) +based projects, specify [environment variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +in the `license_scanning` job's [variables](#available-variables) section in `.gitlab-ci.yml`. + +If a project has [vendored](https://golang.org/pkg/cmd/go/#hdr-Vendor_Directories) its modules, +then the combination of the `vendor` directory and `mod.sum` file are used to detect the software +licenses associated with the Go module dependencies. + +#### Using private Go registries + +You can use the [`GOPRIVATE`](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +and [`GOPROXY`](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +environment variables to control where modules are sourced from. Alternatively, you can use +[`go mod vendor`](https://golang.org/ref/mod#tmp_28) to vendor a project's modules. + +#### Custom root certificates for Go + +You can specify the [`-insecure`](https://golang.org/pkg/cmd/go/internal/get/) flag by exporting the +[`GOFLAGS`](https://golang.org/cmd/go/#hdr-Environment_variables) +environment variable. For example: + +```yaml +include: + - template: License-Scanning.gitlab-ci.yml + +license_scanning: + variables: + GOFLAGS: '-insecure' +``` + ### Migration from `license_management` to `license_scanning` In GitLab 12.8 a new name for `license_management` job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. @@ -450,15 +592,21 @@ license_scanning: The License Compliance job should now use local copies of the License Compliance analyzers to scan your code and generate security reports, without requiring internet access. -Additional configuration may be needed for connecting to [private Maven repositories](#using-private-maven-repos), -[private NPM registries](#using-private-npm-registries), [private Yarn registries](#using-private-yarn-registries), and [private Python repositories](#using-private-python-repos). +Additional configuration may be needed for connecting to +[private Bower registries](#using-private-bower-registries), +[private Conan registries](#using-private-bower-registries), +[private Go registries](#using-private-go-registries), +[private Maven repositories](#using-private-maven-repos), +[private NPM registries](#using-private-npm-registries), +[private Python repositories](#using-private-python-repos), +and [private Yarn registries](#using-private-yarn-registries). Exact name matches are required for [project policies](#project-policies-for-license-compliance) when running in an offline environment ([see related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212388)). ## Project policies for License Compliance -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5940) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5940) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. From the project's settings: @@ -496,7 +644,7 @@ Searching for Licenses: ## License Compliance report under pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5491) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5491) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on the pipeline ID that has a `license_scanning` job to see the Licenses tab with the listed @@ -518,7 +666,7 @@ but commented out to help encourage others to add to it in the future. --> ## License list -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13582) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. The License list allows you to see your project's licenses and key details about them. @@ -554,3 +702,78 @@ Policies can be configured by maintainers of the project. Developers of the project can view the policies configured in a project.  + +## Troubleshooting + +### `ERROR -- : asdf: No preset version installed for command` + +This error occurs when the version of the tools used by your project +do not match the version of the pre-installed tools available in the +`license_scanning` Docker image. The `license_scanning` job uses +[asdf-vm](https://asdf-vm.com/) to activate the appropriate version of +a tool that your project relies on. For example, if your project relies on a specific +version of [Node.js](https://nodejs.org/) or any other supported tool you can +specify the desired version by adding a +[`.tool-versions`](https://asdf-vm.com/#/core-configuration?id=tool-versions) file to the project +or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-configuration?id=environment-variables) environment variable to +activate the appropriate version. + +For example, the following `.tool-versions` file will activate version `12.16.3` of [Node.js](https://nodejs.org/) +and version `2.6.6` of [Ruby](https://www.ruby-lang.org/). + +```plaintext +nodejs 12.16.3 +ruby 2.6.6 +``` + +The next example shows how to activate the same versions of the tools mentioned above by using environment variables defined in your +project's `.gitlab-ci.yml` file. + +```yaml +include: + - template: License-Scanning.gitlab-ci.yml + +license_scanning: + variables: + ASDF_NODEJS_VERSION: '12.16.3' + ASDF_RUBY_VERSION: '2.6.6' +``` + +A full list of variables can be found in [environment variables](#available-variables). + +To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: + +```shell +$ docker run --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -lc 'asdf list' +golang + 1.14 +gradle + 6.3 +java + adopt-openjdk-11.0.7+10 + adopt-openjdk-8u242-b08 +maven + 3.6.3 +nodejs + 10.20.1 + 12.16.3 +php + 7.4.5 +python + 2.7.18 + 3.8.2 +ruby + 2.6.6 +sbt + 1.3.8 +``` + +To interact with the `license_scanning` runtime environment use the following command: + +```shell +$ docker run -it --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -l +root@6abb70e9f193:~# +``` + +NOTE: **Note:** +Selecting a custom version of [Mono](https://www.mono-project.com/) or [.NET Core](https://dotnet.microsoft.com/download/dotnet-core) is currently not supported. diff --git a/doc/user/discussions/img/add_another_suggestion_to_batch_v13_1.jpg b/doc/user/discussions/img/add_another_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..e8aa4b7c730 --- /dev/null +++ b/doc/user/discussions/img/add_another_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/discussions/img/add_first_suggestion_to_batch_v13_1.jpg b/doc/user/discussions/img/add_first_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..d15f5d53e55 --- /dev/null +++ b/doc/user/discussions/img/add_first_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/discussions/img/apply_batch_of_suggestions_v13_1.jpg b/doc/user/discussions/img/apply_batch_of_suggestions_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..3e1e9c20af9 --- /dev/null +++ b/doc/user/discussions/img/apply_batch_of_suggestions_v13_1.jpg 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 differnew file mode 100644 index 00000000000..e19a3ed4f75 --- /dev/null +++ b/doc/user/discussions/img/quickly_assign_commenter_v13_1.png diff --git a/doc/user/discussions/img/remove_suggestion_from_batch_v13_1.jpg b/doc/user/discussions/img/remove_suggestion_from_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..fa8331effdb --- /dev/null +++ b/doc/user/discussions/img/remove_suggestion_from_batch_v13_1.jpg diff --git a/doc/user/discussions/img/suggestions_custom_commit_messages_v12_7.png b/doc/user/discussions/img/suggestions_custom_commit_messages_v12_7.png Binary files differdeleted file mode 100644 index 8bbc0fcb99b..00000000000 --- a/doc/user/discussions/img/suggestions_custom_commit_messages_v12_7.png +++ /dev/null diff --git a/doc/user/discussions/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/discussions/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..a4c9df0ebb9 --- /dev/null +++ b/doc/user/discussions/img/suggestions_custom_commit_messages_v13_1.jpg diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 9f24807ddf4..5ee11c553af 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Threads The ability to contribute conversationally is offered throughout GitLab. @@ -48,7 +54,7 @@ to address feedback and lets you hide threads that are no longer relevant. ### Commit threads in the context of a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/31847) in GitLab 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/31847) in GitLab 10.3. For reviewers with commit-based workflow, it may be useful to add threads to specific commit diffs in the context of a merge request. These threads will @@ -290,9 +296,10 @@ edit existing comments. Non-team members are restricted from adding or editing c Additionally, locked issues and merge requests can not be reopened. -## Merge Request Reviews **(PREMIUM)** +## Merge Request Reviews -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab 11.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Core in 13.1. When looking at a Merge Request diff, you are able to start a review. This allows you to create comments inside a Merge Request that are **only visible to you** until published, @@ -364,7 +371,7 @@ Replying to this email will, consequentially, create a new comment on the associ ## Filtering notes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/26723) in GitLab 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. For issues with many comments like activity notes and user comments, sometimes finding useful information can be hard. There is a way to filter comments from single notes and threads for merge requests and issues. @@ -384,7 +391,7 @@ from any device you're logged into. ## Suggest Changes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/18008) in GitLab 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. As a reviewer, you're able to suggest code changes with a simple Markdown syntax in Merge Request Diff threads. Then, the @@ -402,10 +409,7 @@ the merge request authored by the user that applied them.  -1. Click **Comment**. - - NOTE: **Note:** - If you're using GitLab Premium, GitLab.com Silver, and higher tiers, the thread will display [Review](#merge-request-reviews-premium) options. Click either **Start a review**, **Add comment now**, or **Add to review** to obtain the same result. +1. Click either **Start a review** or **Add to review** to add your comment to a [review](#merge-request-reviews), or **Add comment now** to add the comment to the thread immediately. The Suggestion in the comment can be applied by the merge request author directly from the merge request: @@ -419,7 +423,7 @@ branch. [Developer permission](../permissions.md) is required to do so. ### Multi-line Suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53310) in GitLab 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. Reviewers can also suggest changes to multiple lines with a single Suggestion within merge request diff threads by adjusting the range offsets. The @@ -451,38 +455,66 @@ instead of the usual three. ### Configure the commit message for applied Suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13086) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. + +GitLab uses a default commit message +when applying Suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` -GitLab uses `Apply suggestion to %{file_path}` by default as commit messages -when applying Suggestions. This commit message can be customized to -follow any guidelines you might have. To do so, expand the **Merge requests** +For example, consider that a user applied 3 suggestions to 2 different files, the default commit message will be: **Apply 3 suggestion(s) to 2 file(s)** + +These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests** tab within your project's **General** settings and change the **Merge suggestions** text: - + You can also use following variables besides static text: | Variable | Description | Output example | |---|---|---| +| `%{branch_name}` | The name of the branch the Suggestion(s) was(were) applied to. | `my-feature-branch` | +| `%{files_count}` | The number of file(s) to which Suggestion(s) was(were) applied.| **2** | +| `%{file_paths}` | The path(s) of the file(s) Suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | | `%{project_path}` | The project path. | `my-group/my-project` | | `%{project_name}` | The human-readable name of the project. | **My Project** | -| `%{file_path}` | The path of the file the Suggestion is applied to. | `docs/index.md` | -| `%{branch_name}` | The name of the branch the Suggestion is applied on. | `my-feature-branch` | -| `%{username}` | The username of the user applying the Suggestion. | `user_1` | -| `%{user_full_name}` | The full name of the user applying the Suggestion. | **User 1** | +| `%{suggestions_count}` | The number of Suggestions applied.| **3** | +| `%{username}` | The username of the user applying Suggestion(s). | `user_1` | +| `%{user_full_name}` | The full name of the user applying Suggestion(s). | **User 1** | For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to `Addresses %{username}'s review`. NOTE: **Note:** -Custom commit messages for each applied Suggestion will be +Custom commit messages for each applied Suggestion (and for batch Suggestions) will be introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/issues/25381). +### Batch Suggestions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/25486) in GitLab 13.1. + +You can apply multiple suggestions at once to reduce the number of commits added +to your branch to address your reviewers' requests. + +1. To start a batch of suggestions that will be applied with a single commit, click **Add suggestion to batch**: + +  + +1. Add as many additional suggestions to the batch as you wish: + +  + +1. To remove suggestions, click **Remove from batch**: + +  + +1. Having added all the suggestions to your liking, when ready, click **Apply suggestions**: + +  + ## Start a thread by replying to a standard comment -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30299) in GitLab 11.9 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9 To reply to a standard (non-thread) comment, you can use the **Reply to comment** button. @@ -500,3 +532,15 @@ to the original comment, so a note about when it was last edited will appear und This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are not supported yet. + +## Assign an issue to the commenting user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1. + +You can assign an issue to a user who made a comment. + +In the comment, click the **More Actions** menu and click **Assign to commenting user**. + +Click the button again to unassign the commenter. + + diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index 47f8671afae..9b52c178493 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.md @@ -3,11 +3,11 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/16379) in GitLab 10.5 Feature highlights are represented by a pulsing blue dot. Hovering over the dot -will open up callout with more information. +will display more information. They are used to emphasize a certain feature and make something more visible to the user. You can dismiss any feature highlight permanently by clicking the "Got it" link -at the bottom of the callout. There isn't a way to restore the feature highlight +at the bottom of the modal window. There isn't a way to restore the feature highlight after it has been dismissed.  diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index d615b67f3d2..6522f5c4053 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -31,6 +31,10 @@ gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAA 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`). +## Backups + +[See our backup strategy](https://about.gitlab.com/handbook/engineering/infrastructure/production/#backups). + ## Alternative SSH port GitLab.com can be reached via a [different SSH port](https://about.gitlab.com/blog/2016/02/18/gitlab-dot-com-now-supports-an-alternate-git-plus-ssh-port/) for `git+ssh`. @@ -78,6 +82,7 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | 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 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` | ## Repository size limit @@ -136,7 +141,7 @@ The `gitlab-shared-runners-manager-X.gitlab.com` fleet of Runners are dedicated Jobs handled by the shared Runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), **will be timed out after 3 hours**, regardless of the timeout configured in a -project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/issues/4070) for the reference. +project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. Below are the shared Runners settings. @@ -152,7 +157,7 @@ Below are the shared Runners settings. Linux Shared Runners on GitLab.com provide a way to run commands in a CI job before the Runner attempts to run `git init` and `git fetch` to download a GitLab repository. The -[pre_clone_script](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) +[`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) can be used for: - Seeding the build directory with repository data @@ -219,7 +224,7 @@ sentry_dsn = "X" "google-tags=gitlab-com,srm", "google-use-internal-ip", "google-zone=us-east1-d", - "engine-opt=mtu=1460", # Set MTU for container interface, for more information check https://gitlab.com/gitlab-org/gitlab-runner/issues/3214#note_82892928 + "engine-opt=mtu=1460", # Set MTU for container interface, for more information check https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3214#note_82892928 "google-machine-image=PROJECT/global/images/IMAGE", "engine-opt=ipv6", # This will create IPv6 interfaces in the containers. "engine-opt=fixed-cidr-v6=fc00::/7", @@ -243,7 +248,7 @@ During the beta period, the [shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota-starter-only) will apply for groups and projects in the same way as Linux Runners. This may change when the beta period ends, as discussed in this -[related issue](https://gitlab.com/gitlab-org/gitlab/issues/30834). +[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). Windows Shared Runners on GitLab.com automatically autoscale by launching virtual machines on the Google Cloud Platform. This solution uses @@ -367,7 +372,7 @@ test: release we will update the autoscaler to enable the pre-provisioning of virtual machines. This will significantly reduce the time it takes to provision a VM on the Windows fleet. You can - follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/issues/32). + follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). - The Windows Shared Runner fleet may be unavailable occasionally for maintenance or updates. - The Windows Shared Runner virtual machine instances do not use the @@ -415,44 +420,44 @@ different database servers. The list of GitLab.com specific settings (and their defaults) is as follows: -| Setting | GitLab.com | Default | -|:------------------------------------|:--------------------------------------------------------------------|:--------------------------------------| -| archive_command | `/usr/bin/envdir /etc/wal-e.d/env /opt/wal-e/bin/wal-e wal-push %p` | empty | -| archive_mode | on | off | -| autovacuum_analyze_scale_factor | 0.01 | 0.01 | -| autovacuum_max_workers | 6 | 3 | -| autovacuum_vacuum_cost_limit | 1000 | -1 | -| autovacuum_vacuum_scale_factor | 0.01 | 0.02 | -| checkpoint_completion_target | 0.7 | 0.9 | -| checkpoint_segments | 32 | 10 | -| effective_cache_size | 338688MB | Based on how much memory is available | -| hot_standby | on | off | -| hot_standby_feedback | on | off | -| log_autovacuum_min_duration | 0 | -1 | -| log_checkpoints | on | off | -| log_line_prefix | `%t [%p]: [%l-1]` | empty | -| log_min_duration_statement | 1000 | -1 | -| log_temp_files | 0 | -1 | -| maintenance_work_mem | 2048MB | 16 MB | -| max_replication_slots | 5 | 0 | -| max_wal_senders | 32 | 0 | -| max_wal_size | 5GB | 1GB | -| shared_buffers | 112896MB | Based on how much memory is available | -| shared_preload_libraries | pg_stat_statements | empty | -| shmall | 30146560 | Based on the server's capabilities | -| shmmax | 123480309760 | Based on the server's capabilities | -| wal_buffers | 16MB | -1 | -| wal_keep_segments | 512 | 10 | -| wal_level | replica | minimal | -| statement_timeout | 15s | 60s | -| idle_in_transaction_session_timeout | 60s | 60s | +| Setting | GitLab.com | Default | +|:--------------------------------------|:--------------------------------------------------------------------|:--------------------------------------| +| `archive_command` | `/usr/bin/envdir /etc/wal-e.d/env /opt/wal-e/bin/wal-e wal-push %p` | empty | +| `archive_mode` | on | off | +| `autovacuum_analyze_scale_factor` | 0.01 | 0.01 | +| `autovacuum_max_workers` | 6 | 3 | +| `autovacuum_vacuum_cost_limit` | 1000 | -1 | +| `autovacuum_vacuum_scale_factor` | 0.01 | 0.02 | +| `checkpoint_completion_target` | 0.7 | 0.9 | +| `checkpoint_segments` | 32 | 10 | +| `effective_cache_size` | 338688MB | Based on how much memory is available | +| `hot_standby` | on | off | +| `hot_standby_feedback` | on | off | +| `log_autovacuum_min_duration` | 0 | -1 | +| `log_checkpoints` | on | off | +| `log_line_prefix` | `%t [%p]: [%l-1]` | empty | +| `log_min_duration_statement` | 1000 | -1 | +| `log_temp_files` | 0 | -1 | +| `maintenance_work_mem` | 2048MB | 16 MB | +| `max_replication_slots` | 5 | 0 | +| `max_wal_senders` | 32 | 0 | +| `max_wal_size` | 5GB | 1GB | +| `shared_buffers` | 112896MB | Based on how much memory is available | +| `shared_preload_libraries` | pg_stat_statements | empty | +| `shmall` | 30146560 | Based on the server's capabilities | +| `shmmax` | 123480309760 | Based on the server's capabilities | +| `wal_buffers` | 16MB | -1 | +| `wal_keep_segments` | 512 | 10 | +| `wal_level` | replica | minimal | +| `statement_timeout` | 15s | 60s | +| `idle_in_transaction_session_timeout` | 60s | 60s | Some of these settings are in the process being adjusted. For example, the value for `shared_buffers` is quite high and as such we are looking into adjusting it. More information on this particular change can be found at -<https://gitlab.com/gitlab-com/infrastructure/issues/1555>. An up to date list +<https://gitlab.com/gitlab-com/infrastructure/-/issues/1555>. An up to date list of proposed changes can be found at -<https://gitlab.com/gitlab-com/infrastructure/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=database&label_name[]=change>. +<https://gitlab.com/gitlab-com/infrastructure/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=database&label_name[]=change>. ## Unicorn @@ -553,7 +558,7 @@ GitLab.com: On GitLab.com, projects, groups, and snippets created As of GitLab 12.2 (July 2019), projects, groups, and snippets have the -[**Internal** visibility](../../public_access/public_access.md#internal-projects) setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/issues/12388). +[**Internal** visibility](../../public_access/public_access.md#internal-projects) setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). ### SSH maximum number of connections @@ -563,6 +568,10 @@ If more than the maximum number of allowed connections occur concurrently, they dropped and users get [an `ssh_exchange_identification` error](../../topics/git/troubleshooting_git.md#ssh_exchange_identification-error). +### Import/export + +To help avoid abuse, project and group imports, exports, and export downloads are rate limited. See [Project import/export rate limits](../../user/project/settings/import_export.md#rate-limits) and [Group import/export rate limits](../../user/group/settings/import_export.md#rate-limits) for details. + ## GitLab.com Logging We use [Fluentd](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#fluentd) to parse our logs. Fluentd sends our logs to diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index a90097c848f..c4ccc1f7b52 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,31 +1,74 @@ -# Bulk editing issues, merge requests, and epics at the group level **(PREMIUM)** +--- +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 +--- -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7249) for issues in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12719) for merge requests in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7250) for epics in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +# Bulk editing issues, epics, and merge requests at the group level **(PREMIUM)** -## Editing milestones and labels +NOTE: **Note:** +Bulk editing issues and merge requests is also available at the **project level**. +For more details, see [Bulk editing issues, epics, and merge requests](../../project/bulk_editing.md). -> **Notes:** -> -> - A permission level of `Reporter` or higher is required in order to manage issues. -> - A permission level of `Developer` or higher is required in order to manage merge requests. -> - A permission level of `Reporter` or higher is required in order to manage epics. +If you want to update attributes across multiple issues, epics, or merge requests in a group, you +can do it by bulk editing them, that is, editing them together. -By using the bulk editing feature: + -- Milestones can be updated simultaneously across multiple issues or merge requests. -- Labels can be updated simultaneously across multiple issues, merge requests, or epics. +## Bulk edit issues at the group level - +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. + +NOTE: **Note:** +You need a permission level of [Reporter or higher](../../permissions.md) to manage issues. + +When bulk editing issues in a group, you can edit the following attributes: + +- Milestone +- Labels + +To update multiple project issues at the same time: + +1. In a group, go to **{issues}** **Issues > List**. +1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Select the checkboxes next to each issue you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit epics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +NOTE: **Note:** +You need a permission level of [Reporter or higher](../../permissions.md) to manage epics. + +When bulk editing epics in a group, you can edit their labels. + +To update multiple epics at the same time: + +1. In a group, go to **{epic}** **Epics > List**. +1. Click **Edit epics**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Check the checkboxes next to each epic you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the group level + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +NOTE: **Note:** +You need a permission level of [Developer or higher](../../permissions.md) to manage merge requests. + +When bulk editing merge requests in a group, you can edit the following attributes: + +- Milestone +- Labels -To bulk update group issues, merge requests, or epics: +To update multiple group merge requests at the same time: -1. Navigate to the issues, merge requests, or epics list. -1. Click **Edit issues**, **Edit merge requests**, or **Edit epics**. - - This will open a sidebar on the right-hand side where editable fields - for milestones and labels will be displayed. - - Checkboxes will also appear beside each issue, merge request, or epic. -1. Check the checkbox beside each issue, merge request, or epic to be edited. -1. Select the desired new values from the sidebar. +1. In a group, go to **{merge-request}** **Merge Requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. 1. Click **Update all**. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 5e6ff980c8b..5cdac7ae892 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Group-level Kubernetes clusters -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/34758) in GitLab 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. Similar to [project-level](../../project/clusters/index.md) and [instance-level](../../instance/clusters/index.md) Kubernetes clusters, @@ -23,8 +23,8 @@ and troubleshooting applications for your group cluster, see ## RBAC compatibility -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/29398) in GitLab 11.4. -> - [Project namespace restriction](https://gitlab.com/gitlab-org/gitlab-foss/issues/51716) was introduced in GitLab 11.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29398) in GitLab 11.4. +> - [Project namespace restriction](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) was introduced in GitLab 11.5. For each project under a group with a Kubernetes cluster, GitLab creates a restricted service account with [`edit` privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) @@ -65,7 +65,7 @@ for deployments with a cluster not managed by GitLab, you must ensure: - The project's deployment service account has permissions to deploy to [`KUBE_NAMESPACE`](../../project/clusters/index.md#deployment-variables). - `KUBECONFIG` correctly reflects any changes to `KUBE_NAMESPACE` - (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/issues/31519)). Editing + (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/-/issues/31519)). Editing `KUBE_NAMESPACE` directly is discouraged. NOTE: **Note:** @@ -74,7 +74,7 @@ the resources required to run them even if you choose to manage your own cluster ### Clearing the cluster cache -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31759) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. If you choose to allow GitLab to manage your cluster for you, GitLab stores a cached version of the namespaces and service accounts it creates for your projects. If you diff --git a/doc/user/group/contribution_analytics/img/group_stats_table.png b/doc/user/group/contribution_analytics/img/group_stats_table.png Binary files differindex f1d1031fa18..1f58b9717d0 100644 --- a/doc/user/group/contribution_analytics/img/group_stats_table.png +++ b/doc/user/group/contribution_analytics/img/group_stats_table.png diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 03f0ad6ad1c..bcc6d958427 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -2,13 +2,12 @@ type: reference stage: Manage group: Analytics -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 +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 --- # Contribution Analytics **(STARTER)** > - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3090) for subgroups in GitLab 12.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) for subgroups in GitLab 12.2. ## Overview @@ -63,7 +62,7 @@ Contributions per group member are also presented in tabular format. Click a col - Number of opened issues - Number of closed issues - Number of opened MRs -- Number of accepted MRs +- Number of merged MRs - Number of total contributions  diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index e47a281141d..ebeacda24c6 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -1,10 +1,13 @@ --- type: reference +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 --- # Custom group-level project templates **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in [GitLab 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. diff --git a/doc/user/group/epics/img/bulk_editing.png b/doc/user/group/epics/img/bulk_editing.png Binary files differdeleted file mode 100644 index 85610bef83e..00000000000 --- a/doc/user/group/epics/img/bulk_editing.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..f08f774e986 --- /dev/null +++ b/doc/user/group/epics/img/issue_list_v13_1.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index d53acaf502a..85164292265 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,11 +1,14 @@ --- type: reference, howto +stage: Plan +group: Portfolio 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 --- # Epics **(PREMIUM)** > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. -> - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. +> - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and @@ -25,7 +28,7 @@ milestones. To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include: - [Create an epic](manage_epics.md#create-an-epic) -- [Bulk-edit epics](manage_epics.md#bulk-edit-epics) +- [Bulk-edit epics](../bulk_editing/index.md#bulk-edit-epics) - [Delete an epic](manage_epics.md#delete-an-epic) - [Close an epic](manage_epics.md#close-an-epic) - [Reopen a closed epic](manage_epics.md#reopen-a-closed-epic) @@ -67,7 +70,7 @@ This feature comes with a feature flag enabled by default. For steps to disable ## Multi-level child epics **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8333) in GitLab Ultimate 11.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7. Any epic that belongs to a group, or subgroup of the parent epic's group, is eligible to be added. New child epics appear at the top of the list of epics in the **Epics and Issues** tab. @@ -86,11 +89,11 @@ To set a **Start date** and **Due date** for an epic, select one of the followin - **Fixed**: Enter a fixed value. - **From milestones**: Inherit a dynamic value from the milestones currently assigned to the epic's issues. Note that GitLab 12.5 replaced this option with **Inherited**. -- **Inherited**: Inherit a dynamic value from the epic's issues, child epics, and milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7332) in GitLab 12.5 to replace **From milestones**). +- **Inherited**: Inherit a dynamic value from the epic's issues, child epics, and milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**). ### From milestones -> [Replaced](https://gitlab.com/gitlab-org/gitlab/issues/7332) in GitLab 12.5 by **Inherited**. +> [Replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 by **Inherited**. If you select **From milestones** for the start date, GitLab will automatically set the date to be earliest start date across all milestones that are currently assigned to the issues that are added to the epic. @@ -105,7 +108,7 @@ These are dynamic dates which are recalculated if any of the following occur: ### Inherited -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7332) in GitLab 12.5 to replace **From milestones**. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**. If you select: @@ -127,7 +130,7 @@ then the parent epic's start date will reflect the change and this will propagat ## Roadmap in epics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. If your epic contains one or more [child epics](#multi-level-child-epics-ultimate) which have a [start or due date](#start-date-and-due-date), a diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 50eb0c64f4b..26d5cb51e01 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -1,8 +1,11 @@ --- type: howto +stage: Plan +group: Portfolio 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 --- -<!-- When adding a new section here, remember to mention it in index.md#manage-epics --> +<!-- When adding a new h2 section here, remember to mention it in index.md#manage-epics --> # Manage epics **(PREMIUM)** @@ -30,7 +33,8 @@ You will be taken to the new epic where can edit the following details: An epic's page contains the following tabs: -- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are shown in a tree view. +- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are + shown in a tree view. - Click the <kbd>></kbd> beside a parent epic to reveal the child epics and issues. - Hover over the total counts to see a breakdown of open and closed items. - **Roadmap**: a roadmap view of child epics which have start and due dates. @@ -39,17 +43,8 @@ An epic's page contains the following tabs: ## Bulk-edit epics -You can edit multiple epics at once. For example, to apply labels to multiple epics: - -1. Go to the Epics list. -1. Click **Edit epics**. - - Checkboxes appear next to each epic. - - A sidebar on the right-hand side appears with an editable field for labels. -1. Select the checkbox next to each epic to be edited. -1. Select the labels you want. -1. Click **Update all**. - - +You can edit multiple epics at once. To learn how to do it, visit +[Bulk editing issues, epics, and merge requests at the group level](../bulk_editing/index.md#bulk-edit-epics). ## Delete an epic @@ -92,7 +87,7 @@ link in the issue sidebar. ## Search for an epic from epics list page > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/37081) to the [Premium](https://about.gitlab.com/pricing/) tier in GitLab 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to the [Premium](https://about.gitlab.com/pricing/) tier in GitLab 12.8. You can search for an epic from the list of epics using filtered search bar (similar to that of Issues and Merge Requests) based on following parameters: @@ -134,8 +129,8 @@ confidential** checkbox. ### Enable Confidential Epics **(PREMIUM ONLY)** -The Confidential Epics feature is under development and not ready for production use. It's deployed behind a -feature flag that is **disabled by default**. +The Confidential Epics feature is under development and not ready for production use. +It's 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. @@ -175,14 +170,14 @@ To add an issue to an epic: 1. Identify the issue to be added, using either of the following methods: - Paste the link of the issue. - Search for the desired issue by entering part of the issue's title, then selecting the desired - match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126)). + match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step. 1. Click **Add**. #### Create an issue from an epic -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5419) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5419) in GitLab 12.7. Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts. @@ -195,46 +190,49 @@ To create an issue from an epic: 1. From the **Project** dropdown, select the project in which the issue should be created. 1. Click **Create issue**. +### Remove an issue from an epic + +You can remove issues from an epic when you're on the epic's details page. +After you remove an issue from an epic, the issue will no longer be associated with this epic. + To remove an issue from an epic: -1. Click the <kbd>x</kbd> button in the epic's issue list. -1. Click **Remove** in the **Remove issue** warning message. +1. Click the **Remove** (**{close}**) button next to the issue you want to remove. + The **Remove issue** warning appears. +1. Click **Remove**. + + ### Reorder issues assigned to an epic -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. -New issues are added to the top of their list in the **Epics and Issues** tab. -You can reorder the list of issues. Issues and child epics cannot be intermingled. +New issues appear at the top of the list in the **Epics and Issues** tab. +You can reorder the list of issues by dragging them. To reorder issues assigned to an epic: 1. Go to the **Epics and Issues** tab. -1. Drag and drop issues into the desired order. - -To reorder child epics assigned to an epic: - -1. Go to the **Epics and Issues** tab. -1. Drag and drop epics into the desired order. +1. Drag issues into the desired order. ### Move issues between epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -New issues are added to the top of their list in the **Epics and Issues** -tab. You can move issues from one epic to another. Issues and child epics cannot be intermingled. +New issues appear at the top of the list in the **Epics and Issues** +tab. You can move issues from one epic to another. To move an issue to another epic: 1. Go to the **Epics and Issues** tab. -1. Drag and drop issues into the desired parent epic. +1. Drag issues into the desired parent epic. ### Promote an issue to an epic -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -If you have [permissions](../../permissions.md) to close an issue and create an +If you have the necessary [permissions](../../permissions.md) to close an issue and create an epic in the parent group, you can promote an issue to an epic with the `/promote` [quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). Only issues from projects that are in groups can be promoted. When attempting to promote a confidential @@ -263,7 +261,8 @@ To add a child epic to an epic: 1. Click **Add an epic**. 1. Identify the epic to be added, using either of the following methods: - Paste the link of the epic. - - Search for the desired issue by entering part of the epic's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126)). + - Search for the desired issue by entering part of the epic's title, then selecting the desired + match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step. 1. Click **Add**. @@ -272,7 +271,7 @@ To add a child epic to an epic: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -New child epics are added to the top of their list in the **Epics and Issues** tab. +New child epics appear at the top of the list in the **Epics and Issues** tab. You can move child epics from one epic to another. When you add an epic that's already linked to a parent epic, the link to its current parent is removed. Issues and child epics cannot be intermingled. @@ -280,19 +279,19 @@ Issues and child epics cannot be intermingled. To move child epics to another epic: 1. Go to the **Epics and Issues** tab. -1. Drag and drop epics into the desired parent epic. +1. Drag epics into the desired parent epic. ### Reorder child epics assigned to an epic -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. -New child epics are added to the top of their list in the **Epics and Issues** tab. -You can reorder the list of child epics. Issues and child epics cannot be intermingled. +New child epics appear at the top of the list in the **Epics and Issues** tab. +You can reorder the list of child epics. To reorder child epics assigned to an epic: 1. Go to the **Epics and Issues** tab. -1. Drag and drop epics into the desired order. +1. Drag epics into the desired order. ### Remove a child epic from a parent epic 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 differnew file mode 100644 index 00000000000..1b0a20b7e64 --- /dev/null +++ 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 differnew file mode 100644 index 00000000000..3fc1f28becd --- /dev/null +++ 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 differnew file mode 100644 index 00000000000..504e6ab3a42 --- /dev/null +++ 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 f36f3b3fd4f..324c912b2be 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Groups @@ -17,7 +20,7 @@ Find your groups by clicking **Groups > Your Groups** in the top navigation.  -> The **Groups** dropdown in the top navigation was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/36234) in [GitLab 11.1](https://about.gitlab.com/releases/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation). +> The **Groups** dropdown in the top navigation was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36234) in [GitLab 11.1](https://about.gitlab.com/releases/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation). The **Groups** page displays: @@ -183,7 +186,7 @@ of a group: ## Changing the default branch protection of a group -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7583) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. By default, every group inherits the branch protection set at the global level. @@ -214,7 +217,7 @@ There are two different ways to add a new project to a group: ### Default project-creation level -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2534) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. > - Brought to [GitLab Starter](https://about.gitlab.com/pricing/) in 10.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. @@ -287,7 +290,7 @@ Alternatively, you can [lock the sharing with group feature](#share-with-group-l ## Sharing a group with another group -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18328) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. Similarly to [sharing a project with a group](#sharing-a-project-with-a-group), you can share a group with another group to give direct group members access @@ -306,8 +309,50 @@ All the members of the 'Engineering' group will have been added to 'Frontend'. ## Manage group memberships via LDAP -In GitLab Enterprise Edition, it is possible to manage GitLab group memberships using LDAP groups. -See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information. +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. + +Group links can be created using either a CN or a filter. These group links are created on the **Group Settings -> LDAP Synchronization** page. After configuring the link, it may take over an hour for the users to sync with the GitLab group. + +For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync-starter-only). + +NOTE: **Note:** +If an LDAP user is a group member when LDAP Synchronization is added, and they are not part of the LDAP group, they will be removed from the group. + +### Creating group links via CN **(STARTER ONLY)** + +To create group links via CN: + +1. Select the **LDAP Server** for the link. +1. Select `LDAP Group cn` as the **Sync method**. +1. In the **LDAP Group cn** text input box, begin typing the CN of the group. There will be a dropdown menu with matching CNs within the configured `group_base`. Select your CN from this list. +1. In the **LDAP Access** section, select the [permission level](../permissions.md) for users synced in this group. +1. Click the `Add Synchronization` button to save this group link. + + + +### Creating group links via filter **(PREMIUM ONLY)** + +To create group links via filter: + +1. Select the **LDAP Server** for the link. +1. Select `LDAP user filter` as the **Sync method**. +1. Input your filter in the **LDAP User filter** box. Follow the [documentation on user filters](../../administration/auth/ldap/index.md#set-up-ldap-user-filter-core-only). +1. In the **LDAP Access** section, select the [permission level](../permissions.md) for users synced in this group. +1. Click the `Add Synchronization` button to save this group link. + + + +### Overriding user permissions **(STARTER ONLY)** + +Since GitLab [v8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) LDAP user permissions can now be manually overridden by an admin user. To override a user's permissions: + +1. Go to your group's **Members** page. +1. Select the pencil icon in the row for the user you are editing. +1. Select the orange `Change permissions` button. + + + +Now you will be able to edit the user's permissions from the **Members** page. ## Epics **(ULTIMATE)** @@ -407,11 +452,11 @@ 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-adjourned-period-premium-only). ### Restore a group **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33257) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. To restore a group that is marked for deletion: @@ -460,9 +505,10 @@ This will disable the option for all users who previously had permissions to operate project memberships, so no new users can be added. Furthermore, any request to add a new user to a project through API will not be possible. -#### IP access restriction **(ULTIMATE)** +#### IP access restriction **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1985) in [GitLab Ultimate and Gold](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate and Gold](https://about.gitlab.com/pricing/) 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium and Silver](https://about.gitlab.com/pricing/) in 13.1. To make sure only people from within your organization can access particular resources, you have the option to restrict access to groups and their @@ -470,28 +516,27 @@ underlying projects, issues, etc, by IP address. This can help ensure that particular content doesn't leave the premises, while not blocking off access to the entire instance. -Add one or more whitelisted IP subnets using CIDR notation in comma separated format to the group settings and anyone +Add one or more allowed IP subnets using CIDR notation in comma separated format to the group settings and anyone coming from a different IP address won't be able to access the restricted content. Restriction currently applies to: - UI. -- [From GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/issues/12874), API access. -- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/32113), Git actions via SSH. +- [From GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), API access. +- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/32113), Git actions via SSH. To avoid accidental lock-out, admins and group owners are able to access the group regardless of the IP restriction. #### Allowed domain restriction **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7297) in [GitLab Premium and Silver](https://about.gitlab.com/pricing/) 12.2. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium and Silver](https://about.gitlab.com/pricing/) 12.2. +>- Support for specifying multiple email domains [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1 -You can restrict access to groups by -allowing only users with email addresses in particular domains to be added to the group. +You can restrict access to groups by allowing only users with email addresses in particular domains to be added to the group. -Add email domains you want to whitelist and users with emails from different -domains won't be allowed to be added to this group. +Add email domains you want to allow and users with emails from different domains won't be allowed to be added to this group. Some domains cannot be restricted. These are the most popular public email domains, such as: @@ -509,7 +554,7 @@ Some domains cannot be restricted. These are the most popular public email domai To enable this feature: 1. Navigate to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and enter the domain name into **Restrict membership by email** field. +1. Expand the **Permissions, LFS, 2FA** section, and enter the domain names into **Restrict membership by email** field. You can enter multiple domains by separating each domain with a comma (,). 1. Click **Save changes**. This will enable the domain-checking for all new users added to the group from this moment on. @@ -545,7 +590,7 @@ Define project templates at a group level by setting a group as the template sou #### Disabling email notifications -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/23585) in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23585) in GitLab 12.2. You can disable all email notifications related to the group, which includes its subgroups and projects. @@ -557,7 +602,7 @@ To enable this feature: #### Disabling group mentions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/21301) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21301) in GitLab 12.6. You can prevent users from being added to a conversation and getting notified when anyone mentions a group in which those users are members. @@ -598,7 +643,7 @@ If your namespace shows `N/A` as the total storage usage, you can trigger a reca #### Group push rules **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. Group push rules allow group maintainers to set [push rules](../../push_rules/push_rules.md) for newly created projects within the specific group. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index cffbc013e66..dd1f8914392 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -2,8 +2,7 @@ type: reference, howto stage: Manage group: Analytics -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 +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 --- # Insights **(ULTIMATE)** 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 differnew file mode 100644 index 00000000000..0f94f1ba2c5 --- /dev/null +++ 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 df96f2626e1..01cee3d09b8 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -2,14 +2,13 @@ type: reference stage: Manage group: Analytics -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 +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)** -> - [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. +> - [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. The default timespan is 13 months, which includes the current month, and the 12 months @@ -35,6 +34,17 @@ shows a total of 15 months for the chart in the GitLab.org group.  +## Drill into the information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196547) in GitLab 13.1. + +You can examine details of individual issues by browsing the table +located below the chart. + +The chart displays the top 100 issues based on the global page filters. + + + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md new file mode 100644 index 00000000000..2704147dcdd --- /dev/null +++ b/doc/user/group/iterations/index.md @@ -0,0 +1,85 @@ +--- +type: reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Iterations **(STARTER)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in [GitLab Starter](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 able to be enabled or disabled per-group +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-iterations-core-only). **(CORE ONLY)** + +Iterations are a way to track issues over a period of time. This allows teams +to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) +for tracking over different time periods. + +For example, you can use: + +- Milestones for Program Increments, which span 8-12 weeks. +- Iterations for Sprints, which span 2 weeks. + +In GitLab, iterations are similar to milestones, with a few differences: + +- Iterations are only available to groups. +- A group can only have one active iteration at a time. +- Iterations require both a start and an end date. +- Iteration date ranges cannot overlap. + +## View the iterations list + +To view the iterations list, in a group, go to **{issues}** **Issues > Iterations**. +From there you can create a new iteration or click an iteration to get a more detailed view. + +## Create an iteration + +NOTE: **Note:** +A permission level of [Developer or higher](../../permissions.md) is required to create iterations. + +To create an iteration: + +1. In a group, go to **{issues}** **Issues > Iterations**. +1. Click **New iteration**. +1. Enter the title, a description (optional), a start date, and a due date. +1. Click **Create iteration**. The iteration details page opens. + +### Enable Iterations **(CORE ONLY)** + +GitLab Iterations feature 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. `:group_iterations` can be enabled or disabled per-group. + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:group_iterations) +# or by group +Feature.enable(:group_iterations, Group.find(<group id>)) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:group_iterations) +# or by group +Feature.disable(:group_iterations, Group.find(<group id>)) +``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 6bee552d433..614ed700cfc 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -1,14 +1,17 @@ --- type: reference +stage: Plan +group: Portfolio 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 --- # Roadmap **(PREMIUM)** > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5. -> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/issues/198062), Roadmaps were moved to the Premium tier. -> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/issues/5164) and later, the epic bars show epics' title, progress, and completed weight percentage. -> - Milestones appear in Roadmaps in [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/6802), and later. -> - Feature flag removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29641). +> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198062), Roadmaps were moved to the Premium tier. +> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/5164) and later, the epic bars show epics' title, progress, and completed weight percentage. +> - Milestones appear in roadmaps in [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/6802), and later. +> - Feature flag for milestones visible in roadmaps removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29641). Epics and milestones within a group containing **Start date** and/or **Due date** can be visualized in a form of a timeline (that is, a Gantt chart). The Roadmap page @@ -45,7 +48,7 @@ Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-ep ## Timeline duration > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/issues/198062), Timelines were moved to the Premium tier. +> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198062), Timelines were moved to the Premium tier. Roadmap supports the following date ranges: diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index a3d9a14df10..81684038dc2 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # SAML SSO for GitLab.com groups **(SILVER ONLY)** @@ -54,14 +57,14 @@ We recommend setting the NameID format to `Persistent` unless using a field (suc ### SSO enforcement -- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5291) in GitLab 11.8. -- [Improved](https://gitlab.com/gitlab-org/gitlab/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. +- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. With this option enabled, users must use your group's GitLab single sign on URL to be added to the group or be added via SCIM. 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 log via SSO on each visit. GitLab will check whether a user has authenticated through the SSO link, and will only prompt the user to login via SSO if the session has expired. -We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/issues/9152) in the future. +We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in the future. When SSO enforcement is enabled for a group, users cannot share a project in the group outside the top-level group, even if the project is forked. @@ -82,7 +85,7 @@ When this option is enabled: Upon successful authentication, GitLab prompts the user with options, based on the email address received from the configured identity provider: - 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).) +- 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: @@ -100,7 +103,7 @@ Feature.enable(:group_managed_accounts) ##### Credentials inventory for Group-managed accounts **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/38133) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38133) in GitLab 12.8. Owners who manage user accounts in a group can view the following details of personal access tokens and SSH keys: @@ -140,7 +143,7 @@ Once a lifetime for personal access tokens is set, GitLab will: ##### Outer forks restriction for Group-managed accounts -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34648) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34648) in GitLab 12.9. Groups with group-managed accounts can disallow forking of projects to destinations outside the group. To do so, enable the "Prohibit outer forks" option in **Settings > SAML SSO**. @@ -148,7 +151,7 @@ When enabled, projects within the group can only be forked to other destinations ##### Other restrictions for Group-managed accounts -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12420) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12420) in GitLab 12.9. Projects within groups with enabled group-managed accounts are not to be shared with: @@ -231,7 +234,7 @@ NOTE: **Note:** GitLab is unable to provide support for IdPs that are not listed |----------|---------------| | 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) | -| Okta | [Setting up a SAML application in Okta](https://developer.okta.com/docs/guides/saml-application-setup/overview/) | +| 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) | When [configuring your identify provider](#configuring-your-identity-provider), please consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. @@ -373,8 +376,8 @@ To proceed with configuring Group SAML SSO instead, you'll need to enable the `g Group SAML on a self-managed instance is limited when compared to the recommended [instance-wide SAML](../../../integration/saml.md). The recommended solution allows you to take advantage of: -- [LDAP compatibility](../../../administration/auth/ldap.md). -- [LDAP group Sync](../../../administration/auth/how_to_configure_ldap_gitlab_ee/index.md#group-sync). +- [LDAP compatibility](../../../administration/auth/ldap/index.md). +- [LDAP Group Sync](../index.md#manage-group-memberships-via-ldap) - [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). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index f66c8a788b6..a891962b38e 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,5 +1,8 @@ --- type: howto, reference +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # SCIM provisioning using SAML SSO for GitLab.com groups **(SILVER ONLY)** @@ -117,7 +120,7 @@ Once synchronized, changing the field mapped to `id` and `externalId` will likel ### Okta configuration steps -The SAML application that was created during [Single sign-on](index.md#okta-setup-notes) setup for [Okta](https://developer.okta.com/docs/guides/saml-application-setup/overview/) now needs to be set up for SCIM. +The SAML application that was created during [Single sign-on](index.md#okta-setup-notes) setup for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) now needs to be set up for SCIM. Before proceeding, be sure to complete the [GitLab configuration](#gitlab-configuration) process. 1. Sign in to Okta. diff --git a/doc/user/group/settings/img/export_panel.png b/doc/user/group/settings/img/export_panel.png Binary files differdeleted file mode 100644 index 2a987f04e35..00000000000 --- a/doc/user/group/settings/img/export_panel.png +++ /dev/null diff --git a/doc/user/group/settings/img/export_panel_v13_0.png b/doc/user/group/settings/img/export_panel_v13_0.png Binary files differnew file mode 100644 index 00000000000..36549e1f3f5 --- /dev/null +++ b/doc/user/group/settings/img/export_panel_v13_0.png diff --git a/doc/user/group/settings/img/import_panel_v13_1.png b/doc/user/group/settings/img/import_panel_v13_1.png Binary files differnew file mode 100644 index 00000000000..ce2eb579446 --- /dev/null +++ b/doc/user/group/settings/img/import_panel_v13_1.png diff --git a/doc/user/group/settings/img/new_group_navigation_v13_1.png b/doc/user/group/settings/img/new_group_navigation_v13_1.png Binary files differnew file mode 100644 index 00000000000..98d45a694b6 --- /dev/null +++ b/doc/user/group/settings/img/new_group_navigation_v13_1.png diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 3f14fea673b..cca918d44f3 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -1,3 +1,9 @@ +--- +type: reference +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 +--- # Group Import/Export > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. @@ -61,7 +67,7 @@ For more details on the specific data persisted in a group export, see the 1. In the **Advanced** section, click the **Export Group** button. -  +  1. Once the export is generated, you should receive an e-mail with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in JSON format. @@ -69,12 +75,37 @@ For more details on the specific data persisted in a group export, see the 1. Alternatively, you can come back to the project settings and download the file from there by clicking **Download export**, or generate a new file by clicking **Regenerate export**. +NOTE: **Note:** +The maximum import file size can be set by the Administrator, default is 50MB. +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). + ### Between CE and EE You can export groups from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. 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). +## Importing the group + +1. Navigate to the New Group page, either via the `+` button in the top navigation bar, or the **New subgroup** button +on an existing group's page. + +  + +1. On the New Group page, select the **Import group** tab. + +  + +1. Enter your group name. + +1. Accept or modify the associated group URL. + +1. Click **Choose file** + +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. + ## Version history GitLab can import bundles that were exported from a different GitLab deployment. @@ -92,7 +123,8 @@ For example: To help avoid abuse, users are rate limited to: -| Request Type | Limit | -| ---------------- | ------------------------------ | -| Export | 1 group every 5 minutes | -| Download export | 10 downloads every 10 minutes | +| Request Type | Limit | +| ---------------- | ---------------------------------------- | +| Export | 30 groups every 5 minutes | +| Download export | 10 downloads per group every 10 minutes | +| Import | 30 groups every 5 minutes | diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 49f6ddc3986..842e2082be4 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -4,7 +4,7 @@ type: reference, howto, concepts # Subgroups -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2772) in GitLab 9.0. +> [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. @@ -139,7 +139,7 @@ From the image above, we can deduce the following things: - Administrator is the Owner and member of **all** subgroups and for that reason, as with User3, there is no indication of an ancestor group. -[From](https://gitlab.com/gitlab-org/gitlab/issues/21727) GitLab 12.6, you can filter +[From](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) GitLab 12.6, you can filter this list using dropdown on the right side:  diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md index 73d6e0e055d..48805bda909 100644 --- a/doc/user/incident_management/index.md +++ b/doc/user/incident_management/index.md @@ -7,47 +7,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Incident Management GitLab offers solutions for handling incidents in your applications and services, -from setting up an alert with Prometheus, to receiving a notification through a -monitoring tool like Slack, and [setting up Zoom calls](#zoom-integration-in-issues) with your -support team. Incidents can display [metrics](#embed-metrics-in-incidents-and-issues) -and [logs](#view-logs-from-metrics-panel). +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. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in GitLab Ultimate 11.11. -You can enable or disable Incident Management features in your project's -**{settings}** **Settings > Operations > Incidents**. Issues can be created for -each alert triggered, and separate email notifications can be sent to users with -[Developer permissions](../permissions.md). Appropriately configured alerts include an -[embedded chart](../project/integrations/prometheus.md#embedding-metrics-based-on-alerts-in-incident-issues) -for the query corresponding to the alert. You can also configure GitLab to -[close issues](../project/integrations/prometheus.md#taking-action-on-incidents-ultimate) -when you receive notification that the alert is resolved. - - +You can enable or disable Incident Management features in the GitLab user interface +to create issues when alerts are triggered: -### Create issues from alerts +1. Navigate to **{settings}** **Settings > Operations > Incidents** and expand + **Incidents**: -You can create GitLab issues from an alert notification. These issues contain -information about the alerts to help you diagnose the source of the alerts. +  -1. Visit your project's **{settings}** **Settings > Operations > Incidents**. -1. Select the **Create an issue** checkbox for GitLab to create an issue from - the incident. -1. Select the template from the **Issue Template** dropdown. - You can create your own [issue templates](../project/description_templates.md#creating-issue-templates) - to [use within Incident Management](../project/integrations/prometheus.md#taking-action-on-incidents-ultimate). +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 + [Taking Action on Incidents](../project/integrations/prometheus.md#taking-action-on-incidents-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**. -## Notify developers of alerts +Appropriately configured alerts include an +[embedded chart](../project/integrations/prometheus.md#embedding-metrics-based-on-alerts-in-incident-issues) +for the query corresponding to the alert. You can also configure GitLab to +[close issues](../project/integrations/prometheus.md#taking-action-on-incidents-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. GitLab sends these emails -to [owners and maintainers](../permissions.md) of the project. They contain details -of the alert, and a link for more information. +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 Prometheus alerts +## Configure Prometheus alerts You can set up Prometheus alerts in: @@ -57,7 +59,7 @@ You can set up Prometheus alerts in: 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 +## 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), @@ -65,7 +67,7 @@ GitLab creates a unique endpoint which receives a JSON-formatted, customizable p ## Embed metrics in incidents and issues -You can embed metrics anywhere GitLab Markdown is used, such as descriptions, +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 @@ -78,10 +80,9 @@ in incidents and issue templates. ### Context menu -From each of the embedded metrics panels, you can access more details -about the data you're viewing from a context menu. You can access the context menu -by clicking the **{ellipsis_v}** **More actions** dropdown box above the -upper right corner of the panel. The options are: +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 @@ -89,7 +90,7 @@ upper right corner of the panel. The options are: #### View logs from metrics panel -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201846) in GitLab Ultimate 12.8. +> - [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 @@ -97,16 +98,16 @@ incident and need to [explore logs](../project/integrations/prometheus.md#view-l from across your application. These logs help you understand what is affecting your application's performance and resolve any problems. -## Slack integration +## 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). -## Zoom integration in issues +## 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, so your -team members can join without requesting a link. +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. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 65237bf24e0..c17d1831b50 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -22,136 +22,146 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -To get started, there are two different options when using GitLab managed Terraform State. +To get started with a GitLab-managed Terraform State, there are two different options: -- Use a local machine -- Use GitLab CI +- [Use a local machine](#get-started-using-local-development). +- [Use GitLab CI](#get-started-using-gitlab-ci). -## Get Started using local development +## Get started using local development -If you are planning to only run `terraform plan` and `terraform apply` commands from your local machine, this is a simple way to get started. +If you plan to only run `terraform plan` and `terraform apply` commands from your +local machine, this is a simple way to get started: -First, create your project on your GitLab instance. +1. Create your project on your GitLab instance. +1. Navigate to **{settings}** **Settings > General** and note your **Project name** + and **Project ID**. +1. Define the Terraform backend in your Terraform project to be: -Next, define the Terraform backend in your Terraform project to be: - -```hcl -terraform { - backend "http" { - } -} -``` - -Finally, you need to run `terraform init` on your local machine and pass in the following options. The below example is using GitLab.com: - -```bash -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="username=<YOUR-USERNAME>" \ - -backend-config="password=<YOUR-ACCESS-TOKEN>" \ - -backend-config="lock_method=POST" \ - -backend-config="unlock_method=DELETE" \ - -backend-config="retry_wait_min=5" -``` - -This will initialize your Terraform state and store that state within your GitLab project. - -NOTE: YOUR-PROJECT-ID and YOUR-PROJECT-NAME can be accessed from the project main page. - -## Get Started using a GitLab CI - -Another route is to leverage GitLab CI to run your `terraform plan` and `terraform apply` commands. - -### Configure the CI variables + ```hcl + terraform { + backend "http" { + } + } + ``` -To use the Terraform backend, [first create a Personal Access Token](../profile/personal_access_tokens.md) with the `api` scope. Keep in mind that the Terraform backend is restricted to tokens with [Maintainer access](../permissions.md) to the repository. +1. Create a [Personal Access Token](../profile/personal_access_tokens.md) with + the `api` scope. The Terraform backend is restricted to users with + [Maintainer access](../permissions.md) to the repository. + +1. On your local machine, run `terraform init`, passing in the following options, + replacing `<YOUR-PROJECT-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="username=<YOUR-USERNAME>" \ + -backend-config="password=<YOUR-ACCESS-TOKEN>" \ + -backend-config="lock_method=POST" \ + -backend-config="unlock_method=DELETE" \ + -backend-config="retry_wait_min=5" + ``` -To keep the Personal Access Token secure, add it as a [CI/CD environment variable](../../ci/variables/README.md). In this example we set ours to the ENV: `GITLAB_TF_PASSWORD`. +Next, [configure the backend](#configure-the-backend). -If you are planning to use the ENV on a branch which is not protected, make sure to set the variable protection settings correctly. +## Get started using GitLab CI -### Configure the Terraform backend +If you don't want to start with local development, you can also use GitLab CI to +run your `terraform plan` and `terraform apply` commands. -Next we need to define the [http backend](https://www.terraform.io/docs/backends/types/http.html). In your Terraform project add the following code block in a `.tf` file such as `backend.tf` or wherever you desire to define the remote backend: +Next, [configure the backend](#configure-the-backend). -```hcl -terraform { - backend "http" { - } -} -``` +## Configure the backend -### Configure the CI YAML file +After executing the `terraform init` command, you must configure the Terraform backend +and the CI YAML file: -Finally, configure a `.gitlab-ci.yaml`, which lives in the root of your project repository. +CAUTION: **Important:** +The Terraform backend is restricted to users with [Maintainer access](../permissions.md) +to the repository. -In our case we are using a pre-built image: +1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/backends/types/http.html) + by adding the following code block in a `.tf` file (such as `backend.tf`) to + define the remote backend: -```yaml -image: - name: hashicorp/terraform:light - entrypoint: - - '/usr/bin/env' - - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' -``` - -We then define some environment variables to make life easier. `GITLAB_TF_ADDRESS` is the URL of the GitLab instance where this pipeline runs, and `TF_ROOT` is the directory where the Terraform commands must be executed. - -```yaml -variables: - GITLAB_TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME} - TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production - -cache: - paths: - - .terraform -``` + ```hcl + terraform { + backend "http" { + } + } + ``` -In a `before_script`, pass a `terraform init` call containing configuration parameters. -These parameters correspond to variables required by the -[http backend](https://www.terraform.io/docs/backends/types/http.html): +1. In the root directory of your project repository, configure a `.gitlab-ci.yaml` file. + This example uses a pre-built image: -```yaml -before_script: - - cd ${TF_ROOT} - - terraform --version - - terraform init -backend-config="address=${GITLAB_TF_ADDRESS}" -backend-config="lock_address=${GITLAB_TF_ADDRESS}/lock" -backend-config="unlock_address=${GITLAB_TF_ADDRESS}/lock" -backend-config="username=${GITLAB_USER_LOGIN}" -backend-config="password=${GITLAB_TF_PASSWORD}" -backend-config="lock_method=POST" -backend-config="unlock_method=DELETE" -backend-config="retry_wait_min=5" + ```yaml + image: + name: hashicorp/terraform:light + entrypoint: + - '/usr/bin/env' + - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' + ``` -stages: - - validate - - build - - test - - deploy +1. In the `.gitlab-ci.yaml` file, define some environment variables to ease development. In this + example, `GITLAB_TF_ADDRESS` is the URL of the GitLab instance where this pipeline + runs, and `TF_ROOT` is the directory where the Terraform commands must be executed: -validate: - stage: validate - script: - - terraform validate + ```yaml + variables: + GITLAB_TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME} + TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production -plan: - stage: build - script: - - terraform plan - - terraform show + cache: + paths: + - .terraform + ``` -apply: - stage: deploy - environment: - name: production - script: - - terraform apply - dependencies: - - plan - when: manual - only: - - master -``` +1. In a `before_script`, pass a `terraform init` call containing configuration parameters + corresponding to variables required by the + [HTTP backend](https://www.terraform.io/docs/backends/types/http.html): -### Push to GitLab + ```yaml + before_script: + - cd ${TF_ROOT} + - terraform --version + - terraform init -backend-config="address=${GITLAB_TF_ADDRESS}" -backend-config="lock_address=${GITLAB_TF_ADDRESS}/lock" -backend-config="unlock_address=${GITLAB_TF_ADDRESS}/lock" -backend-config="username=gitlab-ci-token" -backend-config="password=${CI_JOB_TOKEN}" -backend-config="lock_method=POST" -backend-config="unlock_method=DELETE" -backend-config="retry_wait_min=5" + + stages: + - validate + - build + - test + - deploy + + validate: + stage: validate + script: + - terraform validate + + plan: + stage: build + script: + - terraform plan + - terraform show + + apply: + stage: deploy + environment: + name: production + script: + - terraform apply + dependencies: + - plan + when: manual + only: + - master + ``` -Pushing your project to GitLab triggers a CI job pipeline, which runs the `terraform init`, `terraform validate`, and `terraform plan` commands automatically. +1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline runs + the `terraform init`, `terraform validate`, and `terraform plan` commands. The output from the above `terraform` commands should be viewable in the job logs. @@ -161,14 +171,14 @@ See [this reference project](https://gitlab.com/nicholasklick/gitlab-terraform-a ## Output Terraform Plan information into a merge request -Using the [GitLab Terraform Report Artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform), +Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform), you can expose details from `terraform plan` runs directly into a merge request widget, enabling you to see statistics about the resources that Terraform will create, modify, or destroy. -Let's explore how to configure a GitLab Terraform Report Artifact: +Let's explore how to configure a GitLab Terraform Report artifact: -1. First, for simplicity, let's define a few reusable variables to allow us to +1. For simplicity, let's define a few reusable variables to allow us to refer to these files multiple times: ```yaml @@ -177,96 +187,39 @@ Let's explore how to configure a GitLab Terraform Report Artifact: PLAN_JSON: tfplan.json ``` -1. Next we need to install `jq`, a [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). We will also create an alias for a specific `jq` command that parses out the extact information we want to extract from the `terraform plan` output: - -```yaml -before_script: - - apk --no-cache add jq - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" -``` - -1. Finally, we define a `script` that runs `terraform plan` and also a `terraform show` which pipes the output and converts the relevant bits into a store variable `PLAN_JSON`. This json is then leveraged to create a [GitLab Terraform Report Artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform). - -The terraform report obtains a Terraform tfplan.json file. The collected Terraform plan report will be uploaded to GitLab as an artifact and will be automatically shown in merge requests. - -```yaml -plan: - stage: build - script: - - terraform plan -out=$PLAN - - terraform show --json $PLAN | convert_report > $PLAN_JSON - artifacts: - name: plan - paths: - - $PLAN - reports: - terraform: $PLAN_JSON -``` - -A full `.gitlab-ci.yaml` file could look like this: - -```yaml -image: - name: hashicorp/terraform:light - entrypoint: - - '/usr/bin/env' - - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' - -# Default output file for Terraform plan -variables: - GITLAB_TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME} - PLAN: plan.tfplan - PLAN_JSON: tfplan.json - TF_ROOT: ${CI_PROJECT_DIR} - -cache: - paths: - - .terraform - -before_script: - - apk --no-cache add jq - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" - - cd ${TF_ROOT} - - terraform --version - - terraform init -backend-config="address=${GITLAB_TF_ADDRESS}" -backend-config="lock_address=${GITLAB_TF_ADDRESS}/lock" -backend-config="unlock_address=${GITLAB_TF_ADDRESS}/lock" -backend-config="username=${GITLAB_USER_LOGIN}" -backend-config="password=${GITLAB_TF_PASSWORD}" -backend-config="lock_method=POST" -backend-config="unlock_method=DELETE" -backend-config="retry_wait_min=5" - -stages: - - validate - - build - - deploy +1. Install `jq`, a + [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). +1. Create an alias for a specific `jq` command that parses out the information we + want to extract from the `terraform plan` output: -validate: - stage: validate - script: - - terraform validate + ```yaml + before_script: + - apk --no-cache add jq + - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" + ``` -plan: - stage: build - script: - - terraform plan -out=$PLAN - - terraform show --json $PLAN | convert_report > $PLAN_JSON - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.tfplan - reports: - terraform: ${TF_ROOT}/tfplan.json +1. Define a `script` that runs `terraform plan` and `terraform show`. These commands + pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. + This JSON is used to create a + [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform). + The Terraform report obtains a Terraform `tfplan.json` file. The collected + Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. -# Separate apply job for manual launching Terraform as it can be destructive -# action. -apply: - stage: deploy - environment: - name: production - script: - - terraform apply -input=false $PLAN - dependencies: - - plan - when: manual - only: - - master + ```yaml + plan: + stage: build + script: + - terraform plan -out=$PLAN + - terraform show --json $PLAN | convert_report > $PLAN_JSON + artifacts: + name: plan + paths: + - $PLAN + reports: + terraform: $PLAN_JSON + ``` -``` + For a full example, see [Example `.gitlab-ci.yaml` file](#example-gitlab-ciyaml-file). 1. Running the pipeline displays the widget in the merge request, like this: diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 495bfdeed6e..8059b8ca642 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -1,6 +1,6 @@ # Instance-level Kubernetes clusters -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/39840) in GitLab 11.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. ## Overview @@ -12,8 +12,7 @@ projects. ## Cluster precedence -GitLab will try [to match](../../../ci/environments/index.md#scoping-environments-with-specs) clusters in -the following order: +GitLab will try to match clusters in the following order: - Project-level clusters. - Group-level clusters. diff --git a/doc/user/instance_statistics/dev_ops_score.md b/doc/user/instance_statistics/dev_ops_score.md index 216a79f8beb..73b9532015d 100644 --- a/doc/user/instance_statistics/dev_ops_score.md +++ b/doc/user/instance_statistics/dev_ops_score.md @@ -1,7 +1,7 @@ # DevOps Score -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30469) in GitLab 9.3. -> - [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/issues/20976) in GitLab 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30469) in GitLab 9.3. +> - [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. 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. diff --git a/doc/user/instance_statistics/index.md b/doc/user/instance_statistics/index.md index 15e061b118e..b09651e04ee 100644 --- a/doc/user/instance_statistics/index.md +++ b/doc/user/instance_statistics/index.md @@ -1,6 +1,6 @@ # Instance statistics -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41416) in GitLab 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. Instance statistics gives users or admins access to instance-wide analytics. They are accessible to all users by default (GitLab admins can restrict its diff --git a/doc/user/instance_statistics/user_cohorts.md b/doc/user/instance_statistics/user_cohorts.md index b3ef99473e4..8da2d57d474 100644 --- a/doc/user/instance_statistics/user_cohorts.md +++ b/doc/user/instance_statistics/user_cohorts.md @@ -1,6 +1,6 @@ # Cohorts -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/23361) in GitLab 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23361) in GitLab 9.1. As a benefit of having the [usage ping active](../admin_area/settings/usage_statistics.md), GitLab lets you analyze the users' activities over time of your GitLab installation. @@ -24,6 +24,6 @@ How do we measure the activity of users? GitLab considers a user active if: - The user signs in. - The user has Git activity (whether push or pull). -- The user visits pages related to Dashboards, Projects, Issues, and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/54947) in GitLab 11.8). +- The user visits pages related to Dashboards, Projects, Issues, and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8). - The user uses the API - The user uses the GraphQL API diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 102eb1f8f53..0d028cfe77a 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab Markdown This Markdown guide is **valid only for GitLab's internal Markdown rendering system for entries and files**. @@ -5,7 +11,7 @@ It is **not** valid for the [GitLab documentation website](https://docs.gitlab.c or [GitLab's main website](https://about.gitlab.com), as they both use [Kramdown](https://kramdown.gettalong.org) as their Markdown engine. The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). -Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/engineering/ux/technical-writing/markdown-guide/) +Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/) for a complete Kramdown reference. NOTE: **Note:** We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md). @@ -76,7 +82,7 @@ NOTE: **Note:** We will flag any significant differences between Redcarpet and C 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 [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) -tool (not an officially supported product) to generate a list of files, and the +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 to change. @@ -253,7 +259,7 @@ Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) > **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 fallback to image-based emoji where there is lack of support. +Most emoji are natively supported on macOS, Windows, iOS, Android, and will 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/) to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has @@ -272,7 +278,7 @@ in a box at the top of the document, before the rendered HTML content. To view a you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md). In GitLab, front matter is only used in Markdown files and wiki pages, not the other -places where Markdown formatting is supported. It must be at the very top of the document, +places where Markdown formatting is supported. It must be at the very top of the document and must be between delimiters, as explained below. The following delimiters are supported: @@ -405,7 +411,7 @@ GFM recognizes special GitLab related references. For example, you can easily re an issue, a commit, a team member, or even the whole team within a project. GFM will turn that reference into a link so you can navigate between them easily. -Additionally, GFM recognizes certain cross-project references, and also has a shorthand +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: @@ -435,8 +441,8 @@ 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)`. - **(PREMIUM)** +- 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]`. ### Task lists @@ -825,7 +831,7 @@ Regardless of the tag names, the relative order of the reference tags determines numbering. Reference tags can use letters and other characters. Avoid using lowercase `w` or an underscore -(`_`) in footnote tag names until [this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is +(`_`) in footnote tag names until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/24423) is resolved. <!-- @@ -1011,7 +1017,7 @@ You can also use raw HTML in your Markdown, and it will usually work pretty well See the documentation for HTML::Pipeline's [SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42) class for the list of allowed HTML tags and attributes. In addition to the default -`SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements. +`SanitizationFilter` allowlist, GitLab allows `span`, `abbr`, `details` and `summary` elements. ```html <dl> @@ -1103,6 +1109,11 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded. Markdown inside these tags is supported as well. +NOTE: **Note:** +If your Markdown isn't rendering correctly, try adding +`{::options parse_block_html="true" /}` to the top of the page, and add +`markdown="span"` to the opening summary tag like this: `<summary markdown="span">`. + Remember to leave a blank line after the `</summary>` tag and before the `</details>` tag, as shown in the example: @@ -1427,7 +1438,9 @@ Example: 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. -> Note that the headers are always right aligned [within GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables). +NOTE: **Note:** +[Within GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables), +the headers are always left-aligned in Chrome and Firefox, and centered in Safari. ```markdown | Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | @@ -1443,7 +1456,7 @@ to the sides of the "dash" lines in the second row. This will affect every cell #### Copy from spreadsheet and paste in Markdown -[Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27205) in GitLab 12.7. +[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 diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 531422ca077..5a2ff410253 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,6 +1,6 @@ # Operations Dashboard **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. [Moved](https://gitlab.com/gitlab-org/gitlab/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md new file mode 100644 index 00000000000..8a7c70ec74d --- /dev/null +++ b/doc/user/packages/composer_repository/index.md @@ -0,0 +1,155 @@ +--- +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 +--- + +# GitLab Composer Repository **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. + +With the GitLab Composer Repository, every project can have its own space to store [Composer](https://getcomposer.org/) packages. + +## Enabling the Composer 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)** + +After the Composer Repository is enabled, it will be 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 > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages & Registries** section on the left sidebar. + +## Getting started + +This section will cover 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/). + +### Creating a package project + +Understanding how to create a full Composer project is outside the scope of this +guide, but you can create a small package to test out the registry. Start by +creating a new directory called `my-composer-package`: + +```shell +mkdir my-composer-package && cd my-composer-package +``` + +Create a new `composer.json` file inside this directory to set up the basic project: + +```shell +touch composer.json +``` + +Inside `composer.json`, add the following code: + +```json +{ + "name": "<namespace>/composer-test", + "type": "library", + "license": "GPL-3.0-only", + "version": "1.0.0" +} +``` + +Replace `<namespace>` with a unique namespace like your GitLab username or group name. + +After this basic package structure is created, we need to tag it in Git and push it to the repository. + +```shell +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 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: + +- 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`: + +```shell +curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer' +``` + +Where: + +- `<personal-access-token>` is your personal access token. +- `<project_id>` is your project ID. +- `<tag>` is the Git tag name of the version you want to publish. In this example it should be `v1.0.0`. Notice that instead of `tag=<tag>` you can also use `branch=<branch>` to publish branches. + +If the above command succeeds, you now should be able to see the package under the **Packages & Registries** section of your project page. + +### Installing a package + +To install your package you will 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. + +Add the GitLab Composer package repository to your existing project's `composer.json` file, along with the package name and version you want to install like so: + +```json +{ + ... + "repositories": [ + { "type": "composer", "url": "https://gitlab.com/api/v4/group/<group_id>/-/packages/composer/packages.json" } + ], + "require": { + ... + "<package_name>": "<version>" + }, + ... +} +``` + +Where: + +- `<group_id>` is the group ID found under your project's group page. +- `<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: + +```json +{ + "http-basic": { + "gitlab.com": { + "username": "___token___", + "password": "<personal_access_token>" + } + } +} +``` + +Where: + +- `<personal_access_token>` is your personal access token. + +With the `composer.json` and `auth.json` files configured, you can install the package by running `composer`: + +```shell +composer update +``` + +If successful, you should be able to see the output indicating that the package has been successfully installed. + +CAUTION: **Important:** +Make sure to never commit the `auth.json` file to your repository. To install packages from a CI job, +consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages-with-satis.md#authentication) tool with your personal access token +stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in +[Hashicorp Vault](../../../ci/examples/authenticating-with-hashicorp-vault/index.md). diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index a56a67d4959..020028dfc10 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -1,6 +1,12 @@ +--- +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 +--- + # GitLab Conan Repository **(PREMIUM)** -> [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. With the GitLab Conan Repository, every project can have its own space to store Conan packages. @@ -184,7 +190,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 will allow for more flexible naming conventions. ## Installing a package @@ -271,7 +277,7 @@ The GitLab Conan repository supports the following Conan CLI commands: ## Using GitLab CI with Conan packages -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. 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. diff --git a/doc/user/packages/container_registry/img/container_registry_group_repositories_v13_0.png b/doc/user/packages/container_registry/img/container_registry_group_repositories_v13_0.png Binary files differdeleted file mode 100644 index 14119abd56a..00000000000 --- a/doc/user/packages/container_registry/img/container_registry_group_repositories_v13_0.png +++ /dev/null diff --git a/doc/user/packages/container_registry/img/container_registry_group_repositories_v13_1.png b/doc/user/packages/container_registry/img/container_registry_group_repositories_v13_1.png Binary files differnew file mode 100644 index 00000000000..bbbba44eb9b --- /dev/null +++ b/doc/user/packages/container_registry/img/container_registry_group_repositories_v13_1.png diff --git a/doc/user/packages/container_registry/img/container_registry_repositories_v13_0.png b/doc/user/packages/container_registry/img/container_registry_repositories_v13_0.png Binary files differdeleted file mode 100644 index 7286007b953..00000000000 --- a/doc/user/packages/container_registry/img/container_registry_repositories_v13_0.png +++ /dev/null diff --git a/doc/user/packages/container_registry/img/container_registry_repositories_v13_1.png b/doc/user/packages/container_registry/img/container_registry_repositories_v13_1.png Binary files differnew file mode 100644 index 00000000000..13a6d1a4470 --- /dev/null +++ b/doc/user/packages/container_registry/img/container_registry_repositories_v13_1.png diff --git a/doc/user/packages/container_registry/img/container_registry_repositories_with_quickstart_v13_0.png b/doc/user/packages/container_registry/img/container_registry_repositories_with_quickstart_v13_0.png Binary files differdeleted file mode 100644 index f7c3aafcc8e..00000000000 --- a/doc/user/packages/container_registry/img/container_registry_repositories_with_quickstart_v13_0.png +++ /dev/null diff --git a/doc/user/packages/container_registry/img/container_registry_repositories_with_quickstart_v13_1.png b/doc/user/packages/container_registry/img/container_registry_repositories_with_quickstart_v13_1.png Binary files differnew file mode 100644 index 00000000000..35a02182a77 --- /dev/null +++ b/doc/user/packages/container_registry/img/container_registry_repositories_with_quickstart_v13_1.png diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 5e642e1e21c..eb1933de62a 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.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 +--- + # GitLab Container Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) in GitLab 8.8. @@ -20,7 +26,7 @@ have its own space to store its Docker images. You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. - + ## Enable the Container Registry for your project @@ -56,7 +62,7 @@ for both projects and groups. Navigate to your project's **{package}** **Packages & Registries > Container Registry**. - + This view will: @@ -71,7 +77,7 @@ This view will: Navigate to your groups's **{package}** **Packages & Registries > Container Registry**. - + This view will: @@ -237,29 +243,29 @@ For private and internal projects: ### Container Registry examples with GitLab CI/CD -If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml` +If you're using Docker-in-Docker on your Runners, this is how your `.gitlab-ci.yml` should look similar to this: ```yaml build: - image: docker:19.03.8 + image: docker:19.03.11 stage: build services: - - docker:19.03.8-dind + - docker:19.03.11-dind script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $CI_REGISTRY/group/project/image:latest . - docker push $CI_REGISTRY/group/project/image:latest ``` -You can also make use of [other variables](../../../ci/variables/README.md) to avoid hardcoding: +You can also make use of [other variables](../../../ci/variables/README.md) to avoid hard-coding: ```yaml build: - image: docker:19.03.8 + image: docker:19.03.11 stage: build services: - - docker:19.03.8-dind + - docker:19.03.11-dind variables: IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG script: @@ -282,9 +288,9 @@ when needed. Changes to `master` also get tagged as `latest` and deployed using an application-specific deploy script: ```yaml -image: docker:19.03.8 +image: docker:19.03.11 services: - - docker:19.03.8-dind + - docker:19.03.11-dind stages: - build @@ -344,11 +350,11 @@ or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) execut make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work) is set to `always`. -### Using a docker-in-docker image from your Container Registry +### 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 +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 -[docker-in-docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) section: +[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. 1. Add a service [alias](../../../ci/yaml/README.md#servicesalias). @@ -357,9 +363,9 @@ Below is an example of what your `.gitlab-ci.yml` should look like: ```yaml build: - image: $CI_REGISTRY/group/project/docker:19.03.8 + image: $CI_REGISTRY/group/project/docker:19.03.11 services: - - name: $CI_REGISTRY/group/project/docker:19.03.8-dind + - name: $CI_REGISTRY/group/project/docker:19.03.11-dind alias: docker stage: build script: @@ -367,7 +373,7 @@ 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.8` image won't find the +If you forget to set the service alias, the `docker:19.03.11` image won't find the `dind` service, and an error like the following will be thrown: ```plaintext @@ -437,10 +443,10 @@ stages: - clean build_image: - image: docker:19.03.8 + image: docker:19.03.11 stage: build services: - - docker:19.03.8-dind + - docker:19.03.11-dind variables: IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG script: @@ -453,10 +459,10 @@ build_image: - master delete_image: - image: docker:19.03.8 + image: docker:19.03.11 stage: clean services: - - docker:19.03.8-dind + - docker:19.03.11-dind variables: IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228 @@ -487,11 +493,12 @@ older tags and images are regularly removed from the Container Registry. ## Expiration policy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/15398) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. NOTE: **Note:** -Expiration policies for projects created before GitLab 12.8 may be enabled by an -admin in the [CI/CD Package Registry settings](./../../admin_area/settings/index.md#cicd). +For GitLab.com, expiration policies are not available for projects created before GitLab 12.8. +For self-managed instances, expiration policies may be enabled by an admin in the +[CI/CD Package Registry settings](./../../admin_area/settings/index.md#cicd). Note the inherent [risks involved](./index.md#use-with-external-container-registries). It is possible to create a per-project expiration policy, so that you can make sure that @@ -506,7 +513,7 @@ then goes through a process of excluding tags from it until only the ones to be 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 older than the `older_than` value (Expiration interval). +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 (Images to preserve). 1. Finally, the remaining tags in the list are deleted from the Container Registry. @@ -525,6 +532,17 @@ The UI allows you to configure the following: - **Docker tags with names matching this regex pattern will expire:** the regex used to determine what tags should be expired. To qualify all tags for expiration, 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 `.*`. +#### Troubleshooting expiration policies + +If you see the following message: + +"Something went wrong while updating the expiration 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). + ### Managing project expiration policy through the API You can set, update, and disable the expiration policies using the GitLab API. @@ -548,6 +566,36 @@ run the policy may get backed up or fail completely. It is recommended you only policies for projects that were created before GitLab 12.8 if you are confident the amount of tags being cleaned up will be minimal. +### Regex pattern examples + +Expiration policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API. + +Here are examples of regex patterns you may want to use: + +- Match all tags: + + ```plaintext + .* + ``` + +- Match tags that start with `v`: + + ```plaintext + v.+ + ``` + +- Match tags that contain `master`: + + ```plaintext + master + ``` + +- Match tags that either start with `v`, contain `master`, or contain `release`: + + ```plaintext + (?:v.+|master|release) + ``` + ## Limitations - Moving or renaming existing Container Registry repositories is not supported diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index be9710053dd..e68883a1382 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -1,6 +1,12 @@ +--- +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 +--- + # Dependency Proxy **(PREMIUM ONLY)** -> [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 Ultimate](https://about.gitlab.com/pricing/) 11.11. NOTE: **Note:** This is the user guide. In order to use the dependency proxy, an administrator diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md new file mode 100644 index 00000000000..a705b956d30 --- /dev/null +++ b/doc/user/packages/go_proxy/index.md @@ -0,0 +1,169 @@ +--- +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 +--- + +# GitLab Go Proxy **(PREMIUM)** + +> - [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)** + +With the Go proxy for GitLab, every project in GitLab can be fetched with the +[Go proxy protocol](https://proxy.golang.org/). + +## Prerequisites + +### Enable the Go proxy + +The Go proxy for GitLab is under development and not ready for production use, due to +[potential performance issues with large repositories](https://gitlab.com/gitlab-org/gitlab/-/issues/218083). + +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. + +To enable it: + +```ruby +Feature.enable(:go_proxy) # or +``` + +To disable it: + +```ruby +Feature.disable(:go_proxy) +``` + +To enable or disable it for specific projects: + +```ruby +Feature.enable(:go_proxy, Project.find(1)) +Feature.disable(:go_proxy, Project.find(2)) +``` + +### Enable the Package Registry + +The Package Registry is enabled for new projects by default. If you cannot find +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)** +1. The Package Registry is [enabled for your project](../index.md). + +NOTE: **Note:** +GitLab does not currently display Go modules in the **Packages Registry** of a project. +Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details. + +## Add GitLab as a Go proxy + +NOTE: **Note:** +To use a Go proxy, you must be using Go 1.13 or later. + +The available proxy endpoints are: + +- Project - can fetch modules defined by a project - `/api/v4/projects/:id/packages/go` + +To use the Go proxy for GitLab to fetch Go modules from GitLab, add the +appropriate proxy endpoint to `GOPROXY`. For details on setting Go environment +variables, see [Set environment variables](#set-environment-variables). For +details on configuring `GOPROXY`, see [Dependency Management in Go > +Proxies](../../../development/go_guide/dependencies.md#proxies). + +For example, adding the project-specific endpoint to `GOPROXY` will tell Go +to initially query that endpoint and fall back to the default behavior: + +```shell +go env -w GOPROXY='https://gitlab.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct' +``` + +With this configuration, Go fetches dependencies as follows: + +1. Attempt to fetch from the project-specific Go proxy. +1. Attempt to fetch from [proxy.golang.org](https://proxy.golang.org). +1. Fetch directly with version control system operations (such as `git clone`, + `svn checkout`, and so on). + +If `GOPROXY` is not specified, Go follows steps 2 and 3, which corresponds to +setting `GOPROXY` to `https://proxy.golang.org,direct`. If `GOPROXY` only +contains the project-specific endpoint, Go will only query that endpoint. + +## Fetch modules from private projects + +`go` does not support transmitting credentials over insecure connections. The +steps below work only if GitLab is configured for HTTPS. + +1. Configure Go to include HTTP basic authentication credentials when fetching + from the Go proxy for GitLab. +1. Configure Go to skip downloading of checksums for private GitLab projects + from the public checksum database. + +### Enable request authentication + +Create a [personal access token](../../profile/personal_access_tokens.md) with +the `api` or `read_api` scope and add it to +[`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc): + +```netrc +machine <url> login <username> password <token> +``` + +`<url>` should be the URL of the GitLab instance, for example `gitlab.com`. +`<username>` and `<token>` should be your username and the personal access +token, respectively. + +### Disable checksum database queries + +When downloading dependencies, by default Go 1.13 and later validate fetched +sources against the checksum database `sum.golang.org`. If the checksum of the +fetched sources does not match the checksum from the database, Go will not build +the dependency. This causes private modules to fail to build, as +`sum.golang.org` cannot fetch the source of private modules and thus cannot +provide a checksum. To resolve this issue, `GONOSUMDB` should be set to a +comma-separated list of private projects. For details on setting Go environment +variables, see [Set environment variables](#set-environment-variables). For more +details on disabling this feature of Go, see [Dependency Management in Go > +Checksums](../../../development/go_guide/dependencies.md#checksums). + +For example, to disable checksum queries for `gitlab.com/my/project`, set `GONOSUMDB`: + +```shell +go env -w GONOSUMDB='gitlab.com/my/project,<previous value>' +``` + +## Working with Go + +If you are unfamiliar with managing dependencies in Go, or Go in general, +consider reviewing the following documentation: + +- [Dependency Management in Go](../../../development/go_guide/dependencies.md) +- [Go Modules Reference](https://golang.org/ref/mod) +- [Documentation (golang.org)](https://golang.org/doc/) +- [Learn (learn.go.dev)](https://learn.go.dev/) + +### Set environment variables + +Go uses environment variables to control various features. These can be managed +in all the usual ways, but Go 1.14 will read and write Go environment variables +from and to a special Go environment file, `~/.go/env` by default. If `GOENV` is +set to a file, Go will read and write that file instead. If `GOENV` is not set +but `GOPATH` is set, Go will read and write `$GOPATH/env`. + +Go environment variables can be read with `go env <var>` and, in Go 1.14 and +later, can be written with `go env -w <var>=<value>`. For example, `go env +GOPATH` or `go env -w GOPATH=/go`. + +### Release a module + +Go modules and module versions are defined by source repositories, such as Git, +SVN, Mercurial, and so on. A module is a repository containing `go.mod` and Go +files. Module versions are defined by VCS tags. To publish a module, push +`go.mod` and source files to a VCS repository. To publish a module version, push +a VCS tag. See [Dependency Management in Go > +Versioning](../../../development/go_guide/dependencies.md#versioning) for more +details on what constitutes a valid module or module version. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 132a64d99a3..6e59a87ae36 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.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 +--- + # GitLab Package Registry GitLab Packages allows organizations to utilize GitLab as a private repository @@ -15,6 +21,8 @@ The Packages feature allows GitLab to act as a repository for the following: | [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.1+ | ## Enable the Package Registry for your project @@ -104,20 +112,19 @@ are adding support for [PHP](https://gitlab.com/gitlab-org/gitlab/-/merge_reques | Format | Use case | | ------ | ------ | -| [Cargo](https://gitlab.com/gitlab-org/gitlab/issues/33060) | Cargo is the Rust package manager. Build, publish and share Rust packages | -| [Chef](https://gitlab.com/gitlab-org/gitlab/issues/36889) | Configuration management with Chef using all the benefits of a repository manager. | -| [CocoaPods](https://gitlab.com/gitlab-org/gitlab/issues/36890) | Speed up development with Xcode and CocoaPods. | -| [Conda](https://gitlab.com/gitlab-org/gitlab/issues/36891) | Secure and private local Conda repositories. | -| [CRAN](https://gitlab.com/gitlab-org/gitlab/issues/36892) | Deploy and resolve CRAN packages for the R language. | -| [Debian](https://gitlab.com/gitlab-org/gitlab/issues/5835) | Host and provision Debian packages. | -| [Go](https://gitlab.com/gitlab-org/gitlab/issues/9773) | Resolve Go dependencies from and publish your Go packages to GitLab. | -| [Opkg](https://gitlab.com/gitlab-org/gitlab/issues/36894) | Optimize your work with OpenWrt using Opkg repositories. | -| [P2](https://gitlab.com/gitlab-org/gitlab/issues/36895) | Host all your Eclipse plugins in your own GitLab P2 repository. | -| [Puppet](https://gitlab.com/gitlab-org/gitlab/issues/36897) | Configuration management meets repository management with Puppet repositories. | -| [RPM](https://gitlab.com/gitlab-org/gitlab/issues/5932) | Distribute RPMs directly from GitLab. | -| [RubyGems](https://gitlab.com/gitlab-org/gitlab/issues/803) | Use GitLab to host your own gems. | -| [SBT](https://gitlab.com/gitlab-org/gitlab/issues/36898) | Resolve dependencies from and deploy build output to SBT repositories when running SBT builds. | -| [Vagrant](https://gitlab.com/gitlab-org/gitlab/issues/36899) | Securely host your Vagrant boxes in local repositories. | +| [Cargo](https://gitlab.com/gitlab-org/gitlab/-/issues/33060) | Cargo is the Rust package manager. Build, publish and share Rust packages | +| [Chef](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | Configuration management with Chef using all the benefits of a repository manager. | +| [CocoaPods](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | Speed up development with Xcode and CocoaPods. | +| [Conda](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | Secure and private local Conda repositories. | +| [CRAN](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | Deploy and resolve CRAN packages for the R language. | +| [Debian](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) | Host and provision Debian packages. | +| [Opkg](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | Optimize your work with OpenWrt using Opkg repositories. | +| [P2](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | Host all your Eclipse plugins in your own GitLab P2 repository. | +| [Puppet](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | Configuration management meets repository management with Puppet repositories. | +| [RPM](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | Distribute RPMs directly from GitLab. | +| [RubyGems](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | Use GitLab to host your own gems. | +| [SBT](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | Resolve dependencies from and deploy build output to SBT repositories when running SBT builds. | +| [Vagrant](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | Securely host your Vagrant boxes in local repositories. | ## Package workflows diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 51e62dc871e..2d40a623fb8 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -1,6 +1,12 @@ +--- +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 +--- + # GitLab Maven Repository **(PREMIUM)** -> [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. With the GitLab [Maven](https://maven.apache.org) Repository, every project can have its own space to store its Maven artifacts. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index b909646431b..4d60c227ccd 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -1,6 +1,12 @@ +--- +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 +--- + # GitLab NPM Registry **(PREMIUM)** -> [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. With the GitLab NPM Registry, every project can have its own space to store NPM packages. @@ -159,7 +165,7 @@ Then, you could run `npm publish` either locally or via GitLab CI/CD: ### Authenticating with a CI job token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9104) in GitLab Premium 12.5. +> [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. @@ -272,7 +278,7 @@ yarn add @my-project-scope/my-package ### Forwarding requests to npmjs.org -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. +> [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/). @@ -374,7 +380,7 @@ NPM_TOKEN=<your_token> npm install ## NPM dependencies metadata -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11867) in GitLab Premium 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. Starting from GitLab 12.6, new packages published to the GitLab NPM Registry expose the following attributes to the NPM client: @@ -390,7 +396,7 @@ Starting from GitLab 12.6, new packages published to the GitLab NPM Registry exp ## NPM distribution tags -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9425) in GitLab Premium 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) for newly published packages. They follow NPM's convention where they are optional, and each tag can only be assigned to one diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index d9efb3239a8..6ada68dcceb 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -1,6 +1,12 @@ +--- +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 +--- + # GitLab NuGet Repository **(PREMIUM)** -> [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. With the GitLab NuGet Repository, every project can have its own space to store NuGet packages. @@ -95,7 +101,7 @@ Where: For example: ```shell -nuget source Add -Name "GitLab" -Source "https//gitlab.example/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf +nuget source Add -Name "GitLab" -Source "https://gitlab.example/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf ``` ### Add NuGet Repository source with Visual Studio diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 979f7a3c966..6f6609d82b1 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.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 +--- + # GitLab PyPi Repository **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index e5893b291dc..ecae119e9f1 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -23,9 +23,6 @@ GitLab [administrators](../administration/index.md) receive all permissions. To add or import a user, you can follow the [project members documentation](project/members/index.md). -For information on eligible approvers for Merge Requests, see -[Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). - ## Principles behind permissions See our [product handbook on permissions](https://about.gitlab.com/handbook/product/#permissions-in-gitlab) @@ -50,7 +47,7 @@ The following table depicts the various user permission levels in a project. |---------------------------------------------------|---------|------------|-------------|----------|--------| | Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Leave comments | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View approved/blacklisted licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | View Dependency list **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | @@ -99,6 +96,7 @@ The following table depicts the various user permission levels in a project. | Assign merge requests | | | ✓ | ✓ | ✓ | | Label merge requests | | | ✓ | ✓ | ✓ | | Lock merge request threads | | | ✓ | ✓ | ✓ | +| Approve merge requests (*9*) | | | ✓ | ✓ | ✓ | | Manage/Accept merge requests | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | @@ -131,6 +129,7 @@ The following table depicts the various user permission levels in a project. | Enable/disable tag protections | | | | ✓ | ✓ | | Edit project | | | | ✓ | ✓ | | Edit project badges | | | | ✓ | ✓ | +| Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*)| | Add deploy keys to project | | | | ✓ | ✓ | | Configure project hooks | | | | ✓ | ✓ | | Manage Runners | | | | ✓ | ✓ | @@ -150,9 +149,12 @@ The following table depicts the various user permission levels in a project. | Manage [project access tokens](./project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | +| Rename project | | | | | ✓ | | Remove fork relationship | | | | | ✓ | | Remove project | | | | | ✓ | +| Archive project | | | | | ✓ | | Delete issues | | | | | ✓ | +| Delete merge request | | | | | ✓ | | Disable notification emails | | | | | ✓ | | Force push to protected branches (*4*) | | | | | | | Remove protected branches (*4*) | | | | | | @@ -172,6 +174,9 @@ The following table depicts the various user permission levels in a project. 1. If the [branch is protected](./project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. 1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits. 1. Actions are limited only to records owned (referenced) by user. +1. When [Share Group Lock](./group/index.md#share-with-group-lock) is enabled the project can't be shared with other groups. It does not affect group with group sharing. +1. For information on eligible approvers for merge requests, see + [Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). ## Project features permissions @@ -239,6 +244,7 @@ group. | Publish [packages](packages/index.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | Create project in group | | | ✓ (3) | ✓ (3) | ✓ (3) | +| Share (invite) groups with groups | | | | | ✓ | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | | Enable/disable a dependency proxy **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | @@ -246,11 +252,12 @@ group. | View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | | Create subgroup | | | | ✓ (1) | ✓ | | Edit epic comments (posted by any user) **(ULTIMATE)** | | | | ✓ (2) | ✓ (2) | -| Edit group | | | | | ✓ | +| Edit group settings | | | | | ✓ | | Manage group level CI/CD variables | | | | | ✓ | | Manage group members | | | | | ✓ | -| Remove group | | | | | ✓ | +| Delete group | | | | | ✓ | | Delete group epic **(ULTIMATE)** | | | | | ✓ | +| Edit SAML SSO Billing **(SILVER ONLY)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | | View group Audit Events | | | | | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -258,6 +265,8 @@ group. | View Issues analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Billing **(FREE ONLY)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | +| View Usage Quotas **(FREE ONLY)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | 1. Groups can be set to [allow either Owners or Owners and Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) @@ -265,6 +274,7 @@ group. 1. Default project creation role can be changed at: - The [instance level](admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection). - The [group level](group/index.md#default-project-creation-level). +1. Does not apply to subgroups. ### Subgroup permissions @@ -285,7 +295,7 @@ project and should only have access to that project. External users: - Cannot create groups, projects, or personal snippets. -- Can only access projects to which they are explicitly granted access, +- Can only access public projects and projects to which they are explicitly granted access, thus hiding all other internal or private ones from them (like being logged out). @@ -455,7 +465,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](../administration/auth/how_to_configure_ldap_gitlab_ee/index.md) to learn more. +Read through the documentation on [LDAP users permissions](group/index.md#manage-group-memberships-via-ldap) to learn more. ## Project aliases diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 27aa57e7f99..26c2c1bed89 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -1,5 +1,8 @@ --- type: reference +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Creating users **(CORE ONLY)** @@ -32,5 +35,5 @@ You can also [create users through the API](../../../api/users.md) as an admin. Users will be: -- Automatically created upon first login with the [LDAP integration](../../../administration/auth/ldap.md). +- Automatically created upon first login with the [LDAP integration](../../../administration/auth/ldap/index.md). - Created when first logging in via an [OmniAuth provider](../../../integration/omniauth.md) if the `allow_single_sign_on` setting is present. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index c9193c6d94c..3c6f2989091 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,5 +1,8 @@ --- type: howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Deleting a User account diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index ac0835911d2..bfcaeaf6a15 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,5 +1,8 @@ --- type: howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Two-Factor Authentication @@ -65,19 +68,22 @@ in a safe place. ### Enable 2FA via U2F device +> Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/). + GitLab officially only supports [YubiKey](https://www.yubico.com/products/) -U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/). +U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/) +or [Google Titan Security Key](https://cloud.google.com/titan-security-key). The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers: - Chrome - Edge -- Firefox (disabled by default) +- Firefox 67+ - Opera NOTE: **Note:** -For Firefox, you can enable the FIDO U2F API in +For Firefox 47-66, you can enable the FIDO U2F API in [about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). Search for `security.webauth.u2f` and double click on it to toggle to `true`. diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 408276127a2..4dbb11b581d 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -19,7 +19,7 @@ review the sessions, and revoke any you don't recognize. ## Active sessions limit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31611) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31611) in GitLab 12.6. GitLab allows users to have up to 100 active sessions at once. If the number of active sessions exceeds 100, the oldest ones are deleted. diff --git a/doc/user/profile/img/unknown_sign_in_email_v13_1.png b/doc/user/profile/img/unknown_sign_in_email_v13_1.png Binary files differnew file mode 100644 index 00000000000..586be483be9 --- /dev/null +++ b/doc/user/profile/img/unknown_sign_in_email_v13_1.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 383c7fe73aa..663a2888ee7 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,5 +1,8 @@ --- type: index, howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # User account @@ -147,7 +150,7 @@ To add links to other accounts: ## Private contributions -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14078) in GitLab 11.3. +> [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. @@ -250,7 +253,27 @@ 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 (which is for security reasons). +you will be asked to sign in again to verify your identity for security reasons. + +### Increased sign-in time + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20340) in GitLab 13.1. + +The `remember_user_token` lifetime of a cookie can now extend beyond the deadline set by `config.remember_for`, as the `config.extend_remember_period` flag is now set to true. + +GitLab uses both session and persistent cookies: + +- Session cookie: Session cookies are normally removed at the end of the browser session when the browser is closed. The `_gitlab_session` cookie has no expiration date. +- Persistent cookie: The `remember_me_token` is a cookie with an expiration date of two weeks. GitLab activates this cookie if you click Remember Me when you sign in. + +By default, the server sets a time-to-live (TTL) of 1-week on any session that is used. + +When you close a browser, the session cookie may still remain. For example, Chrome has the "Continue where you left off" option that restores session cookies. +In other words, as long as you access GitLab at least once every 2 weeks, you could remain signed in with GitLab, as long as your browser tab is open. +The server continues to reset the TTL for that session, independent of whether 2FA is installed, +If you close your browser and open it up again, the `remember_user_token` cookie allows your user to reauthenticate itself. + +Without the `config.extend_remember_period` flag, you would be forced to sign in again after two weeks. <!-- ## Troubleshooting diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index ae00f3ace57..ee228050945 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -1,5 +1,8 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/workflow/notifications.html' +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # GitLab Notification Emails @@ -163,7 +166,7 @@ In most of the below cases, the notification will be sent to: - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below NOTE: **Note:** -To minimize the number of notifications that do not require any action, from [GitLab 12.9 onwards](https://gitlab.com/gitlab-org/gitlab/issues/616), eligible approvers are no longer notified for all the activities in their projects. To receive them they have to change their user notification settings to **Watch** instead. +To minimize the number of notifications that do not require any action, from [GitLab 12.9 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible approvers are no longer notified for all the activities in their projects. To receive them they have to change their user notification settings to **Watch** instead. | Event | Sent to | |------------------------|---------| @@ -237,4 +240,4 @@ reason `assigned` will have this sentence in the footer: - `You are receiving this email because you have been assigned an item on <configured GitLab hostname>.` NOTE: **Note:** -Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/issues/20689). +Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/20689). diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 87c1fe4007a..e2c3dc74cf1 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -1,5 +1,8 @@ --- type: concepts, howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Personal access tokens @@ -56,6 +59,58 @@ the following table. | `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 +[Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session) +for your GitLab instance. + +To create a token belonging to a user with username `automation-bot`, run the +following in the Rails console (`sudo gitlab-rails console`): + +```ruby +user = User.find_by_username('automation-bot') +token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token') +token.set_token('token-string-here123') +token.save! +``` + +This can be shortened into a single-line shell command using the +[GitLab Rails Runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): + +```shell +sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" +``` + +NOTE: **Note:** +The token string must be 20 characters in length, or it will not be +recognized as a 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 +sufficient access to run a [Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session) +for your GitLab instance. + +To revoke a known token `token-string-here123`, run the following in the Rails +console (`sudo gitlab-rails console`): + +```ruby +token = PersonalAccessToken.find_by_token('token-string-here123') +token.revoke! +``` + +This can be shorted into a single-line shell command using the +[GitLab Rails Runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): + +```shell +sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!" +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 55781b48a27..ccaea61ae4b 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -36,6 +36,29 @@ The default theme is Indigo. You can choose between 10 themes:  +## Dark mode + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an Alpha release. + +GitLab has started work on dark mode! The dark mode Alpha release is available in the +spirit of iteration and the lower expectations of +[Alpha versions](https://about.gitlab.com/handbook/product/#alpha). + +Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). See the epic for: + +- A list of known issues. +- Our planned direction and next steps. + +If you find an issue that isn’t listed, please leave a comment on the epic or create a +new issue. + +Dark mode is available as a navigation theme, for MVC and compatibility reasons. In +the future, we plan to make it configurable in its own section along with support for +[different navigation themes](https://gitlab.com/gitlab-org/gitlab/-/issues/219512). + +NOTE: **Note:** +Dark theme currently only works with the 'Dark' syntax highlighting. + ## Syntax highlighting theme NOTE: **Note:** diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index 9400ead1922..200358bb050 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -1,5 +1,14 @@ +--- +type: concepts, howto +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Email notification for unknown sign-ins +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27211) in GitLab 13.0. + When a user successfully signs in from a previously unknown IP address, GitLab notifies the user by email. In this way, GitLab proactively alerts users of potentially malicious or unauthorized sign-ins. @@ -13,4 +22,4 @@ There are two methods used to identify a known sign-in: ## Example email - + diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 6994f16cf52..542a3763008 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,6 +1,6 @@ # Badges -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41174) in GitLab 10.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. Badges are a unified way to present condensed pieces of information about your projects. They consist of a small image and additionally a URL that the image diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index f4733620640..6d091c431a2 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,32 +1,60 @@ -# Bulk editing issues and merge requests +--- +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 +--- -> **Notes:** -> -> - A permission level of `Reporter` or higher is required in order to manage -> issues. -> - A permission level of `Developer` or higher is required in order to manage -> merge requests. +# Bulk editing issues and merge requests at the project level -Attributes can be updated simultaneously across multiple issues or merge requests -by using the bulk editing feature. +NOTE: **Note:** +Bulk editing issues, epics, and merge requests is also available at the **group level**. +For more details, see +[Bulk editing issues, epics, and merge requests at the group level](../group/bulk_editing/index.md). + +If you want to update attributes across multiple issues or merge requests, you can do it +by bulk editing them, that is, editing them together.  +## Bulk edit issues at the project level + NOTE: **Note:** -Bulk editing issues and merge requests is also available at the group level. -For more details, see [bulk editing group issues and merge requests](../group/bulk_editing/index.md). +You need a permission level of [Reporter or higher](../permissions.md) to manage issues. + +When bulk editing issues in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions -To update multiple project issues or merge requests at the same time: +To update multiple project issues at the same time: -1. Navigate to their respective list. +1. In a project, go to **{issues}** **Issues > List**. +1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Select the checkboxes next to each issue you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the project level + +NOTE: **Note:** +You need a permission level of [Developer or higher](../permissions.md) to manage merge requests. -1. Click **Edit issues** or **Edit merge requests**. +When bulk editing merge requests in a project, you can edit the following attributes: - - This will open a sidebar on the right-hand side of your screen - where editable fields will be displayed. +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions - - Checkboxes will also appear beside each issue or merge request. +To update multiple project merge requests at the same time: -1. Check the checkboxes of each items to be edited. -1. Choose the appropriate fields and their values from the sidebar. +1. In a project, go to **{merge-request}** **Merge Requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. 1. Click **Update all**. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 86e9df1d162..852baf1f628 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,6 +1,6 @@ # Canary Deployments **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 712f8ea0adc..b11483a7446 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -51,7 +51,7 @@ Generate an access key for the IAM user, and configure GitLab with the credentia ## New EKS cluster -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. To create and add a new Kubernetes cluster to your project, group, or instance: @@ -147,7 +147,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) - in your VPC where your worker nodes will run. + in your VPC where your worker nodes will run. You must select at least two. - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. @@ -164,114 +164,45 @@ You will need to add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. +### Troubleshooting creating a new cluster + +The following errors are commonly encountered when creating a new cluster. + +#### Error: Request failed with status code 422 + +When submitting the initial authentication form, GitLab returns a status code 422 +error when it can't determine the role you've provided. Make sure you've +correctly configured your role with the **Account ID** and **External ID** +provided by GitLab. In GitLab, make sure to enter the correct **Role ARN**. + +#### Could not load Security Groups for this VPC + +When populating options in the configuration form, GitLab returns this error +because GitLab has successfully assumed your provided role, but the role has +insufficient permissions to retrieve the resources needed for the form. Make sure +you've assigned the role the correct permissions. + +#### `ROLLBACK_FAILED` during cluster creation + +The creation process halted because GitLab encountered an error when creating +one or more resources. You can inspect the associated +[CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-view-stack-data-resources.html) +to find the specific resources that failed to create. + +If the `Cluster` resource failed with the error +`The provided role doesn't have the Amazon EKS Managed Policies associated with it.`, +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. + ## Existing EKS cluster -To add an existing EKS cluster to your project, group, or instance: - -1. Perform the following steps on the EKS cluster: - 1. Retrieve the certificate. A valid Kubernetes certificate is needed to authenticate to the - EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: - - 1. List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - 1. Get the certificate with: - - ```shell - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - 1. Create admin token. A `cluster-admin` token is required to install and manage Helm Tiller. - GitLab establishes mutual SSL authentication with Helm Tiller and creates limited service - accounts for each application. To create the token we will create an admin service account as - follows: - - 1. Create a file called `eks-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the service account to your cluster: - - ```shell - $ kubectl apply -f eks-admin-service-account.yaml - serviceaccount "eks-admin" created - ``` - - 1. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the cluster role binding to your cluster: - - ```shell - $ kubectl apply -f eks-admin-cluster-role-binding.yaml - clusterrolebinding "eks-admin" created - ``` - - 1. Retrieve the token for the `eks-admin` service account: - - ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - 1. Locate the API server endpoint so GitLab can connect to the cluster. This is displayed on - the AWS EKS console, when viewing the EKS cluster details. -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. -1. Click **Add Kubernetes cluster**. -1. Click the **Add existing cluster** tab and fill in the details: - - **Kubernetes cluster name**: A name for the cluster to identify it within GitLab. - - **Environment scope**: Leave this as `*` for now, since we are only connecting a single cluster. - - **API URL**: The API server endpoint retrieved earlier. - - **CA Certificate**: The certificate data from the earlier step, as-is. - - **Service Token**: The admin token value. - - For project-level clusters, **Project namespace prefix**: This can be left blank to accept the - default namespace, based on the project name. -1. Click on **Add Kubernetes cluster**. The cluster is now connected to GitLab. - -At this point, [Kubernetes deployment variables](index.md#deployment-variables) will -automatically be available during CI/CD jobs, making it easy to interact with the cluster. - -If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. +For information on adding an existing EKS cluster, see +[Existing Kubernetes cluster](add_remove_clusters.md#existing-kubernetes-cluster). ### Create a default Storage Class diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 4094828323a..2746076befe 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -21,26 +21,25 @@ requirements are met: ## New GKE cluster -Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters +Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/25925), all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). -### Important notes - Note the following: - The [Google authentication integration](../../../integration/google.md) must be enabled in GitLab at the instance level. If that's not the case, ask your GitLab administrator to enable it. On GitLab.com, this is enabled. -- Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters +- Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55902), all GKE clusters created by GitLab are RBAC-enabled. Take a look at the [RBAC section](add_remove_clusters.md#rbac-cluster-resources) for more information. - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to - set up an [initial service account](add_remove_clusters.md#access-controls). Starting from [GitLab - 11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will - explicitly request that basic authentication and client certificate is enabled. + set up an [initial service account](add_remove_clusters.md#access-controls). In [GitLab versions + 11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58208), the cluster creation process + explicitly requests GKE to create clusters with basic authentication enabled and a client + certificate. ### Creating the cluster on GKE diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index fddc9873f17..d0cba729e35 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -50,7 +50,7 @@ a `gitlab` service account with `cluster-admin` privileges is created in the `de to manage the newly created cluster. NOTE: **Note:** -Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/51716) in GitLab 11.5. +Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. When you install Helm into your cluster, the `tiller` service account is created with `cluster-admin` privileges in the `gitlab-managed-apps` @@ -151,146 +151,142 @@ For more information, see information for adding an: NOTE: **Note:** Kubernetes integration is not supported for arm64 clusters. See the issue -[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. +[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64044) for details. ### Existing Kubernetes cluster To add a 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. + 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. Click **Add Kubernetes cluster**. 1. Click the **Add existing cluster** tab and fill in the details: - - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - - **Environment scope** (required) - The - [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. - - **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. - For example, `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. - - Get the API URL by running this command: - - ```shell - kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' - ``` - - - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should be named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate by running this command: - - ```shell - - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - - ``` - - NOTE: **Note:** - If the command returns the entire certificate chain, you need copy the *root ca* - certificate at the bottom of the chain. - - - **Token** - - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. - **The token used should belong to a service account with - [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - privileges.** To create this service account: - - 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` - - 1. Apply the service account and cluster role binding to your cluster: - - ```shell - kubectl apply -f gitlab-admin-service-account.yaml - ``` - - You will need the `container.clusterRoleBindings.create` permission - to create cluster-level roles. If you do not have this permission, - you can alternatively enable Basic Authentication and then run the - `kubectl apply` command as an admin: - - ```shell - kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> - ``` - - NOTE: **Note:** - Basic Authentication can be turned on and the password credentials - can be obtained using the Google Cloud Console. - - Output: - - ```shell - serviceaccount "gitlab-admin" created - clusterrolebinding "gitlab-admin" created - ``` - - 1. Retrieve the token for the `gitlab-admin` service account: - - ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: gitlab-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin + 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. + 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. + For example, `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + + Get the API URL by running this command: + + ```shell + kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + ``` + + 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. + 1. List the secrets with `kubectl get secrets`, and one should be named similar to + `default-token-xxxxx`. Copy that token name for use below. + 1. Get the certificate by running this command: + + ```shell + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` + + NOTE: **Note:** + If the command returns the entire certificate chain, you need copy the *root ca* + certificate at the bottom of the chain. + + 1. **Token** - + GitLab authenticates against Kubernetes using service tokens, which are + scoped to a particular `namespace`. + **The token used should belong to a service account with + [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges.** To create this service account: + 1. Create a file called `gitlab-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: + + ```shell + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + You will need the `container.clusterRoleBindings.create` permission + to create cluster-level roles. If you do not have this permission, + you can alternatively enable Basic Authentication and then run the + `kubectl apply` command as an admin: + + ```shell + kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> + ``` + + NOTE: **Note:** + Basic Authentication can be turned on and the password credentials + can be obtained using the Google Cloud Console. + + Output: + + ```shell + serviceaccount "gitlab-admin" created + clusterrolebinding "gitlab-admin" created + ``` + + 1. Retrieve the token for the `gitlab-admin` service account: + + ```shell + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - NOTE: **Note:** - For GKE clusters, you will need the - `container.clusterRoleBindings.create` permission to create a cluster - role binding. You can follow the [Google Cloud - documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) - to grant access. - - - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. - See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. - - - **Project namespace** (optional) - You don't have to fill it in; by leaving - it blank, GitLab will create one for you. Also: - - Each project should have a unique namespace. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + + NOTE: **Note:** + For GKE clusters, you will need the + `container.clusterRoleBindings.create` permission to create a cluster + role binding. You can follow the [Google Cloud + documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) + to grant access. + + 1. **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. + See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. + 1. **Project namespace** (optional) - You don't have to fill it in; by leaving + it blank, GitLab will create one for you. Also: + - Each project should have a unique namespace. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. 1. Finally, click the **Create Kubernetes cluster** button. @@ -337,7 +333,7 @@ To disable the Kubernetes cluster integration, follow the same procedure. To remove the Kubernetes cluster integration from your project, either: - Select **Remove integration**, to remove only the Kubernetes integration. -- [From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/26815), select +- [From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/26815), select **Remove integration and resources**, to also remove all related GitLab cluster resources (for example, namespaces, roles, and bindings) when removing the integration. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 1298a24fcac..961a9fda5ff 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes clusters -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/35954) in GitLab 10.1 for projects. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/34758) in +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1 for projects. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in > GitLab 11.6 for [groups](../../group/clusters/index.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/39840) in +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in > GitLab 11.11 for [instances](../../instance/clusters/index.md). GitLab provides many features with a Kubernetes integration. Kubernetes can be @@ -46,6 +46,7 @@ GitLab is committed to support at least two production-ready Kubernetes minor ve Currently, GitLab supports the following Kubernetes versions: +- 1.16 - 1.15 - 1.14 - 1.13 (deprecated, support ends on November 22, 2020) @@ -171,7 +172,7 @@ Note the following with GitLab and clusters: #### Clearing the cluster cache -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31759) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. If you choose to allow GitLab to manage your cluster for you, GitLab stores a cached version of the namespaces and service accounts it creates for your projects. If you @@ -314,7 +315,7 @@ If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be ### Custom namespace -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27630) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. The Kubernetes integration defaults to project-environment-specific namespaces of the form `<project_name>-<project_id>-<environment>` (see [Deployment @@ -326,7 +327,7 @@ in `.gitlab-ci.yml`. NOTE: **Note:** When using a [GitLab-managed cluster](#gitlab-managed-clusters), the namespaces are created automatically prior to deployment and [can not be -customized](https://gitlab.com/gitlab-org/gitlab/issues/38054). +customized](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). ### Troubleshooting diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 8577231b69b..509be4ed0a8 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes Logs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. +> - [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). @@ -65,23 +65,23 @@ Logs can be displayed by clicking on a specific pod from [Deploy Boards](../depl The **Log Explorer** lets you filter the logs by: - Pods. -- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/5769), environments. +- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/5769), environments. - [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 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/197879), dates. Loading more than 500 log lines is possible from [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198050) onward. Support for pods with multiple containers is coming -[in a future release](https://gitlab.com/gitlab-org/gitlab/issues/13404). +[in a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/13404). Support for historical data is coming -[in a future release](https://gitlab.com/gitlab-org/gitlab/issues/196191). +[in a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/196191). ### Filter by date -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197879) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197879) in GitLab 12.8. When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, you can filter logs displayed in the **Log Explorer** by date. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index dfed43470bc..92ef35ad93f 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -23,7 +23,7 @@ pre-written code blocks or database queries against a given environment. ## Executable Runbooks -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/45912) in GitLab 11.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45912) in GitLab 11.4. The JupyterHub app offered via GitLab’s Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 124a0d4bf9f..15f7e14fda9 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -15,7 +15,7 @@ GitLab supports deployment of AWS Lambda functions through GitLab CI/CD using th ## Serverless Framework -The [Serverless Framework can deploy to AWS](https://serverless.com/framework/docs/providers/aws/). +The [Serverless Framework can deploy to AWS](https://www.serverless.com/framework/docs/providers/aws/). We have prepared an example with a step-by-step guide to create a simple function and deploy it on AWS. @@ -101,7 +101,7 @@ The handler definition will provision the Lambda function using the source code The `events` declaration will create a AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. -You can read more about the available properties and additional configuration possibilities of the Serverless Framework here: <https://serverless.com/framework/docs/providers/aws/guide/serverless.yml/> +You can read more about the [available properties and additional configuration possibilities](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/) of the Serverless Framework. #### Crafting the `.gitlab-ci.yml` file @@ -134,7 +134,7 @@ This example code does the following: #### Setting up your AWS credentials with your GitLab account In order to interact with your AWS account, the GitLab CI/CD pipelines require both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be defined in your GitLab settings under **Settings > CI/CD > Variables**. -For more information please see: <https://docs.gitlab.com/ee/ci/variables/README.html#via-the-ui> +For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). NOTE: **Note:** The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. @@ -275,7 +275,7 @@ module.exports.hello = async event => { }; ``` -For more information, see the [Your CORS and API Gateway survival guide](https://serverless.com/blog/cors-api-gateway-survival-guide/) +For more information, see the [Your CORS and API Gateway survival guide](https://www.serverless.com/blog/cors-api-gateway-survival-guide/) blog post written by the Serverless Framework team. #### Writing automated tests @@ -288,7 +288,7 @@ automated testing of both local and deployed serverless function. The example code is available: -- As a [cloneable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). +- As a [clonable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). - In a version with [tests and secret variables](https://gitlab.com/gitlab-org/project-templates/serverless-framework/). You can also use a [template](../../../../gitlab-basics/create-project.md#project-templates) @@ -416,7 +416,7 @@ production: environment: production ``` -Let’s examine the config file more closely: +Let’s examine the configuration file more closely: - `image` specifies the Docker image to use for this build. This is the latest Python image since the sample application is written in Python. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 2156d96f92a..45fb313d177 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -33,7 +33,7 @@ of the box through its main components: - [Serving](https://github.com/knative/serving): Request-driven compute that can scale to zero. - [Eventing](https://github.com/knative/eventing): Management and delivery of events. -For more information on Knative, visit the [Knative docs repo](https://github.com/knative/docs). +For more information on Knative, visit the [Knative docs repository](https://github.com/knative/docs). With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. @@ -61,14 +61,14 @@ To run Knative on GitLab, you will need: wildcard domain where your applications will be served. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) - to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) + to build the application. We also use [GitLab Knative tool](https://gitlab.com/gitlab-org/gitlabktl) CLI to simplify the deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file will contain the information for all the functions being hosted in the repository as well as a reference to the runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications)): Knative requires a `Dockerfile` in order to build your applications. It should be included at the root of your - project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions + project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. See [Installing Applications](../index.md#installing-applications) for more information. @@ -97,9 +97,9 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. 1. The Ingress is now available at this address and will route incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` - pointing the ip address or hostname of the Ingress. + pointing the IP address or hostname of the Ingress. -  +  NOTE: **Note:** You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) @@ -107,7 +107,7 @@ on a given project but not both. The current implementation makes use of a `serv ## Using an existing installation of Knative -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/58941) in GitLab 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. NOTE: **Note:** The "invocations" monitoring feature of GitLab serverless will not work when @@ -199,7 +199,7 @@ You must provide a `Dockerfile` to run serverless functions if no runtime is spe ### OpenFaaS runtimes -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29253) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29253) in GitLab 12.5. [OpenFaaS classic runtimes](https://github.com/openfaas/templates#templates-in-store) can be used with GitLab serverless. @@ -318,7 +318,7 @@ Explanation of the fields used above: |-----------|-------------| | `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh middleware. | | `envs` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are the variable contents. You may replace this with your own variables. | -| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for **all** functions in the file. The secrets are expected in ini format. | +| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for **all** functions in the file. The secrets are expected in INI format. | ### `functions` @@ -332,7 +332,7 @@ subsequent lines contain the function attributes. | `runtime` (optional)| The runtime to be used to execute the function. This can be a runtime alias (see [Runtime aliases](#runtime-aliases)), or it can be a full URL to a custom runtime repository. When the runtime is not specified, we assume that `Dockerfile` is present in the function directory specified by `source`. | | `description` | A short description of the function. | | `envs` | Sets an environment variable for the specific function only. | -| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for the specific function only. The secrets are expected in ini format. | +| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for the specific function only. The secrets are expected in INI format. | ### Deployment @@ -384,7 +384,7 @@ The sample function can now be triggered from any HTTP client using a simple `PO http://functions-echo.functions-1.functions.example.com/ ``` - 1. Using a web-based tool (ie. postman, restlet, etc) + 1. Using a web-based tool (such as Postman or Restlet)  @@ -516,7 +516,7 @@ cluster. ## Configuring logging -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33330) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33330) in GitLab 12.5. ### Prerequisites diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 40ea1833fa3..6b81aea4b87 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -6,8 +6,8 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/issues/53182) added in GitLab Starter 12.1. -> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. +> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) added in GitLab Starter 12.1. +> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. ## Introduction @@ -73,12 +73,28 @@ be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)** +NOTE: **Note**: +Developer or higher [permissions](../permissions.md) are required in order to +approve a merge request. + Once set, Code Owners are displayed in merge requests widgets:  -NOTE: **Note**: - While the`CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules) it can also be used as the sole driver of a Merge Request approval (without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)) by simply creating the file in one of the three locations specified above, configuring the Code Owners to be required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium) and then using [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) to specify the actual owners and granular permissions. +While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules) +it can also be used as the sole driver of merge request approvals +(without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)). +To do so, create the file in one of the three locations specified above and +set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). +Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) +to specify the actual owners and granular permissions. + +Using Code Owners in conjunction with [Protected Branches Approvals](protected_branches.md#protected-branches-approval-by-code-owners-premium) +will prevent any user who is not specified in the `CODEOWNERS` file from pushing changes +for the specified files/paths, even if their role is included in the **Allowed to push** column. +This allows for a more inclusive push strategy, as administrators don't have to restrict developers +from pushing directly to the protected branch, but can restrict pushing to certain +files where a review by Code Owners is required. ## The syntax of Code Owners files @@ -93,7 +109,7 @@ groups or subgroups from the project's group hierarchy as potential code owners. For example, consider the following hierarchy for a given project: -```text +```plaintext group >> sub-group >> sub-subgroup >> myproject >> file.md ``` @@ -103,7 +119,7 @@ Any of the following groups would be eligible to be specified as code owners: - `@group/sub-group` - `@group/sub-group/sub-subgroup` -In addition, any groups that have been invited to the project using the **Settings > Members** tool will also be recognized as eligible code owners. +In addition, any groups that have been invited to the project using the **Members** tool will also be recognized as eligible code owners. The order in which the paths are defined is significant: the last pattern that matches a given path will be used to find the code diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 8f7bb844e37..0a613ff918b 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,6 +1,13 @@ +--- +stage: Release +group: Progressive Delivery +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, reference +--- + # Deploy Boards **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. GitLab's Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -34,6 +41,10 @@ knowledge. In particular, you should be familiar with: - [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) +NOTE: **Note:** +Apps that consist of multiple deployments are shown as duplicates on the deploy board. +Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) for details. + ## Use cases Since the Deploy Board is a visual representation of the Kubernetes pods for a @@ -68,7 +79,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) - and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/issues/4584). + and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). 1. [Configure GitLab Runner](../../ci/runners/README.md) with the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 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 differnew file mode 100644 index 00000000000..462141ef82a --- /dev/null +++ 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 differnew file mode 100644 index 00000000000..3e6d1605f95 --- /dev/null +++ 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 new file mode 100644 index 00000000000..32d3eab5e62 --- /dev/null +++ b/doc/user/project/deploy_keys/index.md @@ -0,0 +1,164 @@ +--- +stage: Release +group: Progressive Delivery +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, reference +--- + +# Deploy Keys + +Deploy keys allow read-only or read-write (if enabled) access to one or +more repositories, by importing an SSH public key to your GitLab instance. + +This is useful for cloning repositories to your Continuous +Integration (CI) server. By using deploy keys, you don't have to set up a +dummy user account. + +There are two types of deploy keys: + +- [Project deploy keys](#project-deploy-keys) +- [Public deploy keys](#public-deploy-keys) + +## Key details on deploy keys + +Deploy Keys allow a remote machine (VM, physical, and so on) to access a GitLab +repository with just a few steps. If you want a remote machine to interact with a GitLab +repository in automation, it's a simple solution. + +A drawback is that your repository could become vulnerable if a remote machine is compromised +by a hacker. You should limit access to the remote machine before a deploy key is +enabled on your repository. A good rule to follow is to access only to trusted users, +and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md) +in the GitLab project. + +If this security implication is a concern for your organization, +[Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more +security control. + +## Deploy Keys Permissions + +You can choose the access level of a deploy key when you enable it on a project: + +- `read-only`: The deploy key can read a repository. +- `read-write`: The deploy key can read a repository and write to it. + +Project maintainers and owners can activate and deactivate deploy keys. +They can also add their own deploy keys and enable them for this project. + +When a `write-access` deploy key is used to push a commit, GitLab checks if +the **creator** of the deploy key has permission to access the resource. For example: + +- When a deploy key is used to push a commit to a [protected branch](../protected_branches.md), + the **creator** of the deploy key must have access to the branch. +- When a deploy key is used to push a commit that triggers a CI/CD pipelines, the **creator** of + the deploy key must have access to the CI/CD resources (like protected environments, secret variables, and so on). +- If the **creator** of a deploy key does not have permissions to read a project's + repository, the deploy key _might_ encounter an error during the process. + +## Differences between deploy keys and deploy tokens + +Both deploy keys and [deploy tokens](../deploy_tokens/index.md#deploy-tokens) can +help you access a repository, but there are some notables differences between them: + +- Deploy keys are shareable between projects that are not related or don't even + belong to the same group. Deploy tokens belong to either a project or + [a group](../deploy_tokens/index.md#group-deploy-token). +- A deploy key is an SSH key you need to generate yourself on your machine. A deploy + token is generated by your GitLab instance, and is provided to users only once + (at creation time). +- A deploy key is valid as long as it's registered and enabled. Deploy tokens can + be time-sensitive, as you can control their validity by setting an expiration date to them. +- You can't log in to a registry with deploy keys, or perform read / write operations + on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). +- You need an SSH key pair to use deploy keys, but not deploy tokens. + +## How to enable Deploy Keys + +### Project deploy keys + +[Project maintainers and owners](../../permissions.md#project-members-permissions) +can add or enable a deploy key for a project repository: + +1. Navigate to the project's **Settings > Repository** page. +1. Expand the **Deploy Keys** section. +1. Specify a title for the new deploy key and paste your public SSH key. +1. (Optional) Check **Write access allowed** to allow `read-write` access. Leave it unchecked for `read-only` access. + +There are three lists of Project Deploy Keys: + +- Enabled deploy keys +- Privately accessible deploy keys +- Public accessible deploy keys + + + +After you add a key, it will be enabled for this project by default, and it'll appear +in the **Enabled deploy keys** tab. + +In the **Privately accessible deploy keys** tab, you can enable a private key which +has been already imported in a different project. If you have access to these keys, +it's because you have either: + +- Previously uploaded the keys yourself in a different project. +- You are a maintainer or owner of the other project where the keys were imported. + +In the **Publicly accessible deploy keys** tab, you can enable +keys that were [made available to your entire GitLab instance](#public-deploy-keys). + +After a key is added, you can edit it to update its title, or switch between `read-only` +and `read-write` access. + +NOTE: **Note:** +If you have enabled a privately or publicly accessible or deploy key for your +project, and if you then update the access level for this key from `read-only` to +`read-write`, the change will be only for the **current project**. + +### Public deploy keys + +Public deploy keys allow `read-only` or `read-write` +access to any repository in your GitLab instance. This is useful for integrating +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. Click on **New deploy key**. + + Make sure your new key has a meaningful title, as it is the primary way for project + maintainers and owners to identify the correct public deploy key to add. For example, + if the key gives access to a SaaS CI/CD instance, use the name of that service + in the key name if that is all the key is used for. + + + +After adding a key, it will be available to any shared systems. Project maintainers +or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. + +NOTE: **Note:** +The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears +if there is at least one Public deploy key configured. + +Public deploy keys can provide greater security compared to project deploy keys, as +the administrator of the target integrated system is the only one who needs to know the key value, +or configure it. + +When creating a Public deploy key, determine whether or not it can be defined for +very narrow usage, such as just a specific service, or if it needs to be defined for +broader usage, such as full `read-write` access for all services. + +CAUTION: **Warning:** +Adding a public deploy key does not immediately expose any repository to it. Public +deploy keys enable access from other systems, but access is not given to any project +until a project maintainer chooses to make use of it. + +## Troubleshooting + +### Deploy Key cannot push to a protected branch + +If the owner of this deploy key does not have access to a [protected +branch](../protected_branches.md), then this deploy key won't have access to +the branch either. In addition to this, choosing the **No one** value in +[the "Allowed to push" section](../protected_branches.md#configuring-protected-branches) +means that no users **and** no services using deploy keys can push to that selected branch. + +Refer to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) for more information. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 2d42debed68..10f0281d0eb 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,14 @@ +--- +stage: Release +group: Progressive Delivery +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 +--- + # Deploy Tokens > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/199370) from **Settings > Repository** in GitLab 12.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9. > - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. > - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) from **Settings > CI / CD** in GitLab 13.0. @@ -120,7 +127,7 @@ To upload packages in the GitLab package registry, you'll need to: ### Group Deploy Token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/21765) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21765) in GitLab 12.9. A deploy token created at the group level can be used across all projects that belong either to the specific group or to one of its subgroups. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 16ac53a2b52..0f90c321a14 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Description templates >[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11. @@ -29,7 +35,7 @@ templates of the default branch will be taken into account. For example, if you have a project for tracking new blog posts, you can require the title, outlines, author name, author social media information, and so on. - Following the previous example, you can make a template for every MR submitted - with a new blog post, requiring information about the post date, frontmatter data, + with a new blog post, requiring information about the post date, front matter data, images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. 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 differnew file mode 100644 index 00000000000..f3d1005447c --- /dev/null +++ b/doc/user/project/img/status_page_detail_link_v13_1.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 56717858b53..56266718d12 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Import your project from Bitbucket Cloud to GitLab NOTE: **Note:** diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 55df2d7294d..f0e730564d8 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Import your project from Bitbucket Server to GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 89a9f7da852..173ba71b167 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Migrating from ClearCase [ClearCase](https://www.ibm.com/us-en/marketplace/rational-clearcase) is a set of diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 3b2404912f7..d2e79458526 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Migrating from CVS [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 13409c93929..149b5d1913c 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Import your project from FogBugz to GitLab It only takes a few simple steps to import your project from FogBugz. diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index cf9ac15f5ac..0d6e059f1cf 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Gemnasium **(ULTIMATE)** This guide describes how to migrate from Gemnasium.com to your own GitLab diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 94ab9d9195b..543fffd33d6 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Import your project from Gitea to GitLab Import your projects from Gitea to GitLab with minimal effort. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 4c213f21920..b7754e60837 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Import your project from GitHub to GitLab Using the importer, you can import your GitHub repositories to GitLab.com or to diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 2f87f257754..b9aea629e85 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Project importing from GitLab.com to your private GitLab instance You can import your existing GitLab.com projects to your GitLab instance, but keep in diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index a0da68eb513..86b671c8371 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +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 +--- + # Migrating projects to a GitLab instance 1. [From Bitbucket Cloud](bitbucket.md) @@ -47,6 +54,10 @@ Keep in mind the limitations of the [import/export feature](../settings/import_e You will still need to migrate your Container Registry over a series of Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts. +## Migrating from GitLab.com to self-managed GitLab + +The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an admin through the UI or the [users API](../../../api/users.md#user-creation). + ## Migrating between two self-managed GitLab instances The best method for migrating from one GitLab instance to another, diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index db48282a8f3..0b8807bb9b3 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import your Jira project issues to GitLab > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. @@ -43,6 +49,7 @@ Importing large projects may take several minutes depending on the size of the i 1. On the **{issues}** **Issues** page, click the **Import Issues** (**{import}**) button. 1. Select **Import from Jira**. + This option is only visible if you have the [correct permissions](#permissions).  diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 86c8b276887..0374e0acf9a 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -1,6 +1,13 @@ +--- +type: howto +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 +--- + # Import multiple repositories by uploading a manifest file -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28811) in GitLab 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. GitLab allows you to import all the required Git repositories based on a manifest file like the one used by the diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index cbcef7a2fb0..dbc1c491493 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -1,3 +1,10 @@ +--- +type: howto +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 +--- + # Migrating from Perforce Helix [Perforce Helix](https://www.perforce.com/) provides a set of tools which also diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index c81d489f12b..a19068199db 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -1,6 +1,13 @@ +--- +type: howto +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 +--- + # Import Phabricator tasks into a GitLab project -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/60562) in GitLab 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index c20b1cb7f5e..9b5e43aae79 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -1,3 +1,10 @@ +--- +type: howto +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 +--- + # Import project from repo by URL You can import your existing repositories by providing the Git URL: diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index cf034aafca9..d5f4a014705 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -1,3 +1,10 @@ +--- +type: howto +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 +--- + # Migrating from SVN to GitLab Subversion (SVN) is a central version control system (VCS) while @@ -75,7 +82,7 @@ For more information regarding the SubGit configuration options, refer to ### Initial translation -Now that SubGit has configured the Git/SVN repos, run `subgit` to perform the +Now that SubGit has configured the Git/SVN repositories, run `subgit` to perform the initial translation of existing SVN revisions into the Git repository: ```shell @@ -159,7 +166,7 @@ svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt ``` If your SVN repository requires a username and password add the -`--username <username>` and `--password <password` flags to the above command. +`--username <username>` and `--password <password>` flags to the above command. `svn2git` also supports excluding certain file paths, branches, tags, etc. See [svn2git documentation](https://github.com/nirvdrum/svn2git) or run `svn2git --help` for full documentation on all of the available options. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 9b148224e10..1c9ee7476bd 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -6,7 +6,7 @@ type: concepts Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes -[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/overview?view=azure-devops) +[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/what-is-tfvc?view=azure-devops) (TFVC), a centralized version control system similar to Git. In this document, we focus on the TFVC to Git migration. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 50272f0e007..3a4e240fb6c 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -100,7 +100,7 @@ When you create a project in GitLab, you'll have access to a large number of - [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)** - [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** -- [License Compliance](../compliance/license_compliance/index.md): approve and blacklist licenses for projects. **(ULTIMATE)** +- [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)** - [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)** - [Static Site Editor](static_site_editor/index.md): quickly edit content on static websites without prior knowledge of the codebase or Git commands. @@ -144,6 +144,17 @@ To view your starred projects: - Number of open merge requests - Number of open issues +### Explore projects + +You can explore other popular projects available on GitLab. To explore projects: + +1. Click **Projects** in the navigation bar. +1. Click **Explore Projects**. + +GitLab displays a list of projects, sorted by last updated date. To view +projects with the most [stars](#star-a-project), click **Most stars**. To view +projects with the largest number of comments in the past month, click **Trending**. + ## Project settings Set the project's visibility level and the access levels to its various pages @@ -250,14 +261,14 @@ password <personal_access_token> ## Access project page with project ID -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53671) in GitLab 11.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. To quickly access a project from the GitLab UI using the project ID, visit the `/projects/:id` URL in your browser or other tool accessing the project. ## Project aliases **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. When migrating repositories to GitLab and they are being accessed by other systems, it's very useful to be able to access them using the same name especially when diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 52fcad8dd80..3cc76beb323 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -273,7 +273,7 @@ you defined. ### `projects` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10904) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. You can limit where the "issuables" can be queried from: diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index db8f24fc1e1..7b21c590c8a 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -22,7 +22,7 @@ need to be configured in a Bamboo build plan before GitLab can integrate. 1. Choose 'Repository triggers the build when changes are committed' 1. Check one or more repositories checkboxes 1. Enter the GitLab IP address in the 'Trigger IP addresses' box. This is a - whitelist of IP addresses that are allowed to trigger Bamboo builds. + list of IP addresses that are allowed to trigger Bamboo builds. 1. Save the trigger. 1. In the left pane, select a build stage. If you have multiple build stages you want to select the last stage that contains the Git checkout task. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 848e89c18cb..4eaf3a0d4b4 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,25 +1,34 @@ -# Custom Issue Tracker Service +# Custom Issue Tracker service -To enable the Custom Issue Tracker integration in a project, navigate to the -[Integrations page](overview.md#accessing-integrations), click -the **Customer Issue Tracker** service, and fill in the required details on the page as described -in the table below. You will be able to edit the title and description later as well. +To enable the Custom Issue Tracker integration in a project: -| Field | Description | -| ----- | ----------- | -| `title` | A title for the issue tracker (to differentiate between instances, for example). | -| `description` | A name for the issue tracker (to differentiate between instances, for example) | -| `project_url` | The URL to the project in the custom issue tracker. | -| `issues_url` | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | -| `new_issue_url` | Currently unused. Will be changed in a future release. | +1. Go to **{settings}** **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. -Once you have configured and enabled Custom Issue Tracker Service you'll see a link on the GitLab project pages that takes you to that custom issue tracker. + These are some of the required fields: + + | Field | Description | + | --------------- | ----------- | + | **Title** | A title for the issue tracker (for example, to differentiate between instances). | + | **Description** | A name for the issue tracker (for example, to differentiate between instances). | + | **Project URL** | The URL to the project in the custom issue tracker. | + | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | + | **New issue URL** | Currently unused. Will be changed in a future release. | + +1. Click **Test settings and save changes**. + +After you configure and enable the Custom Issue Tracker service, you'll see a link on the GitLab +project pages that takes you to that custom issue tracker. ## Referencing issues -- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string in CAPS and `<ID>` -is a number used in the target project of the custom integration (for example, `PROJECT-143`). -- `ANYTHING` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. -- When building the hyperlink, the `ANYTHING` part is ignored, and links always point to the address +Issues are referenced with `<ANYTHING>-<ID>` (for example, `PROJECT-143`), where `<ANYTHING>` can be any string in CAPS, and `<ID>` +is a number used in the target project of the custom integration. + +`<ANYTHING>` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. + +When building the hyperlink, the `<ANYTHING>` part is ignored, and links always point to the address specified in `issues_url`, so in the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 2234727dd82..57c1e54e48c 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Generic alerts integration -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. GitLab can accept alerts from any source via a generic webhook receiver. When you set up the generic alerts integration, a unique endpoint will @@ -18,6 +18,9 @@ create an issue with the payload in the body of the issue. You can always The entire payload will be posted in the issue discussion as a comment authored by the GitLab Alert Bot. +NOTE: **Note** +In GitLab versions 13.1 and greater, you can configure [External Prometheus instances](prometheus.md#external-prometheus-instances) to use this endpoint. + ## Setting up generic alerts To set up the generic alerts integration: @@ -28,7 +31,7 @@ To set up the generic alerts integration: ## Customizing the payload -You can customize the payload by sending the following parameters. All fields are optional: +You can customize the payload by sending the following parameters. All fields other than `title` are optional: | Property | Type | Description | | -------- | ---- | ----------- | @@ -39,6 +42,7 @@ You can customize the payload by sending the following parameters. All fields ar | `monitoring_tool` | String | The name of the associated monitoring tool. | | `hosts` | String or Array | One or more hosts, as to where this incident occurred. | | `severity` | String | The severity of the alert. Must be one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Default is `critical`. | +| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. | TIP: **Payload size:** Ensure your requests are smaller than the [payload application limits](../../../administration/instance_limits.md#generic-alert-json-payloads). @@ -65,5 +69,7 @@ Example payload: "service": "service affected", "monitoring_tool": "value", "hosts": "value", + "severity": "high", + "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385" } ``` diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 42d8eadd35e..f0977a4ea76 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,6 +1,6 @@ # GitHub project integration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3836) in GitLab Premium 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab Premium 10.6. GitLab provides an integration for updating the pipeline statuses on GitHub. This is especially useful if using GitLab for CI/CD only. @@ -39,7 +39,7 @@ to configure pipelines to run for open pull requests. #### Static / dynamic status check names > - Introduced in GitLab 11.5: using static status check names as opt-in option. -> - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/9931), static status check names is default behavior for new projects. +> - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. This makes it possible to mark these status checks as _Required_ on GitHub. With **Static status check names** enabled on the integration page, your diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 49b6a3f6450..7a827364d41 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -8,7 +8,7 @@ The GitLab Slack application is only configurable for GitLab.com. It will **not* work for on-premises installations where you can configure the [Slack slash commands](slack_slash_commands.md) service instead. We're planning to make this configurable for all GitLab installations, but there's -no ETA - see [#28164](https://gitlab.com/gitlab-org/gitlab/issues/28164). +no ETA - see [#28164](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). Slack provides a native application which you can enable via your project's integrations on GitLab.com. @@ -32,7 +32,7 @@ integration settings. Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your team](https://slack.com/help/articles/202035138). +docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-an-app-to-your-workspace). To enable GitLab's service for your Slack team: diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index f33833a9c93..f65b31150a9 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,6 +1,6 @@ # Hangouts Chat service -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/43756) in GitLab 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. The Hangouts Chat service sends notifications from GitLab to the room for which the webhook was created. 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 differnew file mode 100644 index 00000000000..08d7d6603d2 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_yaml_validation_v13_1.png diff --git a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png Binary files differdeleted file mode 100644 index 8899852ed04..00000000000 --- a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.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 differnew file mode 100644 index 00000000000..56a0a508a1d --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v13_1.png 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 differnew file mode 100644 index 00000000000..4dc141f0e7f --- /dev/null +++ b/doc/user/project/integrations/img/related_links_v13_1.png diff --git a/doc/user/project/integrations/img/slack_configuration.png b/doc/user/project/integrations/img/slack_configuration.png Binary files differdeleted file mode 100644 index 4d5e6ae7856..00000000000 --- a/doc/user/project/integrations/img/slack_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 9fa92f19e4f..619c94b282b 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -3,7 +3,7 @@ An API token is needed when integrating with Jira Cloud, follow the steps below to create one: -1. Log in to <https://id.atlassian.com/manage/api-tokens> with your email address. +1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. NOTE: **Note** It is important that the user associated with this email address has *write* access diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 6c40e5b9696..0d17ff51372 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -25,7 +25,7 @@ Once enabled, GitLab will automatically detect metrics from known services in th ### Managed Prometheus on Kubernetes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28916) in GitLab 10.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. @@ -61,7 +61,7 @@ will help you to quickly create a deployment: 1. Navigate to your project's **CI/CD > Pipelines** page, and run a pipeline on any branch. 1. When the pipeline has run successfully, graphs will be available on the **Operations > Metrics** page. - + #### Using the Metrics Dashboard @@ -209,10 +209,19 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) - `ci_project_namespace` - `ci_project_path` - `ci_environment_name` +- `__range` NOTE: **Note:** Variables for Prometheus queries must be lowercase. +###### __range + +The `__range` variable is useful in Prometheus +[range vector selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#range-vector-selectors). +Its value is the total number of seconds in the dashboard's time range. +For example, if the dashboard time range is set to 8 hours, the value of +`__range` is `28800s`. + ##### User-defined variables [Variables can be defined](#templating-templating-properties) in a custom dashboard YAML file. @@ -244,7 +253,7 @@ http://gitlab.com/<user>/<project>/-/environments/<environment_id>/metrics?dashb #### Editing additional metrics from the dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/208976) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208976) in GitLab 12.9. You can edit existing additional custom metrics by clicking the **{ellipsis_v}** **More actions** dropdown and selecting **Edit metric**. @@ -252,7 +261,7 @@ You can edit existing additional custom metrics by clicking the **{ellipsis_v}** ### Defining custom dashboards per project -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/59974) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. By default, all projects include a GitLab-defined Prometheus dashboard, which includes a few key metrics, but you can also define your own custom dashboards. @@ -308,8 +317,8 @@ supported and will not be available in the UI. #### Duplicating a GitLab-defined dashboard -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/37238) in GitLab 12.7. -> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37238) in GitLab 12.7. +> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. You can save a complete copy of a GitLab defined dashboard along with all custom metrics added to it. Resulting `.yml` file can be customized and adapted to your project. @@ -326,6 +335,42 @@ new branch. If you select your **default** branch, the new dashboard becomes immediately available. If you select another branch, this branch should be merged to your **default** branch first. +#### Dashboard YAML syntax validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33202) in GitLab 13.1. + +To confirm your dashboard definition contains valid YAML syntax: + +1. Navigate to **{doc-text}** **Repository > Files**. +1. Navigate to your dashboard file in your repository. +1. Review the information pane about the file, displayed above the file contents. + +Files with valid syntax display **Metrics Dashboard YAML definition is valid**, +and files with invalid syntax display **Metrics Dashboard YAML definition is invalid**. + + + +When **Metrics Dashboard YAML definition is invalid** at least one of the following messages is displayed: + +1. `dashboard: can't be blank` [learn more](#dashboard-top-level-properties) +1. `panel_groups: can't be blank` [learn more](#dashboard-top-level-properties) +1. `group: can't be blank` [learn more](#panel-group-panel_groups-properties) +1. `panels: can't be blank` [learn more](#panel-group-panel_groups-properties) +1. `metrics: can't be blank` [learn more](#panel-panels-properties) +1. `title: can't be blank` [learn more](#panel-panels-properties) +1. `query: can't be blank` [learn more](#metrics-metrics-properties) +1. `query_range: can't be blank` [learn more](#metrics-metrics-properties) +1. `unit: can't be blank` [learn more](#metrics-metrics-properties) +1. `YAML syntax: The parsed YAML is too big` + + This is displayed when the YAML file is larger than 1 MB. + +1. `YAML syntax: Invalid configuration format` + + This is displayed when the YAML file is empty or does not contain valid YAML. + +Metrics Dashboard YAML definition validation information is also available as a [GraphQL API field](../../../api/graphql/reference/index.md#metricsdashboard) + #### Dashboard YAML properties Dashboards have several components: @@ -342,16 +387,27 @@ The following tables outline the details of expected properties. | ------ | ------ | ------ | ------ | | `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | | `panel_groups` | array | yes | The panel groups which should be on the dashboard. | -| `templating` | Hash | no | Top level key under which templating related options can be added. | +| `templating` | hash | no | Top level key under which templating related options can be added. | +| `links` | array | no | Add links to display on the dashboard. | ##### **Templating (`templating`) properties** | Property | Type | Required | Description | | -------- | ---- | -------- | ----------- | -| `variables` | Hash | no | Variables can be defined here. | +| `variables` | hash | yes | Variables can be defined here. | Read the documentation on [templating](#templating-variables-for-metrics-dashboards). +##### **Links (`links`) properties** + +| Property | Type | Required | Description | +| -------- | ---- | -------- | ----------- | +| `url` | string | yes | The address of the link. | +| `title` | string | no | Display title for the link. | +| `type` | string | no | Type of the link. Specifies the link type, can be: `grafana` | + +Read the documentation on [links](#add-related-links-to-custom-dashboards). + ##### **Panel group (`panel_groups`) properties** | Property | Type | Required | Description | @@ -371,6 +427,7 @@ Read the documentation on [templating](#templating-variables-for-metrics-dashboa | `max_value` | number | no | Denominator value used for calculating [percentile based results](#percentile-based-results) | | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | +| `links` | array | no | Add links to display on the chart's [context menu](#chart-context-menu). | ##### **Axis (`panels[].y_axis`) properties** @@ -472,7 +529,7 @@ Note the following properties:  -Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/issues/202696), the y-axis values will automatically scale according to the data. Previously, it always started from 0. +Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values will automatically scale according to the data. Previously, it always started from 0. ##### Anomaly chart @@ -574,7 +631,7 @@ Note the following properties: ##### Stacked column -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30583) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30583) in GitLab 12.8. To add a stacked column panel type to a dashboard, look at the following sample dashboard file: @@ -639,7 +696,7 @@ Note the following properties: ###### Percentile based results -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201946) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201946) in GitLab 12.8. Query results sometimes need to be represented as a percentage value out of 100. You can use the `max_value` property at the root of the panel definition: @@ -662,7 +719,7 @@ For example, if you have a query value of `53.6`, adding `%` as the unit results ##### Heatmaps -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30581) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30581) in GitLab 12.5. To add a heatmap panel type to a dashboard, look at the following sample dashboard file: @@ -699,7 +756,7 @@ Templating variables can be used to make your metrics dashboard more versatile. [dashboard YAML](#dashboard-top-level-properties). Define your variables in the `variables` key, under `templating`. The value of the `variables` key should be a hash, and each key under `variables` -defines a templating variable on the dashboard. +defines a templating variable on the dashboard, and may contain alphanumeric and underscore characters. A variable can be used in a Prometheus query in the same dashboard using the syntax described [here](#using-variables). @@ -766,7 +823,7 @@ templating: ###### Full syntax -This example creates a variable called `variable1`, with a default value of `var1_option_2`. +This example creates a variable called `variable1`, with a default value of `value_option_2`. The label for the text box on the UI will be the value of the `label` key. The dashboard UI will display a dropdown with `Option 1` and `Option 2` as the choices. @@ -789,9 +846,50 @@ templating: default: true # (Optional) This option should be the default value of this variable. ``` +### Add related links to custom dashboards + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216385) in GitLab 13.1. + +You can embed links to other dashboards or external services in your custom +dashboard by adding **Related links** to your dashboard's YAML file. Related links +open in the same tab as the dashboard. Related links can be displayed in the +following locations on your dashboard: + +- At the top of your dashboard as the top level [`links` dashboard property](#dashboard-top-level-properties). +- In charts context menus as the [`links` property of a panel](#panel-panels-properties). + +Related links can contain the following attributes: + +- `url`: The full URL to the link. Required. +- `title`: A phrase describing the link. Optional. If this attribute is not set, + the full URL is used for the link title. +- `type`: A string declaring the type of link. Optional. If set to `grafana`, the + dashboard's time range values are converted to Grafana's time range format and + appended to the `url`. + +The dashboard's time range is appended to the `url` as URL parameters. + +The following example shows two related links (`GitLab.com` and `GitLab Documentation`) +added to a dashboard: + + + +#### Links Syntax + +```yaml +links: + - title: GitLab.com + url: https://gitlab.com + - title: GitLab Documentation + url: https://docs.gitlab.com + - title: Public Grafana playground dashboard + url: https://play.grafana.org/d/000000012/grafana-play-home?orgId=1 + type: grafana +``` + ### View and edit the source file of a custom dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5. When viewing a custom dashboard of a project, you can view the original `.yml` file by clicking on the **Edit dashboard** button. @@ -812,7 +910,7 @@ The options are: ### Dashboard Annotations -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/215224) in GitLab 13.0. You can use **Metrics Dashboard Annotations** to mark any important events on @@ -827,6 +925,14 @@ You can create annotations by making requests to the  +#### Retention policy + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211433) in GitLab 13.01. + +To avoid excessive storage space consumption by stale annotations, records attached +to time periods older than two weeks are removed daily. This recurring background +job runs at 1:00 a.m. local server time. + ### Expand panel > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0. @@ -839,7 +945,7 @@ browser, or pressing the <kbd>Esc</kbd> key. ### View Logs **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/122013) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122013) in GitLab 12.8. If you have [Logs](../clusters/kubernetes_pod_logs.md) enabled, you can navigate from the charts in the dashboard to view Logs by @@ -881,8 +987,8 @@ To remove the alert, click back on the alert icon for the desired metric, and cl #### External Prometheus instances ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. ->- [Moved](https://gitlab.com/gitlab-org/gitlab/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. +>- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. For manually configured Prometheus servers, a notify endpoint is provided to use with Prometheus webhooks. If you have manual configuration enabled, an **Alerts** section is added to **Settings > Integrations > Prometheus**. This contains the *URL* and *Authorization Key*. The **Reset Key** button will invalidate the key and generate a new one. @@ -903,12 +1009,15 @@ receivers: In order for GitLab to associate your alerts with an [environment](../../../ci/environments/index.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. +NOTE: **Note** +In GitLab versions 13.1 and greater, you can configure your manually configured Prometheus server to use the [Generic alerts integration](generic_alerts.md). + ### Taking action on incidents **(ULTIMATE)** ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. ->- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. -Alerts can be used to trigger actions, like opening an issue automatically (enabled by default since `12.1`). To configure the actions: +Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: 1. Navigate to your project's **Settings > Operations > Incidents**. 1. Enable the option to create issues. @@ -931,14 +1040,14 @@ When GitLab receives a **Recovery Alert**, it will automatically close the assoc To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, which will apply to all incidents. To limit quick actions or other information to only specific types of alerts, use the `annotations/gitlab_incident_markdown` field. -Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well. +Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well. If the metric exceeds the threshold of the alert for over 5 minutes, an email will be sent to all [Maintainers and Owners](../../permissions.md#project-members-permissions) of the project. ## Determining the performance impact of a merge > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10408) in GitLab 9.2. -> - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/issues/27439) of the 30 minute averages. +> - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. Developers can view the performance impact of their changes within the merge request workflow. @@ -1031,7 +1140,7 @@ For [manually configured Prometheus instances](#manual-configuration-of-promethe ### Embedding Cluster Health Charts **(ULTIMATE)** -> [Introduced](<https://gitlab.com/gitlab-org/gitlab/issues/40997>) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](<https://gitlab.com/gitlab-org/gitlab/-/issues/40997>) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. [Cluster Health Metrics](../clusters/index.md#monitoring-your-kubernetes-cluster-ultimate) can also be embedded in [GitLab-flavored Markdown](../../markdown.md). @@ -1075,7 +1184,7 @@ This will render like so: #### Embedding charts via integration with Grafana HTTP API -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31376) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31376) in GitLab 12.5. Each project can support integration with one Grafana instance. This configuration allows a user to copy a link to a panel in Grafana, then paste it into a GitLab Markdown field. The chart will be rendered in the GitLab chart format. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md index 691d20e5de2..7b216ced1cc 100644 --- a/doc/user/project/integrations/prometheus_units.md +++ b/doc/user/project/integrations/prometheus_units.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Unit formats reference -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201999) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201999) in GitLab 12.9. You can select units to format your charts by adding `format` to your [axis configuration](prometheus.md#dashboard-yaml-properties). @@ -19,7 +19,7 @@ Currently, your [internationalization and localization options](https://en.wikip For generic or default data, numbers are formatted according to the current locale in [engineering notation](https://en.wikipedia.org/wiki/Engineering_notation). -While an [engineering notation exists for the web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat), GitLab uses a version based off the [scientific notation](https://en.wikipedia.org/wiki/Scientific_notation). GitLab formatting acts in accordance with SI prefixes. For example, using GitLab notation, `1500.00` becomes `1.5k` instead of `1.5E3`. Keep this distinction in mind when using the engineering notation for your metrics. +While an [engineering notation exists for the web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), GitLab uses a version based off the [scientific notation](https://en.wikipedia.org/wiki/Scientific_notation). GitLab formatting acts in accordance with SI prefixes. For example, using GitLab notation, `1500.00` becomes `1.5k` instead of `1.5E3`. Keep this distinction in mind when using the engineering notation for your metrics. Formats: `engineering` diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 419340c14ef..79fc8eceddf 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -23,7 +23,23 @@ The Slack Notifications Service allows your GitLab project to send events (e.g. Your Slack team will now start receiving GitLab event notifications as configured. - +### Triggers available for Slack notifications + +The following triggers are available for Slack notifications: + +- **Push**: Triggered by a push to the repository. +- **Issue**: Triggered when an issue is created, updated, or closed. +- **Confidential issue**: Triggered when a confidential issue is created, + updated, or closed. +- **Merge request**: Triggered when a merge request is created, updated, or + merged. +- **Note**: Triggered when someone adds a comment. +- **Confidential note**: Triggered when someone adds a confidential note. +- **Tag push**: Triggered when a new tag is pushed to the repository. +- **Pipeline**: Triggered when a pipeline status changes. +- **Wiki page**: Triggered when a wiki page is created or updated. +- **Deployment**: Triggered when a deployment finishes. +- **Alert**: Triggered when a new, unique alert is recorded. ## Troubleshooting diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index a6e688887b6..10735e33746 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ You can configure GitLab to send notifications to a Webex Teams space. ## Create a webhook for the space -1. Go to the [Incoming Webooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems). 1. Click **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space that will receive the notifications. 1. Click **ADD**. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 89e84dda0e8..5a0ca03a646 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -89,7 +89,7 @@ You can turn this off in the webhook settings in your GitLab projects. ## Branch filtering -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/20338) in GitLab 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. Push events can be filtered by branch using a branch name or wildcard pattern to limit which push events are sent to your webhook endpoint. By default the diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 9903a711987..89b17609698 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Issue Boards > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5554) in [GitLab 8.11](https://about.gitlab.com/releases/2016/08/22/gitlab-8-11-released/#issue-board). @@ -190,7 +196,7 @@ as shown in the following table: ### Multiple issue boards > - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. > - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). Multiple issue boards allow for more than one issue board for a given project or group. @@ -290,7 +296,7 @@ Multiple group issue boards were originally [introduced](https://about.gitlab.co ### Assignee lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. Like in a regular list that shows all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. @@ -311,7 +317,7 @@ To remove an assignee list, just as with a label list, click the trash icon. ### Milestone lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6469) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. To add a milestone list: @@ -330,7 +336,7 @@ As in other list types, click the trash icon to remove a list. ## Work In Progress limits **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11403) in GitLab 12.7 +> [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. @@ -352,7 +358,7 @@ To set a WIP limit for a list: ## Blocked issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34723) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34723) in GitLab 12.8. If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked status. @@ -370,7 +376,7 @@ status. - [Filter issues](#filter-issues) that appear across your issue board. - [Create workflows](#create-workflows). - [Drag issues between lists](#drag-issues-between-lists). -- [Mulit-select issue cards](#multi-select-issue-cards). +- [Multi-select issue cards](#multi-select-issue-cards). - [Re-order issues in lists](#issue-ordering-in-a-list). - Drag and reorder the lists. - Change issue labels (by dragging an issue between lists). @@ -501,7 +507,7 @@ When dragging issues between lists, different behavior occurs depending on the s ### Multi-select issue cards -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18954) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index 3bfd24c9654..a026854a947 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Associate a Zoom meeting with an issue > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index a292ce64af9..602a6d79848 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Confidential issues > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3282) in GitLab 8.6. @@ -80,7 +86,7 @@ project's search results respectively. ## Merge Requests for Confidential Issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/58583) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. To help prevent confidential information being leaked from a public project in the process of resolving a confidential issue, confidential issues can be diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index e774fd4480b..6cc31a45309 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Crosslinking Issues Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 64f56221632..981c2a7c34a 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -3,10 +3,6 @@ > - [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. -CAUTION: **Warning:** -This an **alpha** feature and is subject to change at any time without -prior notice. - ## Overview Design Management allows you to upload design assets (wireframes, mockups, etc.) @@ -45,19 +41,19 @@ If the requirements are not met, the **Designs** tab displays a message to the u Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`. -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 [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. ## Limitations - Design uploads are limited to 10 files at a time. - Design Management data - [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/issues/13429) yet. -- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/issues/13426) - when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab/issues/13427) + [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429) yet. +- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/-/issues/13426) + when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) when an issue is deleted. - From GitLab 12.7, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) - by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/issues/32467). + by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). - Only the latest version of the designs can be deleted. - Deleted designs cannot be recovered but you can see them on previous designs versions. @@ -71,8 +67,8 @@ Navigate to the **Design Management** page from any issue by clicking the **Desi To upload design images, click the **Upload Designs** button and select images to upload. -[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 dropzone to upload them. +[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.  @@ -91,7 +87,7 @@ Copy-and-pasting has some limitations: - Copy/pasting designs is not supported on Internet Explorer. Designs with the same filename as an existing uploaded design will create a new version -of the design, and will replace the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design will also create a new version, +of the design, and will replace the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design will also create a new version, provided the filenames are the same. Designs cannot be added if the issue has been moved, or its @@ -123,19 +119,19 @@ to help summarize changes between versions. ### Exploring designs by zooming -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13217) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. Designs can be explored in greater detail by zooming in and out of the image. Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. While zoomed, you can still [start new discussions](#starting-discussions-on-designs) on the image, and see any existing ones. -[Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197324) in GitLab 12.10, while zoomed in, +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10, while zoomed in, you can click-and-drag on the image to move around it.  ## Deleting designs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11089) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. There are two ways to delete designs: manually delete them individually, or select a few of them to delete at once, @@ -169,7 +165,7 @@ A pin is added to the image, identifying the discussion's location.  -[Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8, +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8, you can adjust a pin's position by dragging it around the image. This is useful for when your design layout has changed between revisions, or if you need to move an existing pin to add a new one in its place. @@ -180,3 +176,60 @@ Different discussions have different pin numbers: From GitLab 12.5 on, new discussions will be outputted to the issue activity, so that everyone involved can participate in the discussion. + +## Resolve Design threads + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. + +Discussion threads can be resolved on Designs. You can mark a thread as resolved +or unresolved by clicking the **Resolve thread** icon at the first comment of the +discussion. + + + +Pinned comments can also be resolved or unresolved in their threads. +When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve +the thread once published. + + + +## Referring to designs in Markdown + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in **GitLab 13.1**. +> - It is deployed behind a feature flag, disabled by default. +> - It is disabled on GitLab.com. +> - It is not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-design-references-core-only). **(CORE ONLY)** + +We support referring to designs in [Markdown](../../markdown.md), which is available +throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. + +At present, full URL references are supported. For example, if we refer to a design +somewhere with: + +```markdown +See https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png +``` + +This will be rendered as: + +> See [#123[homescreen.png]](https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png) + +### 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**. +[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(:design_management_reference_filter_gfm_pipeline) +``` + +To disable it: + +```ruby +Feature.disable(:design_management_reference_filter_gfm_pipeline) +``` diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 0be0cdd11bd..56fb4ca5cc7 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Due dates > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3614) in GitLab 8.7. diff --git a/doc/user/project/issues/img/new_issue.png b/doc/user/project/issues/img/new_issue.png Binary files differdeleted file mode 100644 index 07d65a93070..00000000000 --- a/doc/user/project/issues/img/new_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_v13_1.png b/doc/user/project/issues/img/new_issue_v13_1.png Binary files differnew file mode 100644 index 00000000000..a66846c234e --- /dev/null +++ b/doc/user/project/issues/img/new_issue_v13_1.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 differnew file mode 100644 index 00000000000..bd9d1f7a77c --- /dev/null +++ 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 differnew file mode 100644 index 00000000000..5cd005f0799 --- /dev/null +++ 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 22221531360..06a80672769 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Issues Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. @@ -151,7 +157,7 @@ context, such as past work, dependencies, or duplicates. ### Crosslinking issues -You can [crosslink issues](crosslinking_issues.md) by referencing an issue from another +You can [cross-link issues](crosslinking_issues.md) by referencing an issue from another issue or merge request by including its URL or ID. The referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR. @@ -173,7 +179,7 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. ### Health status **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 65e21566d5d..6d34f91d37f 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Issue Data and Actions Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. @@ -185,7 +191,7 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [Since GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/10103), changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** +> [Since GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103), changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** ### Mentions @@ -296,7 +302,7 @@ You can also close the issue from here, so you don't need to scroll to the top o ### Zoom meetings -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31103) in GitLab 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31103) in GitLab 12.3. You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove_zoom` [quick actions](../quick_actions.md) as part of [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). @@ -305,3 +311,9 @@ Attaching a [Zoom](https://zoom.us) call an issue results in a **Join Zoom meeting** button at the top of the issue, just under the header. Read more how to [add or remove a zoom meeting](associate_zoom_meeting.md). + +### Publish an issue **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +If a status page application is associated with the project, you can use the `/publish` [quick action](../quick_actions.md) to publish the issue. Refer to [GitLab Status Page](../status_page/index.md) for more information. diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 74f607dd407..23c1520294d 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -1,5 +1,8 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Issue weight **(STARTER)** diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 4e329889e7c..08e3164b2eb 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -1,21 +1,28 @@ -# Managing Issues +--- +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 +--- + +# Managing issues [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues), [closing](#closing-issues), and [deleting](#deleting-issues) are key actions that you can do with issues. -## Create a new Issue +## Create a new issue -When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), as illustrated below. If you know -the values you want to assign to an issue, you can use the [Quick actions](../quick_actions.md) -feature to input values, instead of selecting them from lists. +When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), +as illustrated below. If you know the values you want to assign to an issue, you can use the +[Quick actions](../quick_actions.md) feature to input values, instead of selecting them from lists. - +While creating an issue, you can associate it to an existing epic from current group by +selecting it using **Epic** dropdown. -### Accessing the new Issue form +### Accessing the New Issue form -There are many ways to get to the new Issue form from within a project: +There are many ways to get to the New Issue form from within a project: - Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: @@ -36,9 +43,28 @@ There are many ways to get to the new Issue form from within a project:  +### Elements of the New Issue form + +> Ability to add the new issue to an epic [was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) +> in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. + + + +When you're creating a new issue, these are the fields you can fill in: + +- Title +- Description +- Checkbox to make the issue confidential +- Assignee +- Weight +- Epic **(PREMIUM)** +- Due date +- Milestone +- Labels + ### New issue from the group-level Issue Tracker -Go to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker +Go to the Group dashboard and click **Issues** in the sidebar to visit the Issue Tracker for all projects in your Group. Select the project you'd like to add an issue for using the dropdown button at the top-right of the page. @@ -107,11 +133,11 @@ field). Follow these examples to form your new issue URL with prefilled fields. - For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` + and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` - For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` + and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` - For a new issue in the GitLab Community Edition project with a pre-filled title, - a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` + a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` ## Moving Issues @@ -147,7 +173,7 @@ issues.each do |issue| end; nil ``` -## Closing Issues +## Closing issues When you decide that an issue is resolved, or no longer needed, you can close the issue using the close button: @@ -226,6 +252,8 @@ when used from the command line with `git commit -m`. #### Disabling automatic issue closing +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. + The automatic issue closing feature can be disabled on a per-project basis within the [project's repository settings](../settings/index.md). Referenced issues will still be displayed as such but won't be closed automatically. @@ -243,7 +271,7 @@ In order to change the default issue closing pattern, GitLab administrators must [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) of your installation. -## Deleting Issues +## Deleting issues > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2982) in GitLab 8.6 diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index dff6a6031d7..c11977f5bee 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,6 +1,12 @@ +--- +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 +--- + # Multiple Assignees for Issues **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). ## Overview diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 8002b528a80..445c28492df 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Related issues **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index d52b629bfed..7cbd9906800 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -1,4 +1,10 @@ -# Sorting and Ordering Issue Lists +--- +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 +--- + +# Sorting and ordering issue lists You can sort a list of issues several ways, including by issue creation date, milestone due date, etc. The available sorting options can change based on the context of the list. @@ -9,7 +15,7 @@ similar to [issue boards](../issue_board.md#issue-ordering-in-a-list). ## Manual sorting -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/62178) in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. When you select **Manual** sorting, you can change the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index f3b59147d5b..406938519b1 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,3 +1,9 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Labels ## Overview @@ -131,7 +137,7 @@ to the project: ## Scoped labels **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. Scoped labels allow teams to use the label feature to annotate issues, merge requests and epics with mutually exclusive labels. This can enable more complicated workflows @@ -203,8 +209,8 @@ to label notifications for the project only, or the whole group. ## Label priority -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14189) in GitLab 8.9. -> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/issues/14523) considers changing this. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14189) in GitLab 8.9. +> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. Labels can have relative priorities, which are used in the **Label priority** and **Priority** sort orders of the epic, issue, and merge request list pages. Prioritization @@ -229,7 +235,7 @@ If you sort by `Label priority`, GitLab uses this sort comparison order: 1. Items without a prioritized label. Ties are broken arbitrarily. Note that only the highest prioritized label is checked, -and labels with a lower priority are ignored. See this [related issue](https://gitlab.com/gitlab-org/gitlab/issues/14523) +and labels with a lower priority are ignored. See this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) for more information.  diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 9020dc335b6..787a74b0065 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -8,7 +8,7 @@ You should have Maintainer or Owner [permissions](../../permissions.md) to add or import a new user to your project. To view, edit, add, and remove project's members, go to your -project's **Settings > Members**. +project's **Members**. ## Inherited membership @@ -27,7 +27,7 @@ From the image above, we can deduce the following things: - Administrator is the Owner and member of **all** groups and for that reason, there is an indication of an ancestor group and inherited Owner permissions. -[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/21727), you can filter this list +[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/21727), you can filter this list using the dropdown on the right side:  diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d0ceac3e1f3..033d69cbbfa 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -18,7 +18,7 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: -1. For 'Project Acme' use the left navigation menu to go to **Settings > Members** +1. For 'Project Acme' use the left navigation menu to go to **Members**  diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 427761281f6..417b85a6082 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -25,16 +25,6 @@ Accessibility Report in the merge request widget area:  -This widget comes with the `:accessibility_report_view` feature flag disabled by default while we test feature stability. -Once we have determined the widget is stable, this feature will be enabled by default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the -following command: - -```ruby -Feature.enable(:accessibility_report_view) -``` - ## Configure Accessibility Testing This example shows how to run [pa11y](https://pa11y.org/) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 0fa3d7be265..390d480724d 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -60,7 +60,7 @@ on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. 1. First, set up GitLab Runner with a - [docker-in-docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). + [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). 1. After configuring the Runner, add a new job to `.gitlab-ci.yml` that generates the expected report. 1. Define the `performance` job according to your version of GitLab: @@ -125,7 +125,7 @@ Key metrics are automatically extracted and shown in the merge request widget. ### Configuring degradation threshold -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27599) in GitLab 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert will only show up diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 3e76b9ec6b9..6685c50c1ed 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -33,7 +33,7 @@ request thread crosslinking the new commit and the existing merge request. Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. NOTE: **Note:** -We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/issues/202215) is planned for a future release. +We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. ## Cherry-picking a commit diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index beb90e30906..7b4d4b668d5 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -12,7 +12,7 @@ source code quality using GitLab Code Quality. Code Quality: - Uses [Code Climate Engines](https://codeclimate.com), which are - free and open source. Code Quality doesn't require a Code Climate + free and open source. Code Quality does not require a Code Climate subscription. - Runs in [pipelines](../../../ci/pipelines/index.md) using a Docker image built in the [GitLab Code @@ -67,10 +67,10 @@ This example shows how to run Code Quality on your code by using GitLab CI/CD an First, you need GitLab Runner configured: -- For the [docker-in-docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). +- For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). - With enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. -Once you set up the Runner, include the CodeQuality template in your CI config: +Once you set up the Runner, include the Code Quality template in your CI configuration: ```yaml include: @@ -80,10 +80,9 @@ include: The above example will create a `code_quality` job in your CI/CD pipeline which will scan your source code for code quality issues. The report will be saved as a [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality-starter) -that you can later download and analyze. Due to implementation limitations we always -take the latest Code Quality artifact available. +that you can later download and analyze. -It is also possible to override the URL to the Code Quality image by +It's also possible to override the URL to the Code Quality image by setting the `CODE_QUALITY_IMAGE` variable. This is particularly useful if you want to lock in a specific version of Code Quality, or use a fork of it: @@ -108,7 +107,7 @@ code_quality: paths: [gl-code-quality-report.json] ``` -The included `code_quality` job is running in the `test` stage, so it needs to be included in your CI config, like so: +The included `code_quality` job is running in the `test` stage, so it needs to be included in your CI configuration, like so: ```yaml stages: @@ -120,7 +119,7 @@ This information will be automatically extracted and shown right in the merge re CAUTION: **Caution:** On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged docker commands on the Runner +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. @@ -129,9 +128,8 @@ allowing access only to trusted actors. 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 may be removed -in the next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` -configuration to reflect that change. +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. For GitLab 11.5 and later, the job should look like: @@ -157,7 +155,7 @@ code_quality: 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 is highly recommended to include the Code Quality template as shown in the +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: @@ -241,7 +239,7 @@ do this: [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality-starter). 1. Configure your tool to generate the Code Quality report artifact as a JSON - file that implements subset of the [Code Climate + file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). The Code Quality report artifact JSON file must contain an array of objects @@ -288,28 +286,28 @@ Once the Code Quality job has completed: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. -If multiple jobs in a pipeline generate a code quality artifact, only the artifact from -the last created job (the job with the largest job ID) is used. To avoid confusion, -configure only one job to generate a code quality artifact. +## Troubleshooting -If the Code Quality report doesn't have anything to compare to, no information -will be displayed in the merge request area. That is the case when you add the -Code Quality job in your `.gitlab-ci.yml` for the very first time. -Consecutive merge requests will have something to compare to and the Code Quality -report will be shown properly. +### No Code Quality report is displayed in a Merge Request -These reports will only be available as long as the Code Quality artifact(s) required to generate -them are also available. See -[`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) for more details. +This can be due to multiple reasons: -<!-- ## Troubleshooting +- You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not + have anything to compare to yet, so no information can be displayed. Future merge + requests will have something to compare to. +- If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), + nothing will be displayed. +- The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD + setting can cause the Code Quality artifact(s) to expire faster than desired. +- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). + As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) + that are [ignored by GitLab](#implementing-a-custom-tool). You can: + - Configure the Code Quality tool to not output those types. + - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to + edit the `codeclimate.json` before the job completes. -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Only a single Code Quality report is displayed, but more are defined -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. --> +GitLab only uses the Code Quality artifact from the latest created job (with the largest job ID). +If multiple jobs in a pipeline generate a code quality artifact, those of earlier jobs are ignored. +To avoid confusion, configure only one job to generate a `codeclimate.json`. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 544727380e7..50d5decc2cc 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -12,8 +12,8 @@ to familiarize yourself with the concept, the terminology, and to learn what you can do with them. Every merge request starts by creating a branch. You can either -do it locally through the command line, via a Git CLI application, -or through the GitLab UI. +do it locally through the [command line](#new-merge-request-from-your-local-environment), via a Git CLI application, +or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through-the-ui). This document describes the several ways to create a merge request. @@ -100,7 +100,7 @@ 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, and the default branch in the current project as the target. -## New merge request from you local environment +## New merge request from your local environment Assuming you have your repository cloned into your computer and you'd like to start working on changes to files, start by creating and diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 0ab8d31403e..32eb0c73ed4 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -67,7 +67,7 @@ Once you have created the merge request, you can also: - Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). - Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](../../discussions/index.md#merge-request-reviews-premium) in order to create multiple comments on a diff and publish them once you're ready. **(PREMIUM)** +- Perform a [Review](../../discussions/index.md#merge-request-reviews) in order to create multiple comments on a diff and publish them once you're ready. - Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). @@ -86,7 +86,7 @@ and the merge request will be added to their #### Multiple assignees **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2038414dab8..5d2813f5bfc 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -54,7 +54,7 @@ To get started, read the [introduction to merge requests](getting_started.md). ## Merge request navigation tabs at the top -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33813) in GitLab 12.6. This positioning is experimental. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. So far, the navigation tabs present in merge requests to display **Discussion**, **Commits**, **Pipelines**, and **Changes** were located after the merge request @@ -86,35 +86,7 @@ See the features at your disposal to [review and manage merge requests](reviewin ## Testing and reports in merge requests -GitLab has the ability to test the changes included in a merge request, and can display -or link to useful information directly in the merge request page: - -| Feature | Description | -|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests | -| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | -| [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | -| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | -| [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | -| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | -| [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | -| [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | -| [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | -| [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | -| [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | -| [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | - -### Security Reports **(ULTIMATE)** - -In addition to the reports listed above, GitLab can do many types of [Security reports](../../application_security/index.md), -generated by scanning and reporting any vulnerabilities found in your project: - -| Feature | Description | -|-----------------------------------------------------------------------------------------|------------------------------------------------------------------| -| [Container Scanning](../../application_security/container_scanning/index.md) | Analyze your Docker images for known vulnerabilities. | -| [Dynamic Application Security Testing (DAST)](../../application_security/dast/index.md) | Analyze your running web applications for known vulnerabilities. | -| [Dependency Scanning](../../application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | -| [Static Application Security Testing (SAST)](../../application_security/sast/index.md) | Analyze your source code for known vulnerabilities. | +Learn about the options for [testing and reports](testing_and_reports_in_merge_requests.md) on the changes in a merge request. ## Authorization for merge requests diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index e5896e62397..dd90449cd86 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -34,10 +34,12 @@ minimum number of required approvers can still be set in the [project settings f ### Eligible approvers -The following can approve merge requests: +The following users can approve merge requests: -- Users being added as approvers at project or merge request level. -- [Code owners](#code-owners-as-eligible-approvers) to the files changed by the merge request. +- Users who have been added as approvers at the project or merge request levels with + developer or higher [permissions](../../permissions.md). +- [Code owners](#code-owners-as-eligible-approvers) of the files changed by the merge request + that have developer or higher [permissions](../../permissions.md). An individual user can be added as an approver for a project if they are a member of: @@ -46,7 +48,7 @@ An individual user can be added as an approver for a project if they are a membe - A group that has access to the project via a [share](../members/share_project_with_groups.md). A group of users can also be added as approvers. In the future, group approvers may be -[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/issues/2048). +[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). If a user is added as an individual approver and is also part of a group approver, then that user is just counted once. The merge request author, as well as users who have committed @@ -68,7 +70,7 @@ were not explicitly listed in the approval rules. If you add [Code Owners](../code_owners.md) to your repository, the owners to the corresponding files will become eligible approvers, together with members with Developer -or higher permissions. +or higher [permissions](../../permissions.md). To enable this merge request approval rule: @@ -127,7 +129,7 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- ### Multiple approval rules **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. In GitLab Premium, it is possible to have multiple approval rules per merge request, as well as multiple default approval rules per project. @@ -149,7 +151,7 @@ reduce the number of approvals left for all rules that the approver belongs to. ### Scoped to Protected Branch **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. Approval rules are often only relevant to specific branches, like `master`. When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule) @@ -222,7 +224,7 @@ from the UI. However, approvals will be reset if the target branch is changed. ### Allowing merge request authors to approve their own merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. You can allow merge request authors to self-approve merge requests. Authors also need to be included in the approvers list in order to be able to @@ -234,7 +236,7 @@ approve their merge request. To enable this feature: ### Prevent approval of merge requests by their committers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. You can prevent users that have committed to a merge request from approving it. To enable this feature: @@ -244,7 +246,12 @@ enable this feature: ### Require authentication when approving a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. + +NOTE: **Note:** +To require authentication when approving a merge request, you must enable +**Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). +in the Admin area. You can force the approver to enter a password in order to authenticate before adding the approval. This enables an Electronic Signature for approvals such as the one defined @@ -264,7 +271,7 @@ For more information, see ## Enabling the new approvals interface -Since [GitLab v12.0](https://gitlab.com/gitlab-org/gitlab/issues/10685), an updated approvals +Since [GitLab v12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/10685), an updated approvals interface is available by default. In versions older than 12.0, the updated interface is not available unless the `approval_rules` feature flag is enabled, which can be done from the Rails console by instance administrators. diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 66a1d2ac6af..a1012e27d32 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -4,7 +4,7 @@ type: reference, concepts # Merge Request dependencies **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge Requests dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. > - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. @@ -94,9 +94,9 @@ merge. ## Limitations -- API support: [issue #12551](https://gitlab.com/gitlab-org/gitlab/issues/12551) -- Dependencies are not preserved across project export/import: [issue #12549](https://gitlab.com/gitlab-org/gitlab/issues/12549) -- Complex merge order dependencies are not supported: [issue #11393](https://gitlab.com/gitlab-org/gitlab/issues/11393) +- API support: [issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551) +- Dependencies are not preserved across project export/import: [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549) +- Complex merge order dependencies are not supported: [issue #11393](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) The last item merits a little more explanation. Dependencies between merge requests can be described as a graph of relationships. The simplest possible 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 50412e0b319..d45ccdc9be9 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -59,11 +59,24 @@ merge request from the UI, until you make all relevant jobs pass.  +### Skipped pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. + +When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/README.md#skip-pipeline) prevent +merge requests from being merged. To change this behavior: + +1. Navigate to your project's **Settings > General** page. +1. Expand the **Merge requests** section. +1. In the **Merge checks** subsection, ensure **Pipelines must succeed** is checked. +1. In the **Merge checks** subsection, select the **Skipped pipelines are considered successful** checkbox. +1. Press **Save** for the changes to take effect. + ### Limitations When this setting is enabled, a merge request is prevented from being merged if there is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced) rules are used and they don't generate any pipelines. -Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/issues/54226) and that it's successful. +Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) and that it's successful. For example, to that on merge requests there is always a passing job even though `only/except` rules may not generate any other jobs: 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 fdcb1049ef7..a3ad41d8dd8 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 @@ -82,6 +82,10 @@ to expand the entire file.  +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205401) in GitLab 13.1, when viewing a +merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the +entire content by clicking **Show file contents**. + ### Ignore whitespace changes in Merge Request diff view If you click the **Hide whitespace changes** button, you can see the diff @@ -96,7 +100,7 @@ whitespace changes. ## Perform inline code reviews -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5. +> [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. @@ -108,7 +112,7 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, you will be able to see: -- Both pre and post-merge pipelines and the environment information if any. +- Both pre-merge and post-merge pipelines and the environment information if any. - Which deployments are in progress. If there's an [environment](../../../ci/environments/index.md) and the application is diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 84d60fca72d..1c0e698aba5 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -4,7 +4,7 @@ type: reference, howto # Test Coverage Visualization -> [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. 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 @@ -67,7 +67,7 @@ test: 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 -data sets. When [the performance issue](https://gitlab.com/gitlab-org/gitlab/issues/211410) +data sets. When [the performance issue](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) is resolved, the feature will be enabled by default. To enable this feature, ask a GitLab administrator with Rails console access to diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md new file mode 100644 index 00000000000..f7614ed7996 --- /dev/null +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -0,0 +1,36 @@ +--- +type: index +description: "Test your code and display reports in merge requests" +--- + +# Tests and reports in merge requests + +GitLab has the ability to test the changes included in a feature branch and display reports +or link to useful information directly from merge requests: + +| Feature | Description | +|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | +| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | +| [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | +| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | +| [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | +| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | +| [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | +| [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | +| [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | +| [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | +| [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | +| [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | + +## Security Reports **(ULTIMATE)** + +In addition to the reports listed above, GitLab can do many types of [Security reports](../../application_security/index.md), +generated by scanning and reporting any vulnerabilities found in your project: + +| Feature | Description | +|-----------------------------------------------------------------------------------------|------------------------------------------------------------------| +| [Container Scanning](../../application_security/container_scanning/index.md) | Analyze your Docker images for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](../../application_security/dast/index.md) | Analyze your running web applications for known vulnerabilities. | +| [Dependency Scanning](../../application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | +| [Static Application Security Testing (SAST)](../../application_security/sast/index.md) | Analyze your source code for known vulnerabilities. | diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 84934148bdc..9581c974414 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -37,7 +37,7 @@ changes appears as a system note. ## Find the merge request that introduced a change -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2383) in GitLab 10.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. When viewing the commit details page, GitLab will link to the merge request (or merge requests, if it's in more than one) containing that commit. @@ -48,7 +48,7 @@ request, they will not be linked. ## `HEAD` comparison mode for Merge Requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27008) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) in GitLab 12.10. Merge Requests, particularly the **Changes** tab, is where source code is reviewed and discussed. In circumstances where the target branch was @@ -62,7 +62,7 @@ shows a diff calculated by simulating how it would look like once merged - a mor representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down by selecting **master (HEAD)**. In the future it will -[replace](https://gitlab.com/gitlab-org/gitlab/issues/198458) the +[replace](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the current default comparison.  diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index e9f23899068..e28ba1d2d5f 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,5 +1,8 @@ --- type: reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Burndown Charts **(STARTER)** diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 085c1bd143e..421cb42de1e 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -1,5 +1,8 @@ --- type: index, reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Milestones diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 120c7a35cb2..cfcbf11a407 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,10 +1,17 @@ +--- +stage: Verify +group: Continuous Integration +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 +--- + # New CI job permissions model > Introduced in GitLab 8.12. GitLab 8.12 has a completely redesigned [job permissions](../permissions.md#job-permissions) system. You can find all discussion and all our concerns when choosing the current approach in issue -[#18994](https://gitlab.com/gitlab-org/gitlab-foss/issues/18994). +[#18994](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18994). Jobs permissions should be tightly integrated with the permissions of a user who is triggering a job. @@ -68,7 +75,7 @@ Let's consider the following scenario: A unique job token is generated for each job and provides the user read access all projects that would be normally accessible to the user creating that job. The unique job token does not have any write permissions, but there -is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab/issues/35067). +is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab/-/issues/35067). We try to make sure that this token doesn't leak by: @@ -156,7 +163,7 @@ As an administrator: [check manually](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/update) for installations from source. - **500 errors**: Check if you have another web proxy sitting in front of NGINX (HAProxy, Apache, etc.). It might be a good idea to let GitLab use the internal NGINX - web server and not disable it completely. See [this comment](https://gitlab.com/gitlab-org/gitlab-foss/issues/22484#note_16648302) for an + web server and not disable it completely. See [this comment](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22484#note_16648302) for an example. - **403 errors**: You need to make sure that your installation has [HTTP(S) cloning enabled](../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols). HTTP(S) support is now a **requirement** by GitLab CI @@ -178,7 +185,7 @@ git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependent ``` It can also be used for system-wide authentication -(only do this in a docker container, it will overwrite ~/.netrc): +(only do this in a Docker container, it will overwrite ~/.netrc): ```shell echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 2dcf72aaf01..411b36411af 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Alert Management > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. @@ -32,12 +38,14 @@ immediately identify which alerts you should prioritize investigating: Alerts contain one of the following icons: -- **Critical**: **{severity-critical}** and hexadecimal color `#8b2615` -- **High**: **{severity-high}** and hexadecimal color `#c0341d` -- **Medium**: **{severity-medium}** and hexadecimal color `#fca429` -- **Low**: **{severity-low}** and hexadecimal color `#fdbc60` -- **Info**: **{severity-info}** and hexadecimal color `#418cd8` -- **Unknown**: **{severity-unknown}** and hexadecimal color `#bababa` +| 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 @@ -72,8 +80,91 @@ You will need at least Developer [permissions](../../permissions.md) to view Ale 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 allows users to update the Alert Status. See [Alert Management statuses](#alert-management-statuses) for more details. +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. + +NOTE: **Note:** +GitLab currently only supports creating system notes when assigning an Alert. + +Assigning a user an Alert creates a system note, visible in the Alert Details view, +giving you a linear timeline of the alert's investigation and assignment history. + + + +## 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. diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md new file mode 100644 index 00000000000..e14c478ab7a --- /dev/null +++ b/doc/user/project/operations/dashboard_settings.md @@ -0,0 +1,47 @@ +--- +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 +--- + +# 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. + +## 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. 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. 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: + + diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 23a50fd7766..a7a16de90e0 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -61,7 +61,7 @@ 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. +- 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: @@ -77,7 +77,7 @@ 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. +> [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. @@ -85,7 +85,7 @@ Ignoring an error will prevent it from appearing in the [Error Tracking List](#e ### Resolving errors -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/39825) in GitLab 12.7. +> [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. diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 8716d5feb4a..a9729204cd7 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -8,100 +8,73 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. -Feature flags allow you to ship a project in different flavors by -dynamically toggling certain functionality. +With Feature Flags, you can deploy your application's new features to production in smaller batches. +You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery. +Feature flags help reduce risk, allowing you to do controlled testing, and separate feature +delivery from customer launch. -## Overview - -Feature Flags offer a feature toggle system for your application. They enable teams -to achieve Continuous Delivery by deploying new features to production at smaller -batches for controlled testing, separating feature delivery from customer launch. -This helps reducing risk and allows you to easily manage which features to enable. - -GitLab offers a Feature Flags interface that allows you to create, toggle and -remove feature flags. - -<div class="video-fallback"> - <a href="https://www.youtube.com/watch?v=5tw2p6lwXxo">Watch</a> a use case between Feature Flags and Sentry Error Tracking -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/5tw2p6lwXxo" frameborder="0" allowfullscreen="true"> </iframe> -</figure> +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo). ## How it works -Underneath, GitLab uses [unleash](https://github.com/Unleash/unleash), a feature -toggle service. GitLab provides an API where your application can talk to and get the -list of feature flags you set in GitLab. +GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature +toggle service. -The application must be configured to talk to GitLab, so that's up to the -developers to use a compatible [client library](#client-libraries) and -integrate it in their app. +By enabling or disabling a flag in GitLab, your application +can determine which features to enable or disable. -By setting a flag active or inactive via GitLab, your application will automatically -know which features to enable or disable respectively. +You can create feature flags in GitLab and use the API from your application +to get the list of feature flags and their statuses. The application must be configured to communicate +with GitLab, so it's up to developers to use a compatible client library and +[integrate the feature flags in your app](#integrate-feature-flags-with-your-application). -## Adding a new feature flag +## Create a feature flag -To add a new feature flag: +To create and enable a feature flag: 1. Navigate to your project's **Operations > Feature Flags**. -1. Click on the **New Feature Flag** button. -1. Give it a name. - - NOTE: **Note:** - A name can contain only lowercase letters, digits, underscores (`_`) - and dashes (`-`), must start with a letter, and cannot end with a dash (`-`) - or an underscore (`_`). - -1. Give it a description (optional, 255 characters max). -1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs) +1. Click the **New feature flag** button. +1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`) + and dashes (`-`), and does not end with a dash (`-`) or underscore (`_`). +1. Enter a description (optional, 255 characters max). +1. Enter details about how the flag should be applied: + - In GitLab 13.0 and earlier: Enter an environment spec, + enable or disable the flag in this environment, and select a rollout strategy. + - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is enabled): Select a strategy and then + the environments to apply the strategy to. 1. Click **Create feature flag**. -Once a feature flag is created, the list of existing feature flags will be presented -with ability to edit or remove them. - -To make a feature flag active or inactive, click the pencil icon to edit it, -and toggle the status for each [spec](#define-environment-specs). +The feature flag is displayed in the list. It is enabled by default. -The toggles next to each feature flag on the list page function as global shutoff switches. -If a toggle is off, that feature flag is disabled for every environment. +## Disable a feature flag for a specific environment - +In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621), +to disable a feature flag for a specific environment: -## Define environment specs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8621) in GitLab 11.8. - -In general, an application is deployed to multiple environments, such as -production, staging and [review apps](../../../ci/review_apps/index.md). -For example, you may not want to enable a feature flag on production until your QA team has -first confirmed that the feature is working correctly on testing environments. +1. Navigate to your project's **Operations > Feature Flags**. +1. For the feature flag you want to disable, click the Pencil icon. +1. To disable the flag: + - In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the + environment spec, on the right, click the **Remove (X)** icon. + - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is + enabled): For each strategy it applies to, under **Environments**, delete the environment. +1. Click **Save changes**. -To handle these situations, you can enable a feature flag on a particular environment -with [Environment specs](../../../ci/environments/index.md#scoping-environments-with-specs). -You can define multiple specs per flag so that you can control your feature flag more granularly. +## Disable a feature flag for all environments -To define specs for each environment: +To disable a feature flag for all environments: 1. Navigate to your project's **Operations > Feature Flags**. -1. Click on the **New Feature Flag** button or edit an existing flag. -1. Set the status of the default [spec](../../../ci/environments/index.md#scoping-environments-with-specs) (`*`). Choose a rollout strategy. This status and rollout strategy combination will be used for _all_ environments. -1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments/index.md#scoping-environments-with-specs) and type the environment name. -1. Set the status and rollout strategy of the additional spec. This status and rollout strategy combination takes precedence over the default spec since we always use the most specific match available. -1. Click **Create feature flag** or **Update feature flag**. +1. For the feature flag you want to disable, slide the Status toggle to **Disabled**. - - -NOTE: **NOTE** -We'd highly recommend you to use the [Environment](../../../ci/environments/index.md) -feature in order to quickly assess which flag is enabled per environment. +The feature flag is displayed on the **Disabled** tab. ## Feature flag behavior change in 13.0 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0. -Starting in GitLab 13.0, you can apply a feature flag strategy across multiple environment specs, +Starting in GitLab 13.0, you can apply a feature flag strategy across multiple environments, without defining the strategy multiple times. This feature is under development and not ready for production use. It is @@ -121,29 +94,18 @@ To disable it: Feature.disable(:feature_flags_new_version) ``` -### Applying a strategy to environments - -After a strategy is defined, it applies to **All Environments** by default. To -make a strategy apply to a specific environment spec: +## Feature flag strategies -1. Click the **Add Environment** button. -1. Create a new - [spec](../../../ci/environments/index.md#scoping-environments-with-specs). - -To apply the strategy to multiple environment specs, repeat these steps. - -## Feature Flag strategies - -GitLab Feature Flag adopts [Unleash](https://unleash.github.io) -as the feature flag engine. In unleash, there is a concept of rulesets for granular feature flag controls, +GitLab Feature Flag uses [Unleash](https://unleash.github.io) +as the feature flag engine. In Unleash, there is a concept of rulesets for granular feature flag controls, called [strategies](https://unleash.github.io/docs/activation_strategy). Supported strategies for GitLab Feature Flags are described below. ### Rollout strategy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. -The selected rollout strategy affects which users will experience the feature enabled. +The selected rollout strategy affects which users will experience the feature as enabled. The status of an environment spec ultimately determines whether or not a feature is enabled at all. For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy. @@ -172,36 +134,34 @@ ID for the feature to be enabled. See the [Ruby example](#ruby-application-examp #### User IDs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/issues/34363) to be defined per environment in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6. A feature flag may be enabled for a list of target users. It is implemented using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid) activation strategy. -User IDs should be a comma separated list of values. For example, `user@example.com, user2@example.com`, or `username1,username2,username3`, etc. +User IDs should be a comma-separated list of values. For example, `user@example.com, user2@example.com`, or `username1,username2,username3`, etc. CAUTION: **Caution:** The Unleash client **must** be given a user ID for the feature to be enabled for target users. See the [Ruby example](#ruby-application-example) below. -## Integrating with your application +## Integrate feature flags with your application -In order to use Feature Flags, you need to first -[get the access credentials](#configuring-feature-flags) from GitLab and then -prepare your application and hook it with a [client library](#client-libraries). +To use feature flags with your application, get access credentials from GitLab. +Then prepare your application with a client library. -## Configuring Feature Flags +### Get access credentials -To get the access credentials that your application will need to talk to GitLab: +To get the access credentials that your application needs to communicate with GitLab: 1. Navigate to your project's **Operations > Feature Flags**. -1. Click on the **Configure** button to see the values: +1. Click the **Configure** button to view the following: - **API URL**: URL where the client (application) connects to get a list of feature flags. - **Instance ID**: Unique token that authorizes the retrieval of the feature flags. - **Application name**: The name of the running environment. For instance, - if the application runs for a production server, application name would be - `production` or similar. This value is used for - [the environment spec evaluation](#define-environment-specs). + if the application runs for a production server, the application name would be + `production` or similar. This value is used for the environment spec evaluation. NOTE: **Note:** The meaning of these fields might change over time. For example, we are not sure @@ -209,34 +169,28 @@ if **Instance ID** will be single token or multiple tokens, assigned to the **Environment**. Also, **Application name** could describe the version of application instead of the running environment. -## Client libraries +### Choose a client library -GitLab currently implements a single backend that is compatible with -[Unleash](https://github.com/Unleash/unleash#client-implementations) clients. +GitLab implements a single backend that is compatible with Unleash clients. -Unleash clients allow the developers to define in the app's code the default -values for flags. Each feature flag evaluation can express the desired -outcome in case the flag isn't present on the provided configuration file. +With the Unleash client, developers can define, in the application code, the default values for flags. +Each feature flag evaluation can express the desired outcome if the flag isn't present in the +provided configuration file. -Unleash currently offers a number of official SDKs for various frameworks and -a number of community contributed libraries. +Unleash currently [offers many SDKs for various languages and frameworks](https://github.com/Unleash/unleash#client-implementations). -Official clients: +### Feature flags API information -- [Unleash client SDK for Java](https://github.com/unleash/unleash-client-java) -- [Unleash client SDK for Node.js](https://github.com/unleash/unleash-client-node) -- [Unleash client for Go](https://github.com/unleash/unleash-client-go) -- [Unleash client for Ruby](https://github.com/unleash/unleash-client-ruby) +For API content, see: -Community contributed clients: - -- [Unleash FeatureToggle Client for .Net](https://github.com/stiano/unleash-client-dotnet) -- [Unofficial .Net Core Unleash client](https://github.com/onybo/unleash-client-core) -- [Unleash client for Python 3](https://github.com/aes/unleash-client-python) +- [Feature Flags API](../../../api/feature_flags.md) +- [Feature Flag Specs API](../../../api/feature_flag_specs.md) (Deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369).) +- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.md) +- [Legacy Feature Flags API](../../../api/feature_flags_legacy.md) -## Golang application example +### Golang application example -Here's an example of how to integrate the feature flags in a Golang application: +Here's an example of how to integrate feature flags in a Golang application: ```golang package main @@ -275,9 +229,9 @@ func main() { } ``` -## Ruby application example +### Ruby application example -Here's an example of how to integrate the feature flags in a Ruby application. +Here's an example of how to integrate feature flags in a Ruby application. The Unleash client is given a user ID for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**. @@ -305,12 +259,3 @@ else puts "hello, world!" end ``` - -## Feature Flags API - -You can create, update, read, and delete Feature Flags via API -to control them in an automated flow: - -- [Feature Flags API](../../../api/feature_flags.md) -- [Feature Flag Specs API](../../../api/feature_flag_specs.md) -- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.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 differnew file mode 100644 index 00000000000..18a6f4fb67b --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_full_v13_1.png 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 differnew file mode 100644 index 00000000000..10c945d3810 --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_overview_v13_1.png 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 differnew file mode 100644 index 00000000000..2a6d0320a54 --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_system_notes_v13_1.png diff --git a/doc/user/project/operations/img/alert_detail_v13_0.png b/doc/user/project/operations/img/alert_detail_v13_0.png Binary files differdeleted file mode 100644 index 7da09407cd5..00000000000 --- a/doc/user/project/operations/img/alert_detail_v13_0.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 differnew file mode 100644 index 00000000000..dab4eac384a --- /dev/null +++ b/doc/user/project/operations/img/alert_details_assignees_v13_1.png diff --git a/doc/user/project/operations/img/alert_issue_v13_1.png b/doc/user/project/operations/img/alert_issue_v13_1.png Binary files differnew file mode 100644 index 00000000000..da79074aa2f --- /dev/null +++ b/doc/user/project/operations/img/alert_issue_v13_1.png 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 differnew file mode 100644 index 00000000000..db1e0d8dcb7 --- /dev/null +++ b/doc/user/project/operations/img/alert_list_assignees_v13_1.png diff --git a/doc/user/project/operations/img/alert_management_1_v13_1.png b/doc/user/project/operations/img/alert_management_1_v13_1.png Binary files differindex c01b4749eda..00aa56a6050 100644 --- a/doc/user/project/operations/img/alert_management_1_v13_1.png +++ b/doc/user/project/operations/img/alert_management_1_v13_1.png 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 differnew file mode 100644 index 00000000000..637f8be5d25 --- /dev/null +++ b/doc/user/project/operations/img/alert_todo_assignees_v13_1.png 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 differnew file mode 100644 index 00000000000..3e8d792c53e --- /dev/null +++ b/doc/user/project/operations/img/dashboard_external_link_v13_1.png 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 differnew file mode 100644 index 00000000000..8d45607a940 --- /dev/null +++ b/doc/user/project/operations/img/dashboard_local_timezone_v13_1.png diff --git a/doc/user/project/operations/img/external_dashboard_settings.png b/doc/user/project/operations/img/external_dashboard_settings.png Binary files differdeleted file mode 100644 index e1b7fa56a1c..00000000000 --- a/doc/user/project/operations/img/external_dashboard_settings.png +++ /dev/null diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index 954f88fe4f2..ca38eab9455 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -10,4 +10,4 @@ your applications: - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). - Create, toggle, and remove [Feature Flags](feature_flags.md). **(PREMIUM)** - [Trace](tracing.md) the performance and health of a deployed application. **(ULTIMATE)** -- Add a [button to the Monitoring dashboard](linking_to_an_external_dashboard.md) linking directly to your existing external dashboards. +- Change the [settings of the Monitoring Dashboard](dashboard_settings.md). 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 8e1117de4c7..ff609a3720e 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -1,19 +1,5 @@ -# Linking to an external dashboard +--- +redirect_to: 'dashboard_settings.md' +--- -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/57171) in GitLab 12.0. - -You can add a button to the Monitoring dashboard linking directly to your existing external dashboards. - -## Enabling the external dashboard link - -1. Go to **Settings > Operations** and scroll to the section titled **External dashboard**. - -1. Fill in the URL to your external dashboard and click **Save changes**. - -  - -1. There should now be a button on your - [Monitoring dashboard](../../../ci/environments/index.md#monitoring-environments) which - will open the URL you entered in the above step. - -  +This document was moved to [another location](dashboard_settings.md). 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 a5fc5b00b53..bf9b58acf14 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 @@ -273,7 +273,7 @@ Sublime Text, Atom, Dreamweaver, Brackets, etc). ## Force HTTPS for GitLab Pages websites -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28857) in GitLab 10.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28857) in GitLab 10.7. To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your @@ -287,6 +287,9 @@ To enable this setting: 1. Navigate to your project's **Settings > Pages**. 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). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 8b180d438ef..4b4b430b663 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages integration with Let's Encrypt -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). The GitLab Pages integration with Let's Encrypt (LE) allows you to use LE certificates for your Pages website with custom domains @@ -19,7 +19,7 @@ GitLab does it for you, out-of-the-box. open source Certificate Authority. CAUTION: **Caution:** -This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). ## Requirements diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index 00cea846f91..de9bd97b262 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -5,68 +5,52 @@ group: Release 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 --- -# New Pages website from a forked sample - -To get started with GitLab Pages from a sample website, the easiest -way to do it is by using one of the [bundled templates](pages_bundled_template.md). -If you don't find one that suits your needs, you can opt by -forking (copying) a [sample project from the most popular Static Site Generators](https://gitlab.com/pages). - -<table class="borderless-table center fixed-table middle width-80"> - <tr> - <td style="width: 30%"><img src="../img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="../img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="../img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> - </tr> - <tr> - <td><em>Fork an example project</em></td> - <td></td> - <td><em>Deploy your website</em></td> - <td></td> - <td><em>Visit your website's URL</em></td> - </tr> -</table> - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** - -1. [Fork](../../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. Once the pipeline has finished successfully, find the link to visit your - website from your project's **Settings > Pages**. It can take approximately - 30 minutes to be deployed. - -You can also take some **optional** further steps: - -- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: - -  - -- _Make it a user or group website._ To turn a **project website** forked - from the Pages group into a **user/group** website, you'll need to: - - Rename it to `namespace.gitlab.io`: go to your project's - **Settings > General** and expand **Advanced**. Scroll down to - **Change path** and change the path to `namespace.gitlab.io`. - - For example, consider the group `https://gitlab.com/gitlab-tests`: - `gitlab-tests` is the group's namespace, the repository path should be set - to `gitlab-tests.gitlab.io` (yes, weird like that), and the - resulting URL for your Pages website will be `https://gitlab-tests.gitlab.io`. +# Create a Pages website from a forked sample + +GitLab provides [sample projects for the most popular Static Site Generators](https://gitlab.com/pages). +You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. + +Fork a sample project when you want to test GitLab Pages or start a new project that's already +configured to generate a Pages site. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) of how this works. + +To fork a sample project and create a Pages website: + +1. View the sample projects by going to the [GitLab Pages examples](https://gitlab.com/pages) group. +1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). +1. In the top right, click the **Fork** button, and then choose a namespace to fork to. +1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. + GitLab CI/CD builds and deploys your site. + +The site can take approximately 30 minutes to deploy. +When the pipeline is finished, go to **Settings > Pages** to find the link to your website from your project. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. + +You can take some **optional** further steps: + +- _Remove the fork relationship._ If you want to contribute to the project you forked from, + you can keep this relationship. Otherwise, go to your project's **Settings > General**, + expand **Advanced settings**, and scroll down to **Remove fork relationship**: + +  + +- _Change the URL to match your namespace._ If your Pages site is hosted on GitLab.com, + you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace + (the one you chose when you forked the project). + + - Go to your project's **Settings > General** and expand **Advanced**. Scroll down to + **Change path** and change the path to `<namespace>.gitlab.io`. + + For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is + `gitlab-tests`. + + If you set the repository path to `gitlab-tests.gitlab.io`, + the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`.  - - Adjust your SSG's [base URL](../getting_started_part_one.md#urls-and-baseurls) from `"project-name"` to - `""`. This setting will be at a different place for each SSG, as each of them - have their own structure and file tree. Most likely, it will be in the SSG's - config file. + - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) + from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the config file. diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md index 9a00b724753..5d7126ab22e 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -5,44 +5,45 @@ group: Release 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 --- -# Start a new Pages website from scratch or deploy an existing website +# Create a Pages website by using a CI/CD template -If you already have a website and want to deploy it with GitLab Pages, -or, if you want to start a new site from scratch, you'll need to: +GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). +You can create your own `.gitlab-ci.yml` file from one of these templates, and run +the CI/CD pipeline to generate a Pages website. -- Create a new project in GitLab to hold your site content. -- Set up GitLab CI/CD to deploy your website to Pages. +Use a `.gitlab-ci.yml` template when you have an existing project that you want to add a Pages site to. -To do so, follow the steps below. +Your GitLab repository should contain files specific to an SSG, or plain HTML. +After you complete these steps, you may need to do additional +configuration for the Pages site to generate properly. -1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, - click **New project**, and name it according to the - [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names). -1. Clone it to your local computer, add your website - files to your project, add, commit, and push to GitLab. - Alternatively, you can run `git init` in your local directory, - add the remote URL: - `git remote add origin git@gitlab.com:namespace/project-name.git`, - then add, commit, and push to GitLab. -1. From the your **Project**'s page, click **Set up CI/CD**: +1. In the left sidebar, click **Project overview**. +1. Click **Set up CI/CD**. -  +  -1. Choose one of the templates from the dropbox menu. - Pick up the template corresponding to the SSG you're using (or plain HTML). + If this button is not available, CI/CD is already configured for + your project. You may want to browse the `.gitlab-ci.yml` files + [in these projects instead](https://gitlab.com/pages). -  +1. From the **Apply a template** list, choose a template for the SSG you're using. + You can also choose plain HTML. - Note that, if you don't find a corresponding template, you can look into - [GitLab Pages group of sample projects](https://gitlab.com/pages), - you may find one among them that suits your needs, from which you - can copy `.gitlab-ci.yml`'s content and adjust for your case. - If you don't find it there either, [learn how to write a `.gitlab-ci.yml` +  + + If you don't find a corresponding template, you can view the + [GitLab Pages group of sample projects](https://gitlab.com/pages). + These projects contain `.gitlab-ci.yml` files that you can modify for your needs. + You can also [learn how to write your own `.gitlab-ci.yml` file for GitLab Pages](../getting_started_part_four.md). -Once you have both site files and `.gitlab-ci.yml` in your project's -root, GitLab CI/CD will build your site and deploy it with Pages. -Once the first build passes, you access your site by -navigating to your **Project**'s **Settings** > **Pages**, -where you'll find its default URL. It can take approximately 30 min to be -deployed. +1. Save and commit the `.gitlab-ci.yml` file. + +If everything is configured correctly, the site can take approximately 30 minutes to deploy. + +You can watch the pipeline run by going to **CI / CD > Pipelines**. +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index 745c50e8d65..cfa4e0910db 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -5,27 +5,30 @@ group: Release 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 --- -# New Pages website from a bundled template +# Create a Pages website from a new project template -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) in GitLab 11.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. -The simplest way to create a GitLab Pages site is to use one of the most -popular templates, which come already bundled with GitLab and are ready to go. +GitLab provides templates for the most popular Static Site Generators (SSGs). +You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. + +Use a template when you want to test GitLab Pages or start a new project that's already +configured to generate a Pages site. 1. From the top navigation, click the **+** button and select **New project**. 1. Select **Create from Template**. -1. Choose one of the templates starting with **Pages**: +1. Next to one of the templates starting with **Pages**, click **Use template**. -  +  +1. Complete the form and click **Create project**. 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. After the pipeline has finished successfully, wait approximately 30 minutes - for your website to be visible. After waiting 30 minutes, find the link to - visit your website from your project's **Settings > Pages**. If the link - leads to a 404 page, wait a few minutes and try again. - -Your website is then visible on your domain and you can modify your files -as you wish. For every modification pushed to your repository, GitLab CI/CD -will run a new pipeline to immediately publish your changes to the server. + site. + +The site can take approximately 30 minutes to deploy. +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 4e95b5d5a69..8cf58280b88 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -6,137 +6,146 @@ group: Release 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 --- -# Creating and Tweaking GitLab CI/CD for GitLab Pages - -To [get started with GitLab Pages](index.md#getting-started), you can -use one of the project templates, a `.gitlab-ci.yml` template, -or fork an existing example project. Therefore, you don't need to -understand _all_ the ins and odds of GitLab CI/CD to get your site -deployed. Still, there are cases where you want to write your own -script or tweak an existing one. This document guides you through -this process. - -This guide also provides a general overview and clear introduction -for **getting familiar with the `.gitlab-ci.yml` file and writing -one for the first time.** - -[GitLab CI/CD](../../../ci/README.md) serves -numerous purposes, to build, test, and deploy your app -from GitLab through -[Continuous Integration, Continuous Delivery, and Continuous Deployment](../../../ci/introduction/index.md#introduction-to-cicd-methodologies) -methods. You will need it to build your website with GitLab Pages, -and deploy it to the Pages server. - -To implement GitLab CI/CD, the first thing you need is a configuration -file called `.gitlab-ci.yml` placed at your website's root directory. - -What this file actually does is telling the -[GitLab Runner](https://docs.gitlab.com/runner/) to run scripts -as you would do from the command line. The Runner acts as your -terminal. GitLab CI/CD tells the Runner which commands to run. -Both are built-in in GitLab, and you don't need to set up -anything for them to work. - -Explaining [every detail of GitLab CI/CD](../../../ci/yaml/README.md) -and GitLab Runner is out of the scope of this guide, but we'll -need to understand just a few things to be able to write our own -`.gitlab-ci.yml` or tweak an existing one. It's a -[YAML](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) file, -with its own syntax. You can always check your CI syntax with -the [GitLab CI/CD Lint Tool](https://gitlab.com/ci/lint). - -## Practical example - -Let's consider you have a [Jekyll](https://jekyllrb.com/) site. -To build it locally, you would open your terminal, and run `jekyll build`. -Of course, before building it, you had to install Jekyll in your computer. -For that, you had to open your terminal and run `gem install jekyll`. -Right? GitLab CI/CD + GitLab Runner do the same thing. But you need to -write in the `.gitlab-ci.yml` the script you want to run so -GitLab Runner will do it for you. It looks more complicated than it -is. What you need to tell the Runner: - -```shell -gem install jekyll -jekyll build +# Create a GitLab Pages website from scratch + +This tutorial shows you how to create a Pages site from scratch. You will start with +a blank project and create your own CI file, which gives instruction to the +[GitLab Runner](https://docs.gitlab.com/runner/). When your CI/CD +[pipeline](../../../ci/pipelines/index.md) runs, the Pages site is created. + +This example uses the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). +Other SSGs follow similar steps. You do not need to be familiar with Jekyll or SSGs +to complete this tutorial. + +## Prerequisites + +To follow along with this example, start with a blank project in GitLab. +Create three files in the root (top-level) directory. + +- `.gitlab-ci.yml` A YAML file that contains the commands you want to run. + For now, leave the file's contents blank. + +- `index.html` An HTML file you can populate with whatever HTML content you'd like, + for example: + + ```html + <html> + <head> + <title>Home</title> + </head> + <body> + <h1>Hello World!</h1> + </body> + </html> + ``` + +- [`Gemfile`](https://bundler.io/gemfile.html) A file that describes dependencies for Ruby programs. + Populate it with this content: + + ```ruby + source "https://rubygems.org" + + gem "jekyll" + ``` + +## Choose a Docker image + +In this example, the Runner uses a [Docker image](../../../ci/docker/using_docker_images.md) +to run scripts and deploy the site. + +This specific Ruby image is maintained on [DockerHub](https://hub.docker.com/_/ruby). + +Edit your `.gitlab-ci.yml` and add this text as the first line. + +```yaml +image: ruby:2.7 ``` -### Script +If your SSG needs [NodeJS](https://nodejs.org/) to build, you must specify an +image that contains NodeJS as part of its file system. For example, for a +[Hexo](https://gitlab.com/pages/hexo) site, you can use `image: node:12.17.0`. + +## Install Jekyll + +To run [Jekyll](https://jekyllrb.com/) locally, you would open your terminal and: -To transpose this script to YAML, it would be like this: +- Install [Bundler](https://bundler.io/) by running `gem install bundler`. +- Create `Gemfile.lock` by running `bundle install`. +- Install Jekyll by running `bundle exec jekyll build`. + +In the `.gitlab-ci.yml` file, this is written as: ```yaml script: - - gem install jekyll - - jekyll build + - gem install bundler + - bundle install + - bundle exec jekyll build ``` -### Job - -So far so good. Now, each `script`, in GitLab is organized by -a `job`, which is a bunch of scripts and settings you want to -apply to that specific task. +In addition, in the `.gitlab-ci.yml` file, each `script` is organized by a `job`. +A `job` includes the scripts and settings you want to apply to that specific +task. ```yaml job: script: - - gem install jekyll - - jekyll build + - gem install bundler + - bundle install + - bundle exec jekyll build ``` -For GitLab Pages, this `job` has a specific name, called `pages`, -which tells the Runner you want that task to deploy your website +For GitLab Pages, this `job` has a specific name, called `pages`. +This setting tells the Runner you want the job to deploy your website with GitLab Pages: ```yaml pages: script: - - gem install jekyll - - jekyll build + - gem install bundler + - bundle install + - bundle exec jekyll build ``` -### The `public` directory +## Specify the `public` directory for output + +Jekyll needs to know where to generate its output. +GitLab Pages only considers files in a directory called `public`. -We also need to tell Jekyll where do you want the website to build, -and GitLab Pages will only consider files in a directory called `public`. -To do that with Jekyll, we need to add a flag specifying the -[destination (`-d`)](https://jekyllrb.com/docs/usage/) of the -built website: `jekyll build -d public`. Of course, we need -to tell this to our Runner: +Jekyll uses destination (`-d`) to specify an output directory for the built website: ```yaml pages: script: - - gem install jekyll - - jekyll build -d public + - gem install bundler + - bundle install + - bundle exec jekyll build -d public ``` -### Artifacts +## Specify the `public` directory for artifacts -We also need to tell the Runner that this _job_ generates -_artifacts_, which is the site built by Jekyll. -Where are these artifacts stored? In the `public` directory: +Now that Jekyll has output the files to the `public` directory, +the Runner needs to know where to get them. The artifacts are stored +in the `public` directory: ```yaml pages: script: - - gem install jekyll - - jekyll build -d public + - gem install bundler + - bundle install + - bundle exec jekyll build -d public artifacts: paths: - public ``` -The script above would be enough to build your Jekyll -site with GitLab Pages. But, from Jekyll 3.4.0 on, its default -template originated by `jekyll new project` requires -[Bundler](https://bundler.io) to install Jekyll dependencies -and the default theme. To adjust our script to meet these new -requirements, we only need to install and build Jekyll with Bundler: +Paste this into `.gitlab-ci.yml` file, so it now looks like this: ```yaml +image: ruby:2.7 + pages: script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: @@ -144,27 +153,35 @@ pages: - public ``` -That's it! A `.gitlab-ci.yml` with the content above would deploy -your Jekyll 3.4.0 site with GitLab Pages. This is the minimum -configuration for our example. On the steps below, we'll refine -the script by adding extra options to our GitLab CI/CD. +Now save and commit the `.gitlab-ci.yml` file. You can watch the pipeline run +by going to **CI / CD > Pipelines**. + +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](https://gitlab.com/ci/lint). + +The following topics show other examples of other options you can add to your CI/CD file. -Artifacts will be automatically deleted once GitLab Pages got deployed. -You can preserve artifacts for limited time by specifying the expiry time. +## Deploy specific branches to a Pages site -### Image +You may want to deploy to a Pages site only from specific branches. -At this point, you probably ask yourself: "okay, but to install Jekyll -I need Ruby. Where is Ruby on that script?". The answer is simple: the -first thing GitLab Runner will look for in your `.gitlab-ci.yml` is a -[Docker](https://www.docker.com/) image specifying what do you need in -your container to run that script: +First, add a `workflow` section to force the pipeline to run only when changes are +pushed to branches: ```yaml image: ruby:2.7 +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + pages: script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: @@ -172,134 +189,122 @@ pages: - public ``` -In this case, you're telling the Runner to pull this image, which -contains Ruby 2.7 as part of its file system. When you don't specify -this image in your configuration, the Runner will use a default -image, which is Ruby 2.6. - -If your SSG needs [NodeJS](https://nodejs.org/) to build, you'll -need to specify which image you want to use, and this image should -contain NodeJS as part of its file system. E.g., for a -[Hexo](https://gitlab.com/pages/hexo) site, you can use `image: node:4.2.2`. - ->**Note:** -We're not trying to explain what a Docker image is, -we just need to introduce the concept with a minimum viable -explanation. To know more about Docker images, please visit -their website or take a look at a -[summarized explanation](http://paislee.io/how-to-automate-docker-deployments/) here. - -Let's go a little further. - -### Branching - -If you use GitLab as a version control platform, you will have your -branching strategy to work on your project. Meaning, you will have -other branches in your project, but you'll want only pushes to the -default branch (usually `master`) to be deployed to your website. -To do that, we need to add another line to our CI, telling the Runner -to only perform that _job_ called `pages` on the `master` branch `only`: +Then configure the pipeline to run the job for the master branch only. ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' pages: script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' ``` -### Stages +## Specify a stage to deploy -Another interesting concept to keep in mind are build stages. -Your web app can pass through a lot of tests and other tasks -until it's deployed to staging or production environments. -There are three default stages on GitLab CI/CD: build, test, -and deploy. To specify which stage your _job_ is running, -simply add another line to your CI: +There are three default stages for GitLab CI/CD: build, test, +and deploy. + +If you want to test your script and check the built site before deploying +to production, you can run the test exactly as it will run when you +push to `master`. + +To specify a stage for your job to run in, +add a `stage` line to your CI file: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' pages: stage: deploy script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' ``` -You might ask yourself: "why should I bother with stages -at all?" Well, let's say you want to be able to test your -script and check the built site before deploying your site -to production. You want to run the test exactly as your -script will do when you push to `master`. It's simple, -let's add another task (_job_) to our CI, telling it to -test every push to other branches, `except` the `master` branch: +Now add another job to the CI file, telling it to +test every push to every branch **except** the `master` branch: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' pages: stage: deploy script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' test: stage: test script: + - gem install bundler - bundle install - bundle exec jekyll build -d test artifacts: paths: - test - except: - - master + rules: + - if: '$CI_COMMIT_BRANCH != "master"' ``` -The `test` job is running on the stage `test`, Jekyll -will build the site in a directory called `test`, and -this job will affect all the branches except `master`. - -The best benefit of applying _stages_ to different -_jobs_ is that every job in the same stage builds in -parallel. So, if your web app needs more than one test -before being deployed, you can run all your test at the -same time, it's not necessary to wait one test to finish -to run the other. Of course, this is just a brief -introduction of GitLab CI/CD and GitLab Runner, which are -tools much more powerful than that. This is what you -need to be able to create and tweak your builds for -your GitLab Pages site. - -### Before Script - -To avoid running the same script multiple times across -your _jobs_, you can add the parameter `before_script`, -in which you specify which commands you want to run for -every single _job_. In our example, notice that we run -`bundle install` for both jobs, `pages` and `test`. -We don't need to repeat it: +When the `test` job runs in the `test` stage, Jekyll +builds the site in a directory called `test`. The job affects +all branches except `master`. + +When you apply stages to different jobs, every job in the same +stage builds in parallel. If your web application needs more than +one test before being deployed, you can run all your tests at the +same time. + +## Remove duplicate commands + +To avoid duplicating the same scripts in every job, you can add them +to a `before_script` section. + +In the example, `gem install bundler` and `bundle install` were running +for both jobs, `pages` and `test`. + +Move these commands to a `before_script` section: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' before_script: + - gem install bundler - bundle install pages: @@ -309,8 +314,8 @@ pages: artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' test: stage: test @@ -319,26 +324,31 @@ test: artifacts: paths: - test - except: - - master + rules: + - if: '$CI_COMMIT_BRANCH != "master"' ``` -### Caching Dependencies +## Build faster with cached dependencies + +To build faster, you can cache the installation files for your +project's dependencies by using the `cache` parameter. -If you want to cache the installation files for your -projects dependencies, for building faster, you can -use the parameter `cache`. For this example, we'll -cache Jekyll dependencies in a `vendor` directory -when we run `bundle install`: +This example caches Jekyll dependencies in a `vendor` directory +when you run `bundle install`: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' cache: paths: - vendor/ before_script: + - gem install bundler - bundle install --path vendor pages: @@ -348,8 +358,8 @@ pages: artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' test: stage: test @@ -358,40 +368,35 @@ test: artifacts: paths: - test - except: - - master + rules: + - if: '$CI_COMMIT_BRANCH != "master"' ``` -For this specific case, we need to exclude `/vendor` -from Jekyll `_config.yml` file, otherwise Jekyll will -understand it as a regular directory to build -together with the site: +In this case, you need to exclude the `/vendor` +directory from the list of folders Jekyll builds. Otherwise, Jekyll +will try to build the directory contents along with the site. + +In the root directory, create a file called `_config.yml` +and add this content: ```yaml exclude: - vendor ``` -There we go! Now our GitLab CI/CD not only builds our website, -but also **continuously test** pushes to feature-branches, +Now GitLab CI/CD not only builds the website, +but also pushes with **continuous tests** to feature-branches, **caches** dependencies installed with Bundler, and -**continuously deploy** every push to the `master` branch. +**continuously deploys** every push to the `master` branch. -## Advanced GitLab CI for GitLab Pages +## Related topics -What you can do with GitLab CI/CD is pretty much up to your -creativity. Once you get used to it, you start creating -awesome scripts that automate most of tasks you'd do -manually in the past. Read through the -[documentation of GitLab CI/CD](../../../ci/yaml/README.md) -to understand how to go even further on your scripts. +For more information, see the following blog posts. -- On this blog post, understand the concept of - [using GitLab CI/CD `environments` to deploy your +- [Use GitLab CI/CD `environments` to deploy your web app to staging and production](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/). -- On this post, learn [how to run jobs sequentially, - in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/) -- On this blog post, we go through the process of - [pulling specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) - to deploy this website you're looking at, <https://docs.gitlab.com>. -- On this blog post, we teach you [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). +- Learn [how to run jobs sequentially, + in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). +- Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + to deploy this website, <https://docs.gitlab.com>. +- Learn [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). 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 7ca09bd21a3..9b5c17f1dda 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.png b/doc/user/project/pages/img/choose_ci_template.png Binary files differdeleted file mode 100644 index 0697542abc8..00000000000 --- a/doc/user/project/pages/img/choose_ci_template.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..84dd9fe2e0f --- /dev/null +++ b/doc/user/project/pages/img/choose_ci_template_v13_1.png diff --git a/doc/user/project/pages/img/pages_project_templates_v11_8.png b/doc/user/project/pages/img/pages_project_templates_v11_8.png Binary files differdeleted file mode 100644 index 61cae88b5a8..00000000000 --- a/doc/user/project/pages/img/pages_project_templates_v11_8.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..3f6d1ecd786 --- /dev/null +++ b/doc/user/project/pages/img/pages_project_templates_v13_1.png diff --git a/doc/user/project/pages/img/remove_fork_relationship.png b/doc/user/project/pages/img/remove_fork_relationship.png Binary files differdeleted file mode 100644 index 67c45491f08..00000000000 --- a/doc/user/project/pages/img/remove_fork_relationship.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..1bc7bcd253b --- /dev/null +++ b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png diff --git a/doc/user/project/pages/img/setup_ci.png b/doc/user/project/pages/img/setup_ci.png Binary files differdeleted file mode 100644 index 214c1cc668f..00000000000 --- a/doc/user/project/pages/img/setup_ci.png +++ /dev/null diff --git a/doc/user/project/pages/img/setup_ci_v13_1.png b/doc/user/project/pages/img/setup_ci_v13_1.png Binary files differnew file mode 100644 index 00000000000..2cf1c05d6d8 --- /dev/null +++ b/doc/user/project/pages/img/setup_ci_v13_1.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index e81c9699153..5861282ca6f 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,7 +1,5 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' -last_updated: 2019-06-04 -type: index, reference stage: Release group: Release 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 @@ -11,46 +9,76 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80) in GitLab Enterprise Edition 8.3. > - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173) in GitLab Enterprise Edition 8.5. -> - [Ported](https://gitlab.com/gitlab-org/gitlab-foss/issues/14605) to GitLab Community Edition in GitLab 8.17. -> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30548) in GitLab 11.8. -> - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) in GitLab 11.8. +> - [Ported](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14605) to GitLab Community Edition in GitLab 8.17. +> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30548) in GitLab 11.8. +> - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. -**GitLab Pages is a feature that allows you to publish static websites -directly from a repository in GitLab.** - -You can use it either for personal or business websites, such as -portfolios, documentation, manifestos, and business presentations. -You can also attribute any license to your content. - -<img src="img/pages_workflow_v12_5.png" alt="Pages websites workflow" class="image-noshadow"> - -Pages is available for free for all GitLab.com users as well as for self-managed -instances (GitLab Core, Starter, Premium, and Ultimate). - -## Overview +With GitLab Pages, you can publish static websites +directly from a repository in GitLab. <div class="row"> <div class="col-md-9"> <p style="margin-top: 18px;"> -To publish a website with Pages, you can use any Static Site Generator (SSG), -such as Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also -publish any website written directly in plain HTML, CSS, and JavaScript.</p> -<p>Pages does <strong>not</strong> support dynamic server-side processing, for instance, as <code>.php</code> and <code>.asp</code> requires. See this article to learn more about -<a href="https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/">static websites vs dynamic websites</a>.</p> +<ul> +<li>Use for any personal or business website.</li> +<li>Use any Static Site Generator (SSG) or plain HTML.</li> +<li>Create websites for your projects, groups, or user account.</li> +<li>Host your site on your own GitLab instance or on GitLab.com for free.</li> +<li>Connect your custom domains and TLS certificates.</li> +<li>Attribute any license to your content.</li> +</ul> +</p> </div> <div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div> </div> -### How it works +To publish a website with Pages, you can use any SSG, +like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also +publish any website written directly in plain HTML, CSS, and JavaScript. -To use GitLab Pages, first you need to create a project in GitLab to upload your website's -files to. These projects can be either public, internal, or private, at your own choice. +Pages does **not** support dynamic server-side processing, for instance, as `.php` and `.asp` requires. +Learn more about +[static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). + +## Getting started + +To create a GitLab Pages website: + +| Document | Description | +| -------- | ----------- | +| [Use a `.gitlab-ci.yml` template](getting_started/new_or_existing_website.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | +| [Create a `gitlab-ci.yml` file from scratch](getting_started_part_four.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | +| [Use a new project template](getting_started/pages_bundled_template.md) | Create a new project with Pages already configured by using a new project template. | +| [Fork a sample project](getting_started/fork_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | + +To update a GitLab Pages website: + +| Document | Description | +| -------- | ----------- | +| [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md) | Learn about GitLab Pages default domains. | +| [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: + +| Document | Description | +| -------- | ----------- | +| [Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | Static versus dynamic site overview. | +| [Modern static site generators](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) | SSG overview. | +| [Build any SSG site with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | Use SSGs for GitLab Pages. | -GitLab will always deploy your website from a very specific folder called `public` in your -repository. Note that when you create a new project in GitLab, a [repository](../repository/index.md) +## How it works + +To use GitLab Pages, you must create a project in GitLab to upload your website's +files to. These projects can be either public, internal, or private. + +GitLab always deploys your website from a very specific folder called `public` in your +repository. When you create a new project in GitLab, a [repository](../repository/index.md) becomes available automatically. -To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md), +To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/README.md) to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named `.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. @@ -59,59 +87,29 @@ You can either use GitLab's [default domain for GitLab Pages websites](getting_s `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll need admin access to your domain's registrar (or control panel) to set it up with Pages. -### Getting started - -To get started with GitLab Pages, you can either: - -- [Use a bundled website template ready to go](getting_started/pages_bundled_template.md). -- [Copy an existing sample](getting_started/fork_sample_project.md). -- [Create a website from scratch or deploy an existing one](getting_started/new_or_existing_website.md). +The following diagrams show the workflows you might follow to get started with Pages. <img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow"> -Optional features: +## Access to your Pages site -- Use a [custom domain or subdomain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain). -- Add an [SSL/TLS certificate to secure your site under the HTTPS protocol](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages). - -Note that, if you're using GitLab Pages default domain (`.gitlab.io`), +If you're using GitLab Pages default domain (`.gitlab.io`), your website will be automatically secure and available under HTTPS. If you're using your own custom domain, you can optionally secure it with SSL/TLS certificates. -## Availability - If you're using GitLab.com, your website will be publicly available to the internet. - To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). -If you're using self-managed instances (Core, Starter, Premium, or Ultimate), +If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the [Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, -who can opt for making them public or internal to your server. +who can make them public or internal. -## Explore GitLab Pages +## Pages examples -To learn more about configuration options for GitLab Pages, read the following: - -| Document | Description | -| --- | --- | -| [GitLab Pages domain names, URLs, and baseurls](getting_started_part_one.md) | Understand how GitLab Pages default domains work. | -| [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. | -| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD's configuration options, Access Control, custom 404 pages, limitations, FAQ. | -|---+---| -| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | How to add custom domains and subdomains to your website, configure 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 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. | -|---+---| -| [Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. | -| [Modern static site generators](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. | -| [Build any SSG site with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | An overview on using SSGs for GitLab Pages. | - -## Advanced use - -There are quite some great examples of GitLab Pages websites built for some -specific reasons. These examples can teach you some advanced techniques +There are some great examples of GitLab Pages websites built for +specific reasons. These examples can teach you advanced techniques to use and adapt to your own needs: - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/blog/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/). @@ -120,14 +118,9 @@ to use and adapt to your own needs: - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/). - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). -## Admin GitLab Pages for self-managed instances - -Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with -the [admin guide](../../../administration/pages/index.md). - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) for getting started with GitLab Pages admin!** +## Administer GitLab Pages for self-managed instances -## More information about GitLab Pages +If you are running a self-managed instance of GitLab (GitLab Community Edition and Enterprise Editions), +[follow the administration steps](../../../administration/pages/index.md) to configure Pages. -- Announcement (2016-12-24): ["We're bringing GitLab Pages to CE"](https://about.gitlab.com/releases/2016/12/24/were-bringing-gitlab-pages-to-community-edition/) -- Announcement (2017-03-06): ["We are changing the IP of GitLab Pages on GitLab.com"](https://about.gitlab.com/releases/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) about how to get started with GitLab Pages administration. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index e36dfd89ab3..614a0d0dd19 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -25,7 +25,7 @@ In brief, this is what you need to upload your website in GitLab Pages: 1. Domain of the instance: domain name that is used for GitLab Pages (ask your administrator). 1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/README.md#pages) in the root directory of your repository. -1. A directory called `public` in your site's repo containing the content +1. A directory called `public` in your site's repository containing the content to be published. 1. GitLab Runner enabled for the project. @@ -87,7 +87,7 @@ will be deleted. When using Pages under the general domain of a GitLab instance (`*.example.io`), you _cannot_ use HTTPS with sub-subdomains. That means that if your -username/groupname contains a dot, for example `foo.bar`, the domain +username or group name contains a dot, for example `foo.bar`, the domain `https://foo.bar.example.io` will _not_ work. This is a limitation of the [HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages will continue to work provided you don't redirect HTTP to HTTPS. @@ -217,7 +217,7 @@ needing to compress files on-demand. ### Resolving ambiguous URLs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/issues/95) in GitLab 11.8 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/95) in GitLab 11.8 GitLab Pages makes assumptions about which files to serve when receiving a request for a URL that does not include an extension. diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 33181828fb2..d86704eb703 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -105,7 +105,7 @@ operating systems the steps might be slightly different. Follow the therefore, it needs to be part of the website content under the repo's [`public`](index.md#how-it-works) folder. -1. Add, commit, and push the file into your repo in GitLab. Once the pipeline +1. Add, commit, and push the file into your repository in GitLab. Once the pipeline passes, press **Enter** on your terminal to continue issuing your certificate. CertBot will then prompt you with the following message: diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 7fe4c4c051d..6fcad0a5357 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages Access Control -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. > - Available on GitLab.com in GitLab 12.4. You can enable Pages access control on your project, so that only diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index e2ee0dd47fe..d0baf57f169 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -2,7 +2,7 @@ type: reference, howto --- -# Protected Branches +# Protected branches [Permissions](../permissions.md) in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose @@ -114,7 +114,7 @@ all matching branches: ## Creating a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53361) in GitLab 11.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. When a protected branch or wildcard protected branches are set to [**No one** is **Allowed to push**](#using-the-allowed-to-merge-and-allowed-to-push-settings), @@ -134,7 +134,7 @@ To create a new branch through the user interface: ## Deleting a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/21393) in GitLab 9.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3. From time to time, it may be required to delete or clean up branches that are protected. @@ -155,7 +155,7 @@ command line or a Git client application. ## Protected Branches approval by Code Owners **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. It is possible to require at least one approval by a [Code Owner](code_owners.md) to a file changed by the @@ -194,11 +194,11 @@ for details about the pipelines security model. **11.9** -- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. +- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. **9.2** -- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/issues/21393)). +- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)). **8.11** diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index b134d283ba9..e80b8098bec 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -2,13 +2,13 @@ type: reference, howto --- -# Protected Tags +# Protected tags > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. -Protected Tags allow control over who has permission to create tags as well as preventing accidental update or deletion once created. Each rule allows you to match either an individual tag name, or use wildcards to control multiple tags at once. +Protected tags allow control over who has permission to create tags as well as preventing accidental update or deletion once created. Each rule allows you to match either an individual tag name, or use wildcards to control multiple tags at once. -This feature evolved out of [Protected Branches](protected_branches.md) +This feature evolved out of [protected branches](protected_branches.md) ## Overview diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index eab88d59867..ca658c06647 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -36,7 +36,7 @@ You can use push options to skip a CI/CD pipeline, or pass environment variables | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [environment variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/issues/27983) | +| `ci.variable="<name>=<value>"` | Provide [environment variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: @@ -60,9 +60,9 @@ time as pushing changes: | `merge_request.create` | Create a new merge request for the pushed branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) | -| `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) | -| `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) | +| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | +| `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | +| `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it will be created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index e2d0b616e4b..a3df173bd9d 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,5 +1,8 @@ --- type: reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # GitLab Quick Actions @@ -10,7 +13,8 @@ You can enter these commands while creating a new issue or merge request, or in comments of issues, epics, merge requests, and commits. Each command should be on a separate line in order to be properly detected and executed. -> From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672), once an action is executed, an alert is displayed when a quick action is successfully applied. +> From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672), once an +> action is executed, an alert appears when a quick action is successfully applied. ## Quick Actions for issues, merge requests and epics @@ -18,63 +22,66 @@ The following quick actions are applicable to descriptions, discussions and thre - Issues - Merge requests -- Epics **(ULTIMATE)** - -| Command | Issue | Merge request | Epic | Action | -|:--------------------------------------|:------|:--------------|:-----|:------ | -| `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻` | -| `/shrug <comment>` | ✓ | ✓ | ✓ | Append the comment with `¯\＿(ツ)＿/¯` | -| `/todo` | ✓ | ✓ | ✓ | Add a To Do | -| `/done` | ✓ | ✓ | ✓ | Mark To Do as done | -| `/subscribe` | ✓ | ✓ | ✓ | Subscribe | -| `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe | -| `/close` | ✓ | ✓ | ✓ | Close | -| `/reopen` | ✓ | ✓ | ✓ | Reopen | -| `/title <new title>` | ✓ | ✓ | ✓ | Change title | -| `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award | -| `/assign me` | ✓ | ✓ | | Assign yourself | -| `/assign @user` | ✓ | ✓ | | Assign one user | -| `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users **(STARTER)** | -| `/reassign @user1 @user2` | ✓ | ✓ | | Change assignee **(STARTER)** | -| `/unassign` | ✓ | ✓ | | Remove current assignee | -| `/unassign @user1 @user2` | ✓ | ✓ | | Remove assignee(s) **(STARTER)** | -| `/milestone %milestone` | ✓ | ✓ | | Set milestone | -| `/remove_milestone` | ✓ | ✓ | | Remove milestone | -| `/label ~label1 ~label2` | ✓ | ✓ | ✓ | Add label(s). Label names can also start without `~` but mixed syntax is not supported | -| `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace existing label(s) with those specified | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove all or specific label(s) | -| `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project | -| `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project | -| `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m` | -| `/remove_estimate` | ✓ | ✓ | | Remove time estimate | -| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Add spent time; optionally specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)` | -| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Subtract spent time; optionally specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)` | -| `/remove_time_spent` | ✓ | ✓ | | Remove time spent | -| `/lock` | ✓ | ✓ | | Lock the thread | -| `/unlock` | ✓ | ✓ | | Unlock the thread | -| `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st` | -| `/remove_due_date` | ✓ | | | Remove due date | -| `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, etc **(STARTER)** | -| `/clear_weight` | ✓ | | | Clear weight **(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. **(ULTIMATE)** | -| `/remove_epic` | ✓ | | | Remove from epic **(ULTIMATE)** | -| `/promote` | ✓ | | | Promote issue to epic **(ULTIMATE)** | -| `/confidential` | ✓ | | | Make confidential | -| `/duplicate <#issue>` | ✓ | | | Mark this issue as a duplicate of another issue and relate them for **(STARTER)** | -| `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue | -| `/relate #issue1 #issue2` | ✓ | | | Mark issues as related **(STARTER)** | -| `/move <path/to/project>` | ✓ | | | Move this issue to another project | -| `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue. ([Introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)) | -| `/remove_zoom` | ✓ | | | Remove Zoom meeting from this issue. ([Introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)) | -| `/target_branch <local branch name>` | | ✓ | | Set target branch | -| `/wip` | | ✓ | | Toggle the Work In Progress status | -| `/approve` | | ✓ | | Approve the merge request **(STARTER)** | -| `/submit_review` | | ✓ | | Submit a pending review. ([Introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/issues/8041)) **(PREMIUM)** | -| `/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). | -| `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/issues/7330)) **(ULTIMATE)** | -| `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/issues/7330)) **(ULTIMATE)** | -| `/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)** | -| `/remove_parent_epic` | | | ✓ | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/issues/10556)) **(ULTIMATE)** | +- Epics **(PREMIUM)** + +| Command | Issue | Merge request | Epic | Action | +| :------------------------------------ | :---- | :------------ | :--- | :------------------------------------------------------------------------------------------------------------------------------ | +| `/approve` | | ✓ | | Approve the merge request. **(STARTER)** | +| `/assign @user` | ✓ | ✓ | | Assign one user. | +| `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | +| `/assign me` | ✓ | ✓ | | Assign yourself. | +| `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | +| `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | +| `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | +| `/close` | ✓ | ✓ | ✓ | Close. | +| `/confidential` | ✓ | | | Make confidential. | +| `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue. | +| `/done` | ✓ | ✓ | ✓ | Mark To-Do as done. | +| `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/duplicate <#issue>` | ✓ | | | Mark this issue as a duplicate of another issue and mark them 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)** | +| `/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. | +| `/milestone %milestone` | ✓ | ✓ | | Set milestone. | +| `/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)** | +| `/reassign @user1 @user2` | ✓ | ✓ | | Change assignee. **(STARTER)** | +| `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace existing labels with those specified. | +| `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | +| `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | +| `/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_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. | +| `/remove_zoom` | ✓ | | | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/reopen` | ✓ | ✓ | ✓ | Reopen. | +| `/shrug <comment>` | ✓ | ✓ | ✓ | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)`. | +| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Add spent time. Optionally, specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)`. | +| `/submit_review` | | ✓ | | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). **(PREMIUM)** | +| `/subscribe` | ✓ | ✓ | ✓ | Subscribe to notifications. | +| `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | | ✓ | | Set target branch. | +| `/title <new title>` | ✓ | ✓ | ✓ | Change title. | +| `/todo` | ✓ | ✓ | ✓ | Add a To-Do. | +| `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | +| `/unassign` | ✓ | ✓ | | Remove all assignees. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove all or specific labels. | +| `/unlock` | ✓ | ✓ | | Unlock the thread. | +| `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe from notifications. | +| `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. **(STARTER)** | +| `/wip` | | ✓ | | Toggle the Work In Progress status. | +| `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Autocomplete characters @@ -86,11 +93,11 @@ to enter a parameter, compared to selecting items from a list. The easiest way to set parameters for quick actions is to use autocomplete. If you manually enter a parameter, it must be enclosed in double quotation marks -(`"`), unless it contains only: +(`"`), unless it contains only these characters: 1. ASCII letters. -1. Numerals. -1. Underscore, hyphen, question mark, dot, and ampersand. +1. Numerals (0-9). +1. Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`). Parameters are also case-sensitive. Autocomplete handles this, and the insertion of quotation marks, automatically. @@ -100,7 +107,7 @@ of quotation marks, automatically. The following quick actions are applicable for commit messages: | Command | Action | -|:------------------------|:------------------------------------------| +| :---------------------- | :---------------------------------------- | | `/tag v1.2.3 <message>` | Tags this commit with an optional message | <!-- ## Troubleshooting diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index bdb99d16625..58d143fb32b 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41766) in GitLab 11.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. It is typical to create a [Git tag](../../../university/training/topics/tags.md) at the moment of release to introduce a checkpoint in your source code @@ -67,9 +67,11 @@ A link is any URL which can point to whatever you like; documentation, built binaries, or other related materials. These can be both internal or external links from your GitLab instance. +The four types of links are "Runbook," "Package," "Image," and "Other." + #### Permanent links to Release assets -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27300) in GitLab 12.9. +> [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 @@ -105,7 +107,7 @@ The physical location of the asset can change at any time and the direct link wi ### Releases associated with milestones -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29020) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29020) in GitLab 12.5. > - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/39467) to edit milestones in the UI in GitLab 13.0. Releases can optionally be associated with one or more @@ -141,7 +143,7 @@ project. ### Number of Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36667) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36667) in GitLab 12.8. The incremental number of Releases is displayed on the project's details page. When clicked, it takes you to the list of Releases. @@ -154,7 +156,7 @@ it is displayed to every user regardless of their permission level. ### Upcoming Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/38105) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. A Release may be created ahead of time by specifying a future `released_at` date. Until the `released_at` date and time is reached, an **Upcoming Release** badge will appear next to the @@ -186,7 +188,7 @@ we recommend doing this as one of the last steps in your CI/CD release pipeline. ## Editing a release -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26016) in GitLab 12.6. Asset link editing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. Asset link editing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. To edit the details of a release, navigate to **Project overview > Releases** and click the edit button (pencil icon) in the top-right corner of the release you want to modify. @@ -205,7 +207,7 @@ through the **Edit Release** page is planned for a future version of GitLab. ## Notification for Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26001) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26001) in GitLab 12.4. You can be notified by email when a new Release is created for your project. @@ -243,7 +245,7 @@ You can also edit an existing tag to add release notes: ## Release Evidence -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26019) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. Each time a release is created, GitLab takes a snapshot of data that's related to it. This data is called Release Evidence. It includes linked milestones and issues, and @@ -256,7 +258,7 @@ can have multiple Release Evidence snapshots. You can view the Release Evidence its details on the Release page. NOTE: **Note:** -When the issue tracker is disabled, release evidence [is not collected](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). +When the issue tracker is disabled, release evidence [cannot be downloaded](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). Release Evidence is stored as a JSON object, so you can compare evidence by using commonly-available tools. @@ -267,11 +269,16 @@ Here is an example of a Release Evidence object: { "release": { "id": 5, - "tag": "v4.0", + "tag_name": "v4.0", "name": "New release", - "project_id": 45, - "project_name": "Project name", - "released_at": "2019-06-28 13:23:40 UTC", + "project": { + "id": 20, + "name": "Project name", + "created_at": "2019-04-14T11:12:13.940Z", + "description": "Project description" + }, + "created_at": "2019-06-28 13:23:40 UTC", + "description": "Release description", "milestones": [ { "id": 11, @@ -311,7 +318,7 @@ Here is an example of a Release Evidence object: } ``` -### Enabling Release Evidence display **(CORE ONLY)** +### Diabling Release Evidence display **(CORE ONLY)** This feature comes with the `:release_evidence_collection` feature flag enabled by default in GitLab self-managed instances. To turn it off, @@ -393,6 +400,8 @@ deploy_to_production: - if: $CI_DEPLOY_FREEZE == null ``` +For more information, see [Deployment safety](../../../ci/environments/deployment_safety.md). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index a49701017f3..75a84e36169 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -46,7 +46,7 @@ You can use [repository mirroring](repository_mirroring.md) to keep your fork sy The main difference is that with repository mirroring your remote fork will be automatically kept up-to-date. -Without mirroring, to work locally you'll have to use `git pull` to update your local repo +Without mirroring, to work locally you'll have to use `git pull` to update your local repository with the upstream project, then push the changes back to your fork to update it. CAUTION: **Caution:** diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 2deb53b313c..e63b57747ef 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -25,7 +25,7 @@ for that commit. ## Blame previous commit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/19299) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19299) in GitLab 12.7. To see earlier revisions of a specific line, click **View blame prior to this change** until you've found the changes you're interested in viewing: diff --git a/doc/user/project/repository/img/repository_cleanup.png b/doc/user/project/repository/img/repository_cleanup.png Binary files differdeleted file mode 100644 index e343f23ac27..00000000000 --- a/doc/user/project/repository/img/repository_cleanup.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 055443daa1f..48975b7864e 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -27,7 +27,7 @@ that you [connect with GitLab via SSH](../../../ssh/README.md). ## Files -Use a repository to store your files in GitLab. From [GitLab 12.10 onwards](https://gitlab.com/gitlab-org/gitlab/issues/33806), +Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), you'll see on the repository's file tree an icon next to the file name according to its extension: @@ -84,9 +84,9 @@ according to the markup language. | [AsciiDoc](../../asciidoc.md) | `adoc`, `ad`, `asciidoc` | | [Textile](https://textile-lang.com/) | `textile` | | [rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | -| [Orgmode](https://orgmode.org/) | `org` | +| [Org mode](https://orgmode.org/) | `org` | | [creole](http://www.wikicreole.org/) | `creole` | -| [Mediawiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | +| [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | ### Repository README and index files @@ -116,7 +116,7 @@ user's sessions and include code, narrative text, equations, and rich output. ### OpenAPI viewer -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/19515) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19515) in GitLab 12.6. GitLab can render OpenAPI specification files with its file viewer, provided their filenames include `openapi` or `swagger` and their extension is `yaml`, @@ -219,7 +219,9 @@ vendored code, and most markup languages are excluded. This behavior can be adjusted by overriding the default. For example, to enable `.proto` files to be detected, add the following to `.gitattributes` in the root of your repository. -> *.proto linguist-detectable=true +```plaintext +*.proto linguist-detectable=true +``` ## Locked files **(PREMIUM)** @@ -232,7 +234,7 @@ You can access your repos via [repository API](../../../api/repositories.md). ## Clone in Apple Xcode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/45820) in GitLab 11.0 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0 Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned in Xcode using the new **Open in Xcode** button, located next to the Git URL @@ -240,7 +242,7 @@ used for cloning your project. The button is only shown on macOS. ## Download Source Code -> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/24704) in GitLab 11.11. +> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. The source code stored in a repository can be downloaded from the UI. By clicking the download icon, a dropdown will open with links to download the following: diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index ca82be280d9..1948b12aacd 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,6 +1,6 @@ # Jupyter Notebook Files -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2508/) in GitLab 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. [Jupyter](https://jupyter.org/) Notebook (previously IPython Notebook) files are used for interactive computing in many fields and contain a complete record of the 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 16bffe5417d..124150c441a 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,150 +1,244 @@ --- +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: howto --- -# Reducing the repository size using Git - -A GitLab Enterprise Edition administrator can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md) -which will prevent you from exceeding it. - -When a project has reached its size limit, you will not be able to push to it, -create a new merge request, or merge existing ones. You will still be able to -create new issues, and clone the project though. Uploading LFS objects will -also be denied. - -If you exceed the repository size limit, your first thought might be to remove -some data, make a new commit and push back to the repository. Perhaps you can -move some blobs to LFS, or remove some old dependency updates from history. -Unfortunately, it's not so easy and that workflow won't work. Deleting files in -a commit doesn't actually reduce the size of the repo since the earlier commits -and blobs are still around. What you need to do is rewrite history with Git's -[`filter-branch` option](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#The-Nuclear-Option:-filter-branch), -or an open source community-maintained tool like the -[BFG](https://rtyley.github.io/bfg-repo-cleaner/). - -Note that even with that method, until `git gc` runs on the GitLab side, the -"removed" commits and blobs will still be around. You also need to be able to -push the rewritten history to GitLab, which may be impossible if you've already -exceeded the maximum size limit. +# Reduce repository size -In order to lift these restrictions, the administrator of the GitLab instance -needs to increase the limit on the particular project that exceeded it, so it's -always better to spot that you're approaching the limit and act proactively to -stay underneath it. If you hit the limit, and your admin can't - or won't - -temporarily increase it for you, your only option is to prune all the unneeded -stuff locally, and then create a new project on GitLab and start using that -instead. +Git repositories become larger over time. When large files are added to a Git repository: -If you can continue to use the original project, we recommend [using -BFG](#using-the-bfg-repo-cleaner), a tool that's built and -maintained by the open source community. It's faster and simpler than -`git filter-branch`, and GitLab can use its account of what has changed to clean -up its own internal state, maximizing the space saved. +- Fetching the repository becomes slower because everyone must download the files. +- They take up a large amount of storage space on the server. +- Git repository storage limits [can be reached](#storage-limits). -CAUTION: **Caution:** -Make sure to first make a copy of your repository since rewriting history will -purge the files and information you are about to delete. Also make sure to -inform any collaborators to not use `pull` after your changes, but use `rebase`. +Rewriting a repository can remove unwanted history to make the repository smaller. +[`git filter-repo`](https://github.com/newren/git-filter-repo) is a tool for quickly rewriting Git +repository history, and is recommended over both: -CAUTION: **Caution:** -This process is not suitable for removing sensitive data like password or keys -from your repository. Information about commits, including file content, is -cached in the database, and will remain visible even after they have been -removed from the repository. +- [`git filter-branch`](https://git-scm.com/docs/git-filter-branch). +- [BFG](https://rtyley.github.io/bfg-repo-cleaner/). + +DANGER: **Danger:** +Rewriting repository history is a destructive operation. Make sure to backup your repository before +you begin. The best way back up a repository is to +[export the project](../settings/import_export.md#exporting-a-project-and-its-data). -## Using the BFG Repo-Cleaner +## Purge files from repository history -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/19376) in GitLab 11.6. +To make cloning your project faster, rewrite branches and tags to remove unwanted files. -1. [Install BFG](https://rtyley.github.io/bfg-repo-cleaner/) from its open source community repository. +1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/master/INSTALL.md) + using a supported package manager or from source. -1. Navigate to your repository: +1. Clone a fresh copy of the repository using `--bare`: ```shell - cd my_repository/ + git clone --bare https://example.gitlab.com/my/project.git ``` -1. Change to the branch you want to remove the big file from: +1. Using `git filter-repo`, purge any files from the history of your repository. + + To purge all large files, the `--strip-blobs-bigger-than` option can be used: ```shell - git checkout master + git filter-repo --strip-blobs-bigger-than 10M ``` -1. Create a commit removing the large file from the branch, if it still exists: + To purge specific large files by path, the `--path` and `--invert-paths` options can be combined: ```shell - git rm path/to/big_file.mpg - git commit -m 'Remove unneeded large file' + git filter-repo --path path/to/big/file.m4v --invert-paths ``` -1. Rewrite history: + See the + [`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 - bfg --delete-files path/to/big_file.mpg + git remote add origin https://example.gitlab.com/<namespace>/<project_name>.git ``` - An object map file will be written to `object-id-map.old-new.txt`. Keep it - around - you'll need it for the final step! +1. Force push your changes to overwrite all branches on GitLab: -1. Force-push the changes to GitLab: + ```shell + git push origin --force --all + ``` + + [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 --force-with-lease origin master + git push origin --force --tags ``` - If this step fails, someone has changed the `master` branch while you were - rewriting history. You could restore the branch and re-run BFG to preserve - their changes, or use `git push --force` to overwrite their changes. + [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. Navigate to **Project > Settings > Repository > Repository Cleanup**: +## 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). - Upload the `object-id-map.old-new.txt` file and press **Start cleanup**. - This will remove any internal Git references to the old commits, and run - `git gc` against the repository. You will receive an email once it has - completed. +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. -NOTE: **Note:** -This process will remove some copies of the rewritten commits from GitLab's -cache and database, but there are still numerous gaps in coverage - at present, -some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) -may help to remove some of them, but it should not be depended on for security -purposes! +The following internal refs are not advertised: -## Using `git filter-branch` +- `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. -1. Navigate to your repository: +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. - ```shell - cd my_repository/ - ``` +However, these refs can be accessed from the Git bundle inside a project export. -1. Change to the branch you want to remove the big file from: +1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/master/INSTALL.md) + using a supported package manager or from source. + +1. Generate a fresh [export from the + project](../settings/import_export.html#exporting-a-project-and-its-data) and download it. + +1. Decompress the backup using `tar`: ```shell - git checkout master + tar xzf project-backup.tar.gz ``` -1. Use `filter-branch` to remove the big file: + This will contain a `project.bundle` file, which was created by + [`git bundle`](https://git-scm.com/docs/git-bundle). + +1. Clone a fresh copy of the repository from the bundle: ```shell - git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD + git clone --bare --mirror /path/to/project.bundle ``` -1. Instruct Git to purge the unwanted data: +1. Using `git filter-repo`, purge any files from the history of your repository. Because we are + trying to remove internal refs, we will rely on the `commit-map` produced by each run to tell us + which internal refs to remove. + + NOTE:**Note:** + `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from + the previous run. You will need this file from **every** run. Do the next step every time you run + `git filter-repo`. + + To purge all large files, the `--strip-blobs-bigger-than` option can be used: ```shell - git reflog expire --expire=now --all && git gc --prune=now --aggressive + git filter-repo --strip-blobs-bigger-than 10M ``` -1. Lastly, force push to the repository: + To purge specific large files by path, the `--path` and `--invert-paths` options can be combined. ```shell - git push --force origin master + git filter-repo --path path/to/big/file.m4v --invert-paths ``` -Your repository should now be below the size limit. + See the + [`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. Run a [repository cleanup](#repository-cleanup). + +## Repository cleanup + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. + +Repository cleanup allows you to upload a text file of objects and GitLab will remove internal Git +references to these objects. You can use +[`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a +`commit-map` file) that can be used with repository cleanup. + +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. Click **Start cleanup**. + +This will: + +- Remove any internal Git references to old commits. +- Run `git gc` against the repository. + +You will receive an email once it has completed. + +When using repository cleanup, note: + +- Housekeeping prunes loose objects older than 2 weeks. This means objects added in the last 2 weeks + will not be removed immediately. If you have access to the + [Gitaly](../../../administration/gitaly/index.md) server, you may run `git gc --prune=now` to + prune all loose objects immediately. +- This process will remove some copies of the rewritten commits from GitLab's cache and database, + but there are still numerous gaps in coverage and some of the copies may persist indefinitely. + [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) + may help to remove some of them, but it should not be depended on for security purposes! + +## Storage limits + +Repository size limits: + +- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#repository-size-limit-starter-only) + on self-managed instances. **(STARTER ONLY)** +- Are [set for GitLab.com](../../gitlab_com/index.md#repository-size-limit). + +When a project has reached its size limit, you cannot: + +- Push to the project. +- Create a new merge request. +- Merge existing merge requests. +- Upload LFS objects. + +You can still: + +- Create new issues. +- Clone the project. + +If you exceed the repository size limit, you might try to: + +1. Remove some data. +1. Make a new commit. +1. Push back to the repository. + +Perhaps you might also: + +- Move some blobs to LFS. +- Remove some old dependency updates from history. + +Unfortunately, this workflow won't work. Deleting files in a commit doesn't actually reduce the size +of the repository because the earlier commits and blobs still exist. + +What you need to do is rewrite history. We recommend the open-source community-maintained tool +[`git filter-repo`](https://github.com/newren/git-filter-repo). + +NOTE: **Note:** +Until `git gc` runs on the GitLab side, the "removed" commits and blobs will still exist. You also +must be able to push the rewritten history to GitLab, which may be impossible if you've already +exceeded the maximum size limit. + +In order to lift these restrictions, the administrator of the self-managed GitLab instance must +increase the limit on the particular project that exceeded it. Therefore, it's always better to +proactively stay underneath the limit. If you hit the limit, and can't have it temporarily +increased, your only option is to: + +1. Prune all the unneeded stuff locally. +1. Create a new project on GitLab and start using that instead. + +CAUTION: **Caution:** +This process is not suitable for removing sensitive data like password or keys from your repository. +Information about commits, including file content, is cached in the database, and will remain +visible even after they have been removed from the repository. <!-- ## Troubleshooting diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index fdbea385998..f75b083e6dc 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -28,7 +28,7 @@ immediate update, unless: - The mirror is already being updated. - 5 minutes haven't elapsed since its last update. -For security reasons, from [GitLab 12.10 onwards](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), +For security reasons, in [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), the URL to the original repository is only displayed to users with Maintainer or Owner permissions to the mirrored project. @@ -134,7 +134,7 @@ The repository will push soon. To force a push, click the appropriate button. ## Pulling from a remote repository **(STARTER)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51) in GitLab Enterprise Edition 8.2. -> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. +> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. @@ -356,6 +356,24 @@ a [Push event webhook](../integrations/webhooks.md#push-events) to trigger an im pull to GitLab. Push mirroring from GitLab is rate limited to once per minute when only push mirroring protected branches. +### Configure a webhook to trigger an immediate pull to GitLab + +Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository-starter) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you will need to configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. + +To do this: + +- Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. +- Navigate to **Settings > Webhooks** +- Add the webhook URL which in this case will use the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter) request to trigger an immediate pull after updates to the repository. + + ```plaintext + https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> + ``` + +- Ensure that the **Push Events** checkbox is selected. +- Click on **Add Webhook** button to save the webhook. +- To test the integration click on the **Test** button and confirm GitLab does not return any error. + ### Preventing conflicts using a `pre-receive` hook CAUTION: **Warning:** @@ -388,13 +406,13 @@ proxy_push() REFNAME="$3" # --- Pattern of branches to proxy pushes - whitelisted=$(expr "$branch" : "\(master\)") + allowlist=$(expr "$branch" : "\(master\)") case "$refname" in refs/heads/*) branch=$(expr "$refname" : "refs/heads/\(.*\)") - if [ "$whitelisted" = "$branch" ]; then + if [ "$allowlist" = "$branch" ]; then unset GIT_QUARANTINE_PATH # handle https://git-scm.com/docs/git-receive-pack#_quarantine_environment error="$(git push --quiet $TARGET_REPO $NEWREV:$REFNAME 2>&1)" fail=$? @@ -435,7 +453,7 @@ Note that this sample has a few limitations: - This example may not work verbatim for your use case and might need modification. - It does not regard different types of authentication mechanisms for the mirror. - It does not work with forced updates (rewriting history). - - Only branches that match the `whitelisted` patterns will be proxy pushed. + - Only branches that match the `allowlist` patterns will be proxy pushed. - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update and Git will complain about it. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 20143af0b33..d55d5c5c2d8 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -65,11 +65,11 @@ git config --global gpg.format x509 ### Windows and MacOS -Install [smimesign](https://github.com/github/smimesign) by downloading the +Install [S/MIME Sign](https://github.com/github/smimesign) by downloading the installer or via `brew install smimesign` on MacOS. Get the ID of your certificate with `smimesign --list-keys` and set your -signingkey `git config --global user.signingkey ID`, then configure X.509: +signing key `git config --global user.signingkey ID`, then configure X.509: ```shell git config --global gpg.x509.program smimesign diff --git a/doc/user/project/requirements/img/requirement_edit_save_v12_10.png b/doc/user/project/requirements/img/requirement_edit_save_v12_10.png Binary files differdeleted file mode 100644 index 6cf7db361b8..00000000000 --- a/doc/user/project/requirements/img/requirement_edit_save_v12_10.png +++ /dev/null diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 50343e52a68..d9bd02518a4 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -1,14 +1,23 @@ --- type: reference, howto +stage: Plan +group: Certify +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 --- -# Requirements **(ULTIMATE)** +# Requirements Management **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -Requirements allow you to create criteria to check your products against. They -can be based on users, stakeholders, system, software, or anything else you -find important to capture. +With requirements, you can set criteria to check your products against. They can be based on users, +stakeholders, system, software, or anything else you find important to capture. + +A requirement is an artifact in GitLab which describes the specific behavior of your product. +Requirements are long-lived and don't disappear unless manually cleared. + +If an industry standard *requires* that your application has a certain feature or behavior, you can +[create a requirement](#create-a-requirement) to reflect this. +When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). @@ -38,22 +47,18 @@ list page. To edit a requirement: -1. From the requirements list, click the **Edit** (**{pencil}**) button. +1. From the requirements list, click **Edit** (**{pencil}**). 1. Update the title in text input field. 1. Click **Save changes**.  -The requirements list shows the new title immediately. - - - ## Archive a requirement You can archive an open requirement (if you have the necessary privileges) while you're in the **Open** tab. -From the requirements list page, click the **Archive** (**{archive}**) button. +From the requirements list page, click **Archive** (**{archive}**).  @@ -65,6 +70,84 @@ You can view the list of archived requirements in the **Archived** tab.  -To reopen an archived requirement, click the **Reopen** button. +To reopen an archived requirement, click **Reopen**. As soon as a requirement is reopened, it no longer appears in the **Archived** tab. + +## Search for a requirement from the requirements list page + +> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +You can search for a requirement from the list of requirements using filtered search bar (similar to +that of Issues and Merge Requests) based on following parameters: + +- Title +- Author username + +To search, go to the list of requirements and click the field **Search or filter results**. +It will display a dropdown menu, from which you can add an author. You can also enter plain +text to search by epic title or description. When done, press <kbd>Enter</kbd> on your +keyboard to filter the list. + +You can also sort requirements list by: + +- Created date +- Last updated + +## Allow requirements to be satisfied from a CI job + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +GitLab supports [requirements test +reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements-ultimate) now. +You can add a job to your CI pipeline that, when triggered, marks all existing +requirements as Satisfied. + +### Add the manual job to CI + +To configure your CI to mark requirements as Satisfied when the manual job is +triggered, add the code below to your `.gitlab-ci.yml` file. + +```yaml +requirements_confirmation: + when: manual + allow_failure: false + script: + - mkdir tmp + - echo "{\"*\":\"passed\"}" > tmp/requirements.json + artifacts: + reports: + requirements: tmp/requirements.json +``` + +This definition adds a manually-triggered (`when: manual`) job to the CI +pipeline. It's blocking (`allow_failure: false`), but it's up to you what +conditions you use for triggering the CI job. Also, you can use any existing CI job +to mark all requirements as satisfied, as long as the `requirements.json` +artifact is generated and uploaded by the CI job. + +When you manually trigger this job, the `requirements.json` file containing +`{"*":"passed"}` is uploaded as an artifact to the server. On the server side, +the requirement report is checked for the "all passed" record +(`{"*":"passed"}`), and on success, it marks all existing open requirements as +Satisfied. + +### Add the manual job to CI conditionally + +To configure your CI to include the manual job only when there are some open +requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI variable. + +```yaml +requirements_confirmation: + rules: + - if: "$CI_HAS_OPEN_REQUIREMENTS" == "true" + when: manual + - when: never + allow_failure: false + script: + - mkdir tmp + - echo "{\"*\":\"passed\"}" > tmp/requirements.json + artifacts: + reports: + requirements: tmp/requirements.json +``` diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index d021f259015..ffb1f6a1407 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,6 +1,13 @@ +--- +stage: Plan +group: Certify +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 Desk **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/149) in [GitLab Premium 9.1](https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#service-desk-eep). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/149) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. ## Overview @@ -28,14 +35,19 @@ with GitLab CI/CD. Here's how Service Desk will work for you: -1. You'll provide a project-specific email address to your paying customers, who can email you directly from within the app -1. Each email they send creates an issue in the appropriate project -1. Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues -1. Your team communicates back and forth with the customer to understand the request -1. Your team starts working on implementing code to solve your customer's problem -1. When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically -1. The customer will have been attended successfully via email, without having real access to your GitLab instance -1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer +1. You provide a project-specific email address to your paying customers, who can email you directly + from within the app. +1. Each email they send creates an issue in the appropriate project. +1. Your team members navigate to the Service Desk issue tracker, where they can see new support + requests and respond inside associated issues. +1. Your team communicates back and forth with the customer to understand the request. +1. Your team starts working on implementing code to solve your customer's problem. +1. When your team finishes the implementation, whereupon the merge request is merged and the issue + is closed automatically. +1. The customer will have been attended successfully via email, without having real access to your + GitLab instance. +1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with + your customer. ## How it works @@ -56,7 +68,8 @@ If you have the correct access and a Premium license, you have the option to set Follow these steps to do so: 1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - This must support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). + - We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), + but in GitLab 11.7 and later you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). 1. Navigate to your project's **Settings > General** and locate the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues to the project. These issues will be [confidential](issues/confidential_issues.md), so they will @@ -83,7 +96,7 @@ navigation's **Issues** menu. ### Using customized email templates - > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. + > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. When a user submits a new issue using Service Desk, or when a new note is created on a Service Desk issue, an email is sent to the author. @@ -110,14 +123,14 @@ in the email, `%{ISSUE_PATH}` placeholder which will be replaced by ### Using custom email display name -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7529) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. You can customize the email display name. Emails sent from Service Desk will have this name in the `From` header. The default display name is `GitLab Support Bot`. ### Using custom email address -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. NOTE: **Note:** This feature is disabled by default. For steps to enable it, see [Enable custom email address](#enable-custom-email-address). @@ -160,12 +173,12 @@ As a result, a new Service Desk issue is created from this email in the `mygroup #### Enable custom email address -This feature comes with the `service_desk_email` feature flag disabled by default. +This feature comes with the `service_desk_custom_address` feature flag disabled by default. To turn on the feature, ask a GitLab administrator with Rails console access to run the following command: ```ruby -Feature.enable(service_desk_email) +Feature.enable(:service_desk_custom_address) ``` The configuration options are the same as for configuring diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index e9521a0567e..5a364eb89aa 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,6 +1,6 @@ # Project import/export -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/3050) in GitLab 8.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. > - From GitLab 10.0, administrators can disable the project export option on the GitLab instance. Existing projects running on any GitLab instance or GitLab.com can be exported with all their related @@ -158,12 +158,16 @@ If use of the `Internal` visibility level [is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. +NOTE: **Note:** +The maximum import file size can be set by the Administrator, default is 50MB. +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). + ## Rate limits To help avoid abuse, users are rate limited to: -| Request Type | Limit | -| ---------------- | --------------------------- | -| Export | 1 project per 5 minutes | -| Download export | 10 projects per 10 minutes | -| Import | 30 projects per 5 minutes | +| Request Type | Limit | +| ---------------- | ----------------------------------------- | +| Export | 30 projects per 5 minutes | +| Download export | 10 downloads per project every 10 minutes | +| Import | 30 projects per 5 minutes | diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 0c98772237b..0798c39fff5 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -55,7 +55,7 @@ Use the switches to enable or disable the following features: | **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | | **Forks** | ✓ | Enables [forking](../index.md#fork-a-project) functionality | | **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your docker images | +| **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 | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | @@ -192,11 +192,9 @@ to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: -1. You have at least **Maintainer** [permissions](../../permissions.md#project-members-permissions) to that group. -1. The project is in a subgroup you own. -1. You're at least a **Maintainer** of the project under your personal namespace. - Similarly, if you're an owner of a group, you can transfer any of its projects - under your own user. +- You have at least **Maintainer** [permissions](../../permissions.md#project-members-permissions) to that group. +- You're at least an **Owner** of the project to be transferred. +- The group to which the project is being transferred to must allow creation of new projects. To transfer a project: @@ -228,14 +226,14 @@ To remove a project: This action either: - Removes a project including all associated resources (issues, merge requests etc). -- Since [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/32935), on +- Since [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/32935), on [GitLab Premium or GitLab.com Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a project 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). #### Restore a project **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32935) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. To restore a project marked for deletion: @@ -272,3 +270,8 @@ Configure Error Tracking to discover and view [Sentry errors within GitLab](../o ### Jaeger tracing **(ULTIMATE)** Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../operations/tracing.md). + +### 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). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 303a6f6d3be..42ba2654b42 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,6 +1,13 @@ -# Project access tokens **(CORE ONLY)** +# Project access tokens (Alpha) **(CORE ONLY)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. +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. + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. +> - It's deployed behind a feature flag, disabled by default. +> - 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). Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). @@ -27,7 +34,7 @@ For each project access token created, a bot user will also be created and added ["Maintainer" level permissions](../../permissions.md#project-members-permissions). API calls made with a project access token will be associated to the corresponding bot user. -These users will appear in **{settings}** **Settings > Members** but can not be modified. +These users will appear in **Members** but can not be modified. Furthermore, the bot user can not be added to any other project. When the project access token is [revoked](#revoking-a-project-access-token) the bot user will be deleted and all @@ -53,3 +60,22 @@ the following table. | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | | `read_repository` | Allows read-only access (pull) to the repository. | | `write_repository` | Allows read-write access (pull, push) to the repository. | + +### 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**. +[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(:resource_access_token) +``` + +To disable it: + +```ruby +Feature.disable(:resource_access_token) +``` diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index 8ebfb638894..ec0a79583d5 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -55,7 +55,7 @@ To deploy the Status Page to AWS S3 you need to add the Status Page project & co Once the CI/CD variables are set, you'll need to set up the Project you want to use for Incident issues: -1. Navigate to **Settings > Operations > Status Page**. +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**. @@ -71,7 +71,8 @@ The incident detail page shows detailed information about a particular incident. - Status on the incident, including when the incident was last updated. - The incident title, including any emojis. -- The description of the incident, including emojis and static images. +- 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.  @@ -82,12 +83,21 @@ The incident detail page shows detailed information about a particular incident. To publish an Incident, you first need to create an issue in the Project you enabled the Status Page settings in. -Once this issue is created, a background worker will publish the issue onto the Status Page using the credentials you provided during setup. +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 are not published. If a published issue is made confidential it will be unpublished. +Confidential issues can't be published. If you make a published issue confidential, it will be unpublished. ### Publishing updates @@ -108,3 +118,15 @@ Anyone with access to view the Issue can add an Emoji Award to a comment, so you ### 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. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 57a26f4e928..b88e1ed2d37 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -1,6 +1,9 @@ --- type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Time Tracking diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index d4daca0e1e4..0ddc9762bc5 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ # Web IDE -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/issues/44157) in 10.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. The Web IDE editor makes it faster and easier to contribute changes to your projects by providing an advanced editor with commit staging. @@ -57,10 +57,30 @@ which applies to the entire Web IDE screen. |---------------------------------------------------------------|-----------------------------------------| |  |  | +## Configure the Web IDE + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. + +The Web IDE supports configuration of certain editor settings by using +[`.editorconfig` files](https://editorconfig.org/). When opening a file, the +Web IDE looks for a file named `.editorconfig` in the current directory +and all parent directories. If a configuration file is found and has settings +that match the file's path, these settings will be enforced on the opened file. + +The Web IDE currently supports the following `.editorconfig` settings: + +- `indent_style` +- `indent_size` +- `end_of_line` +- `trim_trailing_whitespace` +- `tab_width` +- `insert_final_newline` + ## Commit changes -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4 and [brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/issues/44157) in 10.7. -> - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/issues/33441), files were automatically staged. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files were automatically staged. > - From [GitLab 12.9 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All your current changes necessarily have to be committed or discarded. After making your changes, click the **Commit** button on the bottom-left to @@ -116,6 +136,20 @@ in the top of the sidebar to open a list of branches. You will need to commit or discard all your changes before switching to a different branch. +## Markdown editing + +> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Core](https://about.gitlab.com/pricing/) 10.7. +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. + +When you edit Markdown files in the Web IDE, you can preview your changes by +clicking the **Preview Markdown** tab above the file editor. The Markdown preview +supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + +You can also upload any local images by pasting them directly in the Markdown file. +The image is uploaded to the same directory and is named `image.png` by default. +If another file already exists with the same name, a numeric suffix is automatically +added to the file name. + ## Live Preview > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. @@ -152,9 +186,10 @@ below. } ``` -## Interactive Web Terminals for the Web IDE **(ULTIMATE ONLY)** +## Interactive Web Terminals for the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Core in 13.1. CAUTION: **Warning:** Interactive Web Terminals for the Web IDE is currently in **Beta**. @@ -252,7 +287,8 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Core in 13.1. File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal @@ -284,7 +320,7 @@ terminal: - The `webide-file-sync` executable must start **after** the project directory is available. This is why we need to add `sleep 5` to the `command`. - See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/issues/7) for + See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/-/issues/7) for more information. - `$CI_PROJECT_DIR` is a [predefined environment variable](../../../ci/variables/predefined_variables.md) diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index fa3ad4536ef..82dbeb0ff7e 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -52,7 +52,7 @@ When you're ready, click the **Create page** and the new page will be created. ### Attachment storage -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33475) in GitLab 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. Starting with GitLab 11.3, any file that is uploaded to the wiki via GitLab's interface will be stored in the wiki Git repository, and it will be available @@ -185,6 +185,14 @@ them like you would do with every other Git repository. On the right sidebar, click on **Clone repository** and follow the on-screen instructions. +Files that you add to your wiki locally must have one of the following +supported extensions, depending on the markup language you wish to use, +otherwise they will not display when pushed to GitLab: + +- Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. +- AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. +- Other markup extensions: `.textile`, `.rdoc`, `.org`, `.creole`, `.wiki`, `.mediawiki`, `.rst`. + ## Customizing sidebar On the project's Wiki page, there is a right side navigation that renders the full Wiki pages list by default, with hierarchy. diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index fac1702f2ac..eaa57395b8f 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -2,9 +2,10 @@ > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. -NOTE: **Note** -Advanced Global Search (powered by Elasticsearch) is not yet available on GitLab.com. We are working on adding it. -[Follow this epic for the latest updates](https://gitlab.com/groups/gitlab-org/-/epics/153). +NOTE: **GitLab.com availability:** +Advanced Global Search (powered by Elasticsearch) is not yet available on GitLab.com. +It will be progressively enabled for all paid groups in Q3 of 2020. +[Follow this epic](https://gitlab.com/groups/gitlab-com/-/epics/649) for the latest updates on the timeline. Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index 5113578af9e..1ca9649b581 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -4,9 +4,10 @@ > > - Introduced in [GitLab Enterprise Starter](https://about.gitlab.com/pricing/) 9.2 -NOTE: **Note** -Advanced Global Search (powered by Elasticsearch) is not yet available on GitLab.com. We are working on adding it. -[Follow this epic for the latest updates](https://gitlab.com/groups/gitlab-org/-/epics/153). +NOTE: **GitLab.com availability:** +Advanced Global Search (powered by Elasticsearch) is not yet available on GitLab.com. +It will be progressively enabled for all paid groups in Q3 of 2020. +[Follow this epic](https://gitlab.com/groups/gitlab-com/-/epics/649) for the latest updates on the timeline. Use advanced queries for more targeted search results. diff --git a/doc/user/search/index.md b/doc/user/search/index.md index f5efa3519d9..b616b606b64 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -49,8 +49,8 @@ groups: 1. Select or type the operator to use for filtering the attribute. The following operators are available: - `=`: Is - - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18059) in GitLab 12.7) -1. Enter the text to filter the attribute by. + - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) +1. Enter the text to [filter the attribute by](#filters-autocomplete). 1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical `AND`. @@ -86,7 +86,7 @@ You can filter issues and merge requests by specific terms included in titles or ### Filtering by ID -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/39908) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. You can filter the **Issues** list to individual instances by their ID. For example, enter filter `#10` to return only issue 10. The same applies to the **Merge Requests** list. Enter filter `#30` to return only merge request 30. @@ -110,6 +110,18 @@ the dropdown) **Approved-By** and select the user.  +## Filters autocomplete + +GitLab provides many filters across many pages (issues, merge requests, epics, +and pipelines among others) which you can use to narrow down your search. When +using the filter functionality, you can start typing characters to bring up +relevant users or other attributes. + +For performance optimization, there is a requirement of a minimum of three +characters to begin your search. For example, if you want to search for +issues that have the assignee "Simone Presley", you'll need to type at +least "Sim" before autocomplete gives any relevant results. + ## Search history You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser. @@ -149,9 +161,9 @@ You can search through your projects from the left menu, by clicking the menu ba On the field **Filter by name**, type the project or group name you want to find, and GitLab will filter them for you as you type. -You can also look for the projects you starred (**Starred projects**), and **Explore** all +You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**), and **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, -through **Trending**, best rated with **Most starts**, or **All** of them. +through **Trending**, best rated with **Most stars**, or **All** of them. You can also sort them by **Name**, **Last created**, **Oldest created**, **Last updated**, **Oldest updated**, **Owner**, and choose to hide or show **archived projects**: diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index fa466fdb3b9..efa374cf1c3 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -8,7 +8,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' GitLab has many useful keyboard shortcuts to make it easier to access different features. You can see a modal listing keyboard shortcuts within GitLab itself by pressing <kbd>?</kbd>, or clicking **Keyboard shortcuts** in the Help menu at the top right. -From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/issues/22113), +In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22113), keyboard shortcuts can be disabled using the **Enable**/**Disable** toggle in this modal window. The [Global Shortcuts](#global-shortcuts) work from any area of GitLab, but you must diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 96c8dba11e5..68e5c5ac92c 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -129,7 +129,7 @@ different visibility level from the dropdown menu. ## Snippet comments -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/12910) in GitLab 9.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12910) in GitLab 9.2. With GitLab Snippets you engage in a conversation about that piece of code, facilitating the collaboration among users. @@ -147,8 +147,8 @@ snippet was created using the GitLab web interface the original line ending is W > Introduced in GitLab 10.8. -Public snippets can not only be shared, but also embedded on any website. This -allows us to reuse a GitLab snippet in multiple places and any change to the source +Public snippets can not only be shared, but also embedded on any website. With +this, you can reuse a GitLab snippet in multiple places and any change to the source is automatically reflected in the embedded snippet. To embed a snippet, first make sure that: @@ -172,6 +172,6 @@ Here's how an embedded snippet looks like: <script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script> -Embedded snippets are displayed with a header that shows the file name is defined, +Embedded snippets are displayed with a header that shows the file name if it's defined, the snippet size, a link to GitLab, and the actual snippet content. Actions in the header allow users to see the snippet in raw format and download it. diff --git a/doc/user/todos.md b/doc/user/todos.md index 84a7b6afdac..5d3e3e62652 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -1,5 +1,8 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/workflow/todos.html' +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # GitLab To-Do List |
