diff options
Diffstat (limited to 'doc/user')
300 files changed, 3406 insertions, 2730 deletions
diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 653c67ed197..85ad0667322 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -45,7 +45,7 @@ There are 3 ways to resolve an abuse report, with a button for each method: The following is an example of the **Abuse Reports** page: - + ### Blocking users diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 1bca1751d2e..144ee2dbf98 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -66,4 +66,4 @@ Activating a user changes the user's state to active and consumes a [seat](../../subscriptions/self_managed/index.md#billable-users). NOTE: -A deactivated user can also activate their account themselves by simply logging back in via the UI. +A deactivated user can also activate their account themselves by logging back in via the UI. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 053cee82634..0ae6e41264c 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -11,8 +11,8 @@ type: howto GitLab administrators are responsible for the overall security of their instance. To assist, GitLab provides a Credentials inventory to keep track of all the credentials that can be used to access their self-managed instance. -Using Credentials inventory, you can see all the personal access tokens (PAT), SSH keys, and GPG keys -that exist in your GitLab instance. In addition, you can [revoke](#revoke-a-users-personal-access-token) +Using Credentials inventory, you can see all the personal access tokens (PAT), SSH keys, and GPG keys +that exist in your GitLab instance. In addition, you can [revoke](#revoke-a-users-personal-access-token) and [delete](#delete-a-users-ssh-key) and see: - Who they belong to. @@ -56,12 +56,16 @@ The instance then notifies the user. ## Review existing GPG keys > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282429) in GitLab 13.10. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-gpg-keys-view). +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/292961) in GitLab 13.11. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-gpg-keys-view). -You can view all existing GPG in your GitLab instance by navigating to the +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can view all existing GPG in your GitLab instance by navigating to the credentials inventory GPG Keys tab, as well as the following properties: - Who the GPG key belongs to. @@ -72,10 +76,10 @@ credentials inventory GPG Keys tab, as well as the following properties: ### Enable or disable the GPG keys view -Enabling or disabling the GPG keys view is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +Enabling or disabling the GPG keys view is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can opt to disable it. To enable it: diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 26551d828bf..b4b33df37bf 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -16,7 +16,7 @@ Every project directly under the group namespace will be available to the user if they have access to them. For example: - Public projects, in the group will be available to every signed-in user, if all enabled [project features](../project/settings/index.md#sharing-and-permissions) - are set to **Everyone With Access**. + except for GitLab Pages are set to **Everyone With Access**. - Private projects will be available only if the user is a member of the project. Repository and database information that are copied over to each new project are diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index f41170da975..e5132ef4e96 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -70,6 +70,12 @@ breaking communication between **primary** and **secondary** nodes when using HTTPS, customize your Internal URL to point to a load balancer with TLS terminated at the load balancer. +WARNING: +Starting with GitLab 13.3 and [until 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/325522), +using an internal URL that is not accessible to the users will result in the +OAuth authorization flow not working properly, as the users will get redirected +to the internal URL instead of the external one. + ## Multiple secondary nodes behind a load balancer In GitLab 11.11, **secondary** nodes can use identical external URLs as long as diff --git a/doc/user/admin_area/img/abuse_reports_page.png b/doc/user/admin_area/img/abuse_reports_page.png Binary files differdeleted file mode 100644 index 30e932211cb..00000000000 --- a/doc/user/admin_area/img/abuse_reports_page.png +++ /dev/null diff --git a/doc/user/admin_area/img/abuse_reports_page_v13_11.png b/doc/user/admin_area/img/abuse_reports_page_v13_11.png Binary files differnew file mode 100644 index 00000000000..bcb2aec9e64 --- /dev/null +++ b/doc/user/admin_area/img/abuse_reports_page_v13_11.png diff --git a/doc/user/admin_area/img/admin_area_settings_button.png b/doc/user/admin_area/img/admin_area_settings_button.png Binary files differdeleted file mode 100644 index 5b969ecd668..00000000000 --- a/doc/user/admin_area/img/admin_area_settings_button.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png Binary files differindex 2486332c477..a88d80a72b6 100644 --- a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png +++ b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png diff --git a/doc/user/admin_area/img/credentials_inventory_v13_10.png b/doc/user/admin_area/img/credentials_inventory_v13_10.png Binary files differindex e41bbf35a8e..2790ca70fba 100644 --- a/doc/user/admin_area/img/credentials_inventory_v13_10.png +++ b/doc/user/admin_area/img/credentials_inventory_v13_10.png diff --git a/doc/user/admin_area/img/export_permissions_v13_11.png b/doc/user/admin_area/img/export_permissions_v13_11.png Binary files differnew file mode 100644 index 00000000000..d9bbe8c3daf --- /dev/null +++ b/doc/user/admin_area/img/export_permissions_v13_11.png diff --git a/doc/user/admin_area/img/license_details_v13_8.png b/doc/user/admin_area/img/license_details_v13_8.png Binary files differdeleted file mode 100644 index 00421d8a41d..00000000000 --- a/doc/user/admin_area/img/license_details_v13_8.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 6877148bd6d..08fcd4674dc 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -173,6 +173,8 @@ The following data is included in the export: - Path - Access level ([Project](../permissions.md#project-members-permissions) and [Group](../permissions.md#group-members-permissions)) + + #### Users statistics The **Users statistics** page provides an overview of user accounts by role. These statistics are diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 89417de4bab..85ff5f8e7b1 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -89,10 +89,7 @@ is active until the end of the license period. When that period ends, the instance will [fall back](#what-happens-when-your-license-expires) to Free-only functionality. -You can review the license details at any time in the **License** section of the -**Admin Area**. - - +You can review the license details at any time by going to **Admin Area > License**. ## Notification before the license expires @@ -102,12 +99,15 @@ license, otherwise you miss all the paid features if your license expires. ## What happens when your license expires -In case your license expires, GitLab locks down some features like Git pushes, -and issue creation, and displays a message to all administrators to inform of the expired license. +When your license expires, GitLab locks down features, like Git pushes +and issue creation. Then, your instance becomes read-only and +an expiration message is displayed to all administrators. + +For GitLab self-managed instances, you have a 14-day grace period +before this occurs. -To get back all the previous functionality, you must upload a new license. -To fall back to having only the Free features active, you must delete the -expired license(s). +- To resume functionality, upload a new license. +- To fall back to Free features, delete the expired license. ### Remove a license diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index d6ffde7be95..e8c435a2b5e 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -31,3 +31,5 @@ maintainers from allowing users to approve merge requests if they have submitted any commits to the source branch. - **Prevent users from modifying merge request approvers list**. Prevents users from modifying the approvers list in project settings or in individual merge requests. + +Also read the [project level merge request approval rules](../project/merge_requests/merge_request_approvals.md), which are affected by instance level rules. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 3d19bde9a26..29b5bdd5e05 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -8,9 +8,8 @@ type: reference # Continuous Integration and Deployment Admin settings **(FREE SELF)** In this area, you will find settings for Auto DevOps, runners, and job artifacts. -You can find it in the **Admin Area > Settings > CI/CD**. - - +You can find it in the [Admin Area](index.md) by navigating to +**Admin Area > Settings > CI/CD**. ## Auto DevOps **(FREE SELF)** diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index cbdc617d7d9..60081f2e0bd 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index --- @@ -38,7 +38,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [PlantUML](../../../administration/integration/plantuml.md) | Allow rendering of PlantUML diagrams in documents. | | [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | -| [Snowplow](../../../development/snowplow.md) | Configure the Snowplow integration. | +| [Snowplow](../../../development/snowplow/index.md) | Configure the Snowplow integration. | | [Google GKE](../../project/clusters/add_gke_clusters.md) | Google GKE integration allows you to provision GKE clusters from GitLab. | | [Amazon EKS](../../project/clusters/add_eks_clusters.md) | Amazon EKS integration allows you to provision EKS clusters from GitLab. | @@ -46,7 +46,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | -| [Repository's custom initial branch name](../../project/repository/branches/index.md#custom-initial-branch-name) | Set a custom branch name rather than master for all the new repositories created within your instance. | +| [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) | Set a custom branch name for new repositories created in your instance. | | [Repository mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. | | [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. | | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. | diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 0b9f039880a..b152787b23f 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -40,7 +40,7 @@ If this is the first time you are setting up instance-level settings for an inte When you make further changes to the instance defaults: - They are immediately applied to all groups and projects that have the integration set to use default settings. -- They are immediately applied to newer groups and projects, created since you last saved defaults for the +- They are immediately applied to newer groups and projects, created after you last saved defaults for the integration. If your instance-level default setting has the **Enable integration** toggle turned on, the integration is automatically enabled for all such groups and projects. - Groups and projects with custom settings selected for the integration are not immediately affected and may @@ -82,7 +82,7 @@ When you make further changes to the group defaults: - They are immediately applied to all subgroups and projects belonging to the group that have the integration set to use default settings. -- They are immediately applied to newer subgroups and projects, created since you last saved defaults for the +- They are immediately applied to newer subgroups and projects, even those created after you last saved defaults for the integration. If your group-level default setting has the **Enable integration** toggle turned on, the integration is automatically enabled for all such subgroups and projects. 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 30cc64ccaa0..3acfb636a13 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 @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Rate limits on issue creation +# Rate limits on issue creation **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28129) in GitLab 12.10. diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md index 54b5da35dac..1997e6b5149 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Rate limits on note creation +# Rate limits on note creation **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53637) in GitLab 13.9. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index a34a63f4543..7b2928a3873 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -23,9 +23,86 @@ You can restrict the password authentication for web interface and Git over HTTP - **Web interface**: When this feature is disabled, an [external authentication provider](../../../administration/auth/README.md) must be used. - **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) must be used to authenticate. +## Admin Mode + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. +> - It's [deployed behind the feature flag](../../../user/feature_flags.md) `:user_mode_in_session`, disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. + +When this feature is enabled, instance administrators are limited as regular users. During that period, +they do not have access to all projects, groups, or the **Admin Area** menu. + +To access potentially dangerous resources, an administrator can activate Admin Mode by: + +- Selecting the *Enable Admin Mode* button +- Trying to access any part of the UI that requires an administrator role, specifically those which call `/admin` endpoints. + +The main use case allows administrators to perform their regular tasks as a regular +user, based on their memberships, without having to set up a second account for +security reasons. + +When Admin Mode status is disabled, administrative users cannot access resources unless +they've been explicitly granted access. For example, when Admin Mode is disabled, they +get a `404` error if they try to open a private group or project, unless +they are members of that group or project. + +2FA should be enabled for administrators and is supported for the Admin Mode flow, as are +OmniAuth providers and LDAP auth. The Admin Mode status is stored in the active user +session and remains active until it is explicitly disabled (it will be disabled +automatically after a timeout otherwise). + +### Limitations of Admin Mode + +The following access methods are **not** protected by Admin Mode: + +- Git client access (SSH using public keys or HTTPS using Personal Access Tokens). +- API access using a Personal Access Token. + +In other words, administrators who are otherwise limited by Admin Mode can still use +Git clients, and access RESTful API endpoints as administrators, without additional +authentication steps. + +We may address these limitations in the future. For more information see the following epic: +[Admin mode for GitLab Administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158). + +### Troubleshooting Admin Mode + +If necessary, you can disable **Admin Mode** as an administrator by using one of these two methods: + +- **API**: + + ```shell + curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?admin_mode=false" + ``` + +- [**Rails console**](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ::Gitlab::CurrentSettings.update_attributes!(admin_mode: false) + ``` + +## Enable or disable Admin Mode + +Admin Mode 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. + +To enable it: + +```ruby +Feature.enable(:user_mode_in_session) +``` + +To disable it: + +```ruby +Feature.disable(:user_mode_in_session) +``` + ## Two-factor authentication -When this feature enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). +When this feature is enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). After the two-factor authentication is configured as mandatory, users are allowed to skip forced configuration of two-factor authentication for the configurable grace diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 0f19998749d..397f311adae 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -22,7 +22,10 @@ View pipeline duration history:  -## DORA4 Metrics +## DevOps Research and Assessment (DORA) key metrics **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. +> - Added support for [lead time for changes](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) in GitLab 13.10. Customer experience is a key metric. Users want to measure platform stability and other post-deployment performance KPIs, and set targets for customer behavior, experience, and financial @@ -41,11 +44,20 @@ performance indicators for software development teams: - Time to restore service: How long it takes an organization to recover from a failure in production. -GitLab plans to add support for all the DORA4 metrics at the project and group levels. GitLab added -the first metric, deployment frequency, at the project and group scopes for [CI/CD charts](ci_cd_analytics.md#deployment-frequency-charts), -the [Project API]( ../../api/dora4_project_analytics.md), and the [Group API]( ../../api/dora4_group_analytics.md). +### Supported metrics in GitLab + +The following table shows the supported metrics, at which level they are supported, and which GitLab version (API and UI) they were introduced: + +| Metric | Level | API version | Chart (UI) version | Comments | +| --------------- | ----------- | --------------- | ---------- | ------- | +| `deployment_frequency` | Project-level | [13.7+](../../api/dora/metrics.md) | [13.8+](#deployment-frequency-charts) | The [old API endopint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | +| `deployment_frequency` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | | +| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | To be supported | Unit in seconds. Aggregation method is median. | +| `lead_time_for_changes` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | Unit in seconds. Aggregation method is median. | +| `change_failure_rate` | Project/Group-level | To be supported | To be supported | | +| `time_to_restore_service` | Project/Group-level | To be supported | To be supported | | -## Deployment frequency charts **(ULTIMATE)** +### Deployment frequency charts **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. @@ -54,3 +66,18 @@ The **Analytics > CI/CD Analytics** page shows information about the deployment information to appear on the graphs.  + +### Lead time charts **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250329) in GitLab 13.11. + +The charts in the **Lead Time** tab show information about how long it takes +merge requests to be deployed to a production environment. + + + +Smaller values are better. Small lead times indicate fast, efficient deployment +processes. + +For time periods in which no merge requests were deployed, the charts render a +red, dashed line. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 19016c3aa26..fe091fc9899 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -24,11 +24,11 @@ Initially, no data appears. Data is populated as users comment on open merge req Code Review Analytics is available to users with Reporter access and above, and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. -To access Code Review Analytics, from your project's menu, go to **Project Analytics > Code Review**. +To access Code Review Analytics, from your project's menu, go to **Analytics > Code Review**. You can filter the list of merge requests by milestone and label. - + The table is sorted by: diff --git a/doc/user/analytics/img/code_review_analytics_v12_8.png b/doc/user/analytics/img/code_review_analytics_v12_8.png Binary files differdeleted file mode 100644 index 3b23e74130a..00000000000 --- a/doc/user/analytics/img/code_review_analytics_v12_8.png +++ /dev/null diff --git a/doc/user/analytics/img/code_review_analytics_v13_11.png b/doc/user/analytics/img/code_review_analytics_v13_11.png Binary files differnew file mode 100644 index 00000000000..e337afa3ace --- /dev/null +++ b/doc/user/analytics/img/code_review_analytics_v13_11.png diff --git a/doc/user/analytics/img/issues_created_per_month_v12_8.png b/doc/user/analytics/img/issues_created_per_month_v12_8.png Binary files differdeleted file mode 100644 index fccfa949779..00000000000 --- a/doc/user/analytics/img/issues_created_per_month_v12_8.png +++ /dev/null diff --git a/doc/user/analytics/img/issues_created_per_month_v13_11.png b/doc/user/analytics/img/issues_created_per_month_v13_11.png Binary files differnew file mode 100644 index 00000000000..01ebde5a54d --- /dev/null +++ b/doc/user/analytics/img/issues_created_per_month_v13_11.png diff --git a/doc/user/analytics/img/lead_time_chart_v13_11.png b/doc/user/analytics/img/lead_time_chart_v13_11.png Binary files differnew file mode 100644 index 00000000000..5577e215711 --- /dev/null +++ b/doc/user/analytics/img/lead_time_chart_v13_11.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index fe35d575373..6e3c9cf7a5f 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -23,7 +23,7 @@ as described in ([Measuring DevOps Performance](https://devops.com/measuring-dev - MTTD (Mean Time to Detect): The average duration that a bug goes undetected in production. GitLab measures MTTD from deployment of bug to issue creation. - MTTM (Mean Time To Merge): The average lifespan of a merge request. GitLab measures MTTM from merge request creation to merge request merge (and closed/un-merged merge requests are excluded). For more information, see [Merge Request Analytics](merge_request_analytics.md). - MTTR (Mean Time to Recover/Repair/Resolution/Resolve/Restore): The average duration that a bug is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. -- Lead time: The duration of the work itself. Often displayed in combination with "cycle time." GitLab measures from issue first merge request creation to issue close. Note: Obviously work started before the creation of the first merge request. We plan to start measuring from "issue first commit" as a better proxy, although still imperfect. GitLab displays lead time in [Value Stream Analytics](value_stream_analytics.md). +- Lead time: The duration of the work itself. Often displayed in combination with "cycle time." GitLab measures from issue first merge request creation to issue close. Note: Work started before the creation of the first merge request. We plan to start measuring from "issue first commit" as a better proxy, although still imperfect. GitLab displays lead time in [Value Stream Analytics](value_stream_analytics.md). - Throughput: The number of issues closed or merge requests merged (not closed) in some period of time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). - Value Stream: The entire work process that is followed to deliver value to customers. For example, the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). - Velocity: The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points/weight of issues closed in a given period of time. @@ -46,11 +46,13 @@ in one place. The following analytics features are available at the group level: - [Contribution](../group/contribution_analytics/index.md). **(PREMIUM)** +- [DevOps Adoption](../group/devops_adoption/index.md). **(ULTIMATE)** - [Insights](../group/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** -- [Productivity](productivity_analytics.md) **(PREMIUM)** -- [Repositories](../group/repositories_analytics/index.md) **(PREMIUM)** +- [Productivity](productivity_analytics.md). **(PREMIUM)** +- [Repositories](../group/repositories_analytics/index.md). **(PREMIUM)** - [Value Stream](../group/value_stream_analytics/index.md). **(PREMIUM)** +- [Application Security](../application_security/security_dashboard/#group-security-dashboard). **(ULTIMATE)** ## Project-level analytics @@ -64,3 +66,10 @@ The following analytics features are available at the project level: [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** - [Repository](repository_analytics.md). **(FREE)** - [Value Stream](value_stream_analytics.md). **(FREE)** +- [Application Security](../application_security/security_dashboard/#project-security-dashboard). **(ULTIMATE)** + +## User-configurable analytics + +The following analytics features are available for users to create personalized views: + +- [Application Security](../application_security/security_dashboard/#security-center). **(ULTIMATE)** diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 6c6911ff4f4..b77a25a9d62 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -13,7 +13,7 @@ Issue Analytics is a bar graph which illustrates the number of issues created ea The default time span is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your project sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart, navigate to your project sidebar and select **Analytics > Issue**. Hover over each bar to see the total number of issues. @@ -31,7 +31,7 @@ You can change the total number of months displayed by setting a URL parameter. For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` shows a total of 15 months for the chart in the GitLab.org group. - + ## Drill into the information diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 6c41d93d51f..2af98492ee7 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -58,19 +58,13 @@ GitLab provides the ability to filter analytics based on a date range. To filter 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. +- **Cycle time**: median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages).) ## How the stages are measured -Value Stream Analytics records stage time and data based on the project issues with the -exception of the staging stage, where only data deployed to -production are measured. - -Specifically, if your CI is not set up and you have not defined a [production environment](#how-the-production-environment-is-identified), then you will not have any -data for this stage. +Value Stream Analytics uses start events and stop events to measure the time that an Issue or MR spends in each stage. +For example, a stage might start when one label is added to an issue, and end when another label is added. +Items are not included in the stage time calculation if they have not reached the stop event. Each stage of Value Stream Analytics is further described in the table below. @@ -103,14 +97,8 @@ In short, the Value Stream Analytics dashboard tracks data related to [GitLab fl ## How the production environment is identified -Value Stream Analytics identifies production environments by looking for project [environments](../../ci/yaml/README.md#environment) with a name matching any of these patterns: - -- `prod` or `prod/*` -- `production` or `production/*` - -These patterns are not case-sensitive. - -You can change the name of a project environment in your GitLab CI/CD configuration. +Value Stream Analytics identifies production environments based on +[the deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). ## Example workflow diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 036da0068b5..dfb7e12a8be 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -63,6 +63,7 @@ Examples of both configurations can be found here: - [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) +- [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/graphql-api-fuzzing-example) WARNING: GitLab 14.0 will require that you place API fuzzing configuration files (for example, @@ -73,10 +74,6 @@ starting in GitLab 14.0, GitLab will not check your repository's root for config ### Configuration form > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-api-fuzzing-configuration-form). **(ULTIMATE)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -102,25 +99,6 @@ to your project's `.gitlab-ci.yml` file where you can paste the YAML configurati Select **Copy code only** to copy the snippet to your clipboard and close the modal. -#### Enable or disable API Fuzzing configuration form **(ULTIMATE)** - -The API Fuzzing configuration form is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:api_fuzzing_configuration_ui) -``` - -To disable it: - -```ruby -Feature.disable(:api_fuzzing_configuration_ui) -``` - ### OpenAPI Specification > Support for OpenAPI Specification v3 was @@ -465,7 +443,7 @@ To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab - `FUZZAPI_HTTP_USERNAME`: The username for authentication. - `FUZZAPI_HTTP_PASSWORD`: The password for authentication. -For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) +For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables) (for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable as the value for `FUZZAPI_HTTP_PASSWORD`: @@ -500,7 +478,7 @@ outgoing HTTP requests. Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: -1. [Create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), +1. [Create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables), for example `TEST_API_BEARERAUTH`, with the value `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the @@ -839,7 +817,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-variables): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables): ```yaml include: @@ -975,7 +953,7 @@ faults it reports. ## Viewing fuzzing faults The API Fuzzing analyzer produces a JSON report that is collected and used -[to populate the faults into GitLab vulnerability screens](../index.md#view-details-of-an-api-fuzzing-vulnerability). +[to populate the faults into GitLab vulnerability screens](#view-details-of-an-api-fuzzing-vulnerability). Fuzzing faults show up as vulnerabilities with a severity of Unknown. The faults that API fuzzing finds require manual investigation and aren't associated with a specific @@ -984,8 +962,42 @@ they should be fixed. See [handling false positives](#handling-false-positives) for information about configuration changes you can make to limit the number of false positives reported. -For additional information, see -[View details of an API Fuzzing vulnerability](../index.md#view-details-of-an-api-fuzzing-vulnerability). +### View details of an API Fuzzing vulnerability + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +Faults detected by API Fuzzing occur in the live web application, and require manual investigation +to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a +severity of Unknown. To facilitate investigation of the fuzzing faults, detailed information is +provided about the HTTP messages sent and received along with a description of the modification(s) +made. + +Follow these steps to view details of a fuzzing fault: + +1. You can view faults in a project, or a merge request: + + - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + page. This page shows all vulnerabilities from the default branch only. + - In a merge request, go the merge request's **Security** section and click the **Expand** + button. API Fuzzing faults are available in a section labeled + **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault + details. + +1. Click the fault's title to display the fault's details. The table below describes these details. + + | Field | Description | + |:--------------------|:----------------------------------------------------------------------------------------| + | Description | Description of the fault including what was modified. | + | Project | Namespace and project in which the vulnerability was detected. | + | Method | HTTP method used to detect the vulnerability. | + | URL | URL at which the vulnerability was detected. | + | Request | The HTTP request that caused the fault. | + | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Actual Response | Response received from fuzzed request. | + | Evidence | How we determined a fault occurred. | + | Identifiers | The fuzzing check used to find this fault. | + | Severity | Severity of the finding is always Unknown. | + | Scanner Type | Scanner used to perform testing. | ### Security Dashboard @@ -1016,7 +1028,7 @@ False positives can be handled in two ways: Checks perform testing of a specific type and can be turned on and off for specific configuration profiles. The provided [configuration files](#configuration-files) define several profiles that you can use. The profile definition in the configuration file lists all the checks that are active -during a scan. To turn off a specific check, simply remove it from the profile definition in the +during a scan. To turn off a specific check, remove it from the profile definition in the configuration file. The profiles are defined in the `Profiles` section of the configuration file. Example profile definition: @@ -1131,6 +1143,51 @@ Profiles: UnicodeFuzzing: true ``` +## Troubleshooting + +### Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema + +At the start of an API Fuzzing job the OpenAPI specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI specification has validation errors. Errors can be introduced when creating an OpenAPI specification manually, and also when the schema is generated. + +For OpenAPI specifications that are generated automatically validation errors are often the result of missing code annotations. + +**Error message** + +- In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/323939), `Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema` + - `OpenAPI 2.0 schema validation error ...` + - `OpenAPI 3.0.x schema validation error ...` + +**Solution** + +**For generated OpenAPI specifications** + +1. Identify the validation errors. + 1. Use the [Swagger Editor](https://editor.swagger.io/) to identify validation problems in your specification. The visual nature of the Swagger Editor makes it easier to understand what needs to change. + 1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Note that JSON Schema validation messages might not be easy to understand. This is why we recommend the use of editors to validate schema documents. +1. Review the documentation for the OpenAPI generation your framework/tech stack is using. Identify the changes needed to produce a correct OpenAPI document. +1. Once the validation issues are resolved, re-run your pipeline. + +**For manually created OpenAPI Specifications** + +1. Identify the validation errors. + 1. The simplest solution is to use a visual tool to edit and validate the OpenAPI document. For example the [Swagger Editor](https://editor.swagger.io/) will point out schema errors and possible solutions. + 1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Correct each of the validation failures and then resubmit the OpenAPI doc. Note that JSON Schema validation message might not be easy to understand. This is why we recommend the use of editors to validate document. +1. Once the validation issues are resolved, re-run your pipeline. + +### Failed to start scanner session (version header not found) + +The API Fuzzing engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `apifuzzer_fuzz` job. A common cause of this issue is changing the `FUZZAPI_API` variable from its default. + +**Error message** + +- In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/323939), `Failed to start scanner session (version header not found).` +- In GitLab 13.10 and earlier, `API Security version header not found. Are you sure that you are connecting to the API Security server?`. + +**Solution** + +- Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. +- If removing the variable is not possible, check to see if this value has changed in the latest version of the [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. + <!-- ### Target Container diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 909065d7907..fcf5c81db74 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -103,7 +103,7 @@ The included template: (see [requirements](#requirements)) and scans it for possible vulnerabilities. GitLab saves the results as a -[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning) +[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning) that you can download and analyze later. When downloading, you always receive the most-recent artifact. @@ -241,7 +241,7 @@ container_scanning: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Vulnerability allowlisting @@ -250,8 +250,85 @@ To allowlist specific vulnerabilities, follow these steps: 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 allowlisted vulnerabilities in a YAML file named `vulnerability-allowlist.yml`. This must use - the format described in the [allowlist example file](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/raw/master/testdata/vulnerability-allowlist.yml). -1. Add the `vulnerability-allowlist.yml` file to your project's Git repository. + the format described in [vulnerability-allowlist.yml data format](#vulnerability-allowlistyml-data-format). +1. Add the `vulnerability-allowlist.yml` file to the root folder of your project's Git repository. + +#### vulnerability-allowlist.yml data format + +The `vulnerability-allowlist.yml` file is a YAML file that specifies a list of CVE IDs of vulnerabilities that are **allowed** to exist, because they're _false positives_, or they're _not applicable_. + +If a matching entry is found in the `vulnerability-allowlist.yml` file, the following happens: + +- The vulnerability **is not included** when the analyzer generates the `gl-container-scanning-report.json` file. +- The Security tab of the pipeline **does not show** the vulnerability. It is not included in the JSON file, which is the source of truth for the Security tab. + +Example `vulnerability-allowlist.yml` file: + +```yaml +generalallowlist: + CVE-2019-8696: + CVE-2014-8166: cups + CVE-2017-18248: +images: + registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256: + CVE-2018-4180: + your.private.registry:5000/centos: + CVE-2015-1419: libxml2 + CVE-2015-1447: +``` + +This example excludes from `gl-container-scanning-report.json`: + +1. All vulnerabilities with CVE IDs: _CVE-2019-8696_, _CVE-2014-8166_, _CVE-2017-18248_. +1. All vulnerabilities found in the `registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256` container image with CVE ID _CVE-2018-4180_. +1. All vulnerabilities found in `your.private.registry:5000/centos` container with CVE IDs _CVE-2015-1419_, _CVE-2015-1447_. + +##### File format + +- `generalallowlist` block allows you to specify CVE IDs globally. All vulnerabilities with matching CVE IDs are excluded from the scan report. + +- `images` block allows you to specify CVE IDs for each container image independently. All vulnerabilities from the given image with matching CVE IDs are excluded from the scan report. The image name is retrieved from one of the environment variables used to specify the Docker image to be scanned, such as `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` or `DOCKER_IMAGE`. The image provided in this block **must** match this value and **must not** include the tag value. For example, if you specify the image to be scanned using `DOCKER_IMAGE=alpine:3.7`, then you would use `alpine` in the `images` block, but you cannot use `alpine:3.7`. + + You can specify container image in multiple ways: + + - as image name only (ie. `centos`). + - as full image name with registry hostname (ie. `your.private.registry:5000/centos`). + - as full image name with registry hostname and sha256 label (ie. `registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256`). + +NOTE: +The string after CVE ID (`cups` and `libxml2` in the previous example) is an optional comment format. It has **no impact** on the handling of vulnerabilities. You can include comments to describe the vulnerability. + +##### Container scanning job log format + +You can verify the results of your scan and the correctness of your `vulnerability-allowlist.yml` file by looking +at the logs that are produced by the container scanning analyzer in `container_scanning` job details. + +The log contains a list of found vulnerabilities as a table, for example: + +```plainttext ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| STATUS | CVE SEVERITY | PACKAGE NAME | PACKAGE VERSION | CVE DESCRIPTION | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| Approved | High CVE-2019-3462 | apt | 1.4.8 | Incorrect sanitation of the 302 redirect field in HTTP transport metho | +| | | | | d of apt versions 1.4.8 and earlier can lead to content injection by a | +| | | | | MITM attacker, potentially leading to remote code execution on the ta | +| | | | | rget machine. | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| Unapproved | Medium CVE-2020-27350 | apt | 1.4.8 | APT had several integer overflows and underflows while parsing .deb pa | +| | | | | ckages, aka GHSL-2020-168 GHSL-2020-169, in files apt-pkg/contrib/extr | +| | | | | acttar.cc, apt-pkg/deb/debfile.cc, and apt-pkg/contrib/arfile.cc. This | +| | | | | issue affects: apt 1.2.32ubuntu0 versions prior to 1.2.32ubuntu0.2; 1 | +| | | | | .6.12ubuntu0 versions prior to 1.6.12ubuntu0.2; 2.0.2ubuntu0 versions | +| | | | | prior to 2.0.2ubuntu0.2; 2.1.10ubuntu0 versions prior to 2.1.10ubuntu0 | +| | | | | .1; | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| Unapproved | Medium CVE-2020-3810 | apt | 1.4.8 | Missing input validation in the ar/tar implementations of APT before v | +| | | | | ersion 2.1.2 could result in denial of service when processing special | +| | | | | ly crafted deb files. | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +``` + +Vulnerabilities in the log are marked as `Approved` when the corresponding CVE ID is added to the `vulnerability-allowlist.yml` file. ### Running container scanning in an offline environment diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 94a7d5268b7..e9097836d83 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -109,7 +109,7 @@ There are two types of jobs: Here's our current suggestion for configuring your fuzz target's timeout: - Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (asynchronous) fuzzing - jobs. This is `master` by default. + jobs. This is normally the default branch. - Use regression or short-running fuzzing jobs for other branches or merge requests. This suggestion helps find new bugs on the development branch and catch old bugs in merge requests @@ -121,10 +121,10 @@ any option available in the underlying fuzzing engine. ### Available CI/CD variables -| CI/CD variable | Description | -|-----------------------|--------------------------------------------------------------------| -| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | -| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | +| CI/CD variable | Description | +|-----------------------|--------------------------------------------------------------------------------| +| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. This is normally the default branch. | +| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | | `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | The files in the seed corpus (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new @@ -141,7 +141,7 @@ The `gitlab-cov-fuzz` tool emits a JSON report file. For more information, see t [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). You can download the JSON report file from the CI pipelines page. For more information, see -[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#downloading-artifacts). +[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). Here's an example coverage fuzzing report: diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md new file mode 100644 index 00000000000..48b48392e65 --- /dev/null +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -0,0 +1,64 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, howto +--- + +# Dynamic Application Security Testing (DAST) Troubleshooting **(ULTIMATE)** + +The following troubleshooting scenarios have been collected from customer support cases. If you +experience a problem not addressed here, or the information here does not fix your problem, create a +support ticket. For more details, see the [GitLab Support](https://about.gitlab.com/support/) page. + +## Running out of memory + +By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25% +of the total memory on the host. +Since it keeps most of its information in memory during a scan, +it's possible for DAST to run out of memory while scanning large applications. +This results in the following error: + +```plaintext +[zap.out] java.lang.OutOfMemoryError: Java heap space +``` + +Fortunately, it's straightforward to increase the amount of memory available +for DAST by using the `DAST_ZAP_CLI_OPTIONS` CI/CD variable: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_ZAP_CLI_OPTIONS: "-Xmx3072m" +``` + +This example allocates 3072 MB to DAST. +Change the number after `-Xmx` to the required memory amount. + +## DAST job exceeding the job timeout + +If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some +tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). + +## Getting warning message `gl-dast-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +## Getting error `dast job: chosen stage does not exist` when including DAST CI template + +To avoid overwriting stages from other CI files, newer versions of the DAST CI template do not +define stages. If you recently started using `DAST.latest.gitlab-ci.yml` or upgraded to a new major +release of GitLab and began receiving this error, you must define a `dast` stage with your other +stages. Note that you must have a running application for DAST to scan. If your application is set +up in your pipeline, it must be deployed in a stage _before_ the `dast` stage: + +```yaml +stages: + - deploy # DAST needs a running application to scan + - dast + +include: + - template: DAST.latest.gitlab-ci.yml +``` diff --git a/doc/user/application_security/dast/img/dast_v13_4.png b/doc/user/application_security/dast/img/dast_v13_4.png Binary files differdeleted file mode 100644 index d9c1d1b5c66..00000000000 --- a/doc/user/application_security/dast/img/dast_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 209dd7ad251..d3f679fe9dd 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -7,125 +7,142 @@ 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. +If you deploy your web application into a new environment, your application may +become exposed to new types of attacks. For example, misconfigurations of your +application server or incorrect assumptions about security controls may not be +visible from the source code. -Your application may be exposed to a new category of attacks once deployed into a new environment. For -example, application server misconfigurations or incorrect assumptions about security controls may -not be visible from source code alone. Dynamic Application Security Testing (DAST) checks an -application for these types of vulnerabilities in a deployed environment. GitLab DAST uses the -popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) to analyze your running -web application. +Dynamic Application Security Testing (DAST) examines applications for +vulnerabilities like these in deployed environments. DAST uses the open source +tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. NOTE: -The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) -explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your -organization. +To learn how four of the top six attacks were application-based and how +to protect your organization, download our +["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) +whitepaper. -In GitLab, DAST is commonly initiated by a merge request and runs as a job in the CI/CD pipeline. -You can also run a DAST scan on demand, outside the CI/CD pipeline. Your running web application is -analyzed for known vulnerabilities. GitLab checks the DAST report, compares the vulnerabilities -found between the source and target branches, and shows any relevant findings on the merge request. +You can use DAST to examine your web applications: -Note that this comparison logic uses only the latest pipeline executed for the target branch's base -commit. Running the pipeline on any other commit has no effect on the merge request. +- When initiated by a merge request, running as CI/CD pipeline job. +- On demand, outside the CI/CD pipeline. - +After DAST creates its report, GitLab evaluates it for discovered +vulnerabilities between the source and target branches. Relevant +findings are noted in the merge request. -## Enable DAST +The comparison logic uses only the latest pipeline executed for the target +branch's base commit. Running the pipeline on other commits has no effect on +the merge request. + +## Prerequisite -### Prerequisites +To use DAST, ensure you're using GitLab Runner with the +[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -- GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +## Enable DAST To enable DAST, either: -- Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast), provided by - [Auto DevOps](../../../topics/autodevops/index.md). -- [Include the DAST template](#dast-cicd-template) in your existing `.gitlab-ci.yml` file. +- Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast) (provided + by [Auto DevOps](../../../topics/autodevops/index.md)). +- Manually [include the DAST template](#include-the-dast-template) in your existing + `.gitlab-ci.yml` file. -### DAST CI/CD template +### Include the DAST template -The DAST job is defined in a CI/CD template file you reference in your CI/CD configuration file. The -template is included with GitLab. Updates to the template are provided with GitLab upgrades. You -benefit from any improvements and additions. +If you want to manually add DAST to your application, the DAST job is defined +in a CI/CD template file. Updates to the template are provided with GitLab +upgrades, allowing you to benefit from any improvements and additions. -The following templates are available: +To include the DAST template: -- [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): - Stable version of the DAST CI/CD template. -- [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): - Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) - in GitLab 13.8). Please note that the latest version may include breaking changes. Check the - [DAST troubleshooting guide](#troubleshooting) if you experience problems. +1. Select the CI/CD template you want to use: -Use the stable template unless you need a feature provided only in the latest template. + - [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): + Stable version of the DAST CI/CD template. + - [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): + Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) + in GitLab 13.8). -See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) -on template versioning for more information. + WARNING: + The latest version of the template may include breaking changes. Use the + stable template unless you need a feature provided only in the latest template. -#### Include the DAST template + For more information about template versioning, see the + [CI/CD documentation](../../../development/cicd/templates.md#latest-version). -The method of including the DAST template depends on the GitLab version: +1. Add a `dast` stage to your GitLab CI stages configuration: -- In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate) the - `DAST.gitlab-ci.yml` template. + ```yaml + stages: + - dast + ``` - Add the following to your `.gitlab-ci.yml` file: +1. Add the template to GitLab, based on your version of GitLab: - ```yaml - include: - - template: DAST.gitlab-ci.yml + - In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate) + the template by adding the following to your `.gitlab-ci.yml` file: - variables: - DAST_WEBSITE: https://example.com - ``` + ```yaml + include: + - template: <template_file.yml> -- In GitLab 11.8 and earlier, copy the template's content into your `.gitlab_ci.yml` file. + variables: + DAST_WEBSITE: https://example.com + ``` -#### Template options + - In GitLab 11.8 and earlier, add the contents of the template to your + `.gitlab_ci.yml` file. -Running a DAST scan requires a URL. There are two ways to define the URL to be scanned by DAST: +1. Define the URL to be scanned by DAST by using one of these methods: -1. Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). + - Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). + If set, this value takes precedence. -1. Add it in an `environment_url.txt` file at the root of your project. - This is useful for testing in dynamic environments. To run DAST against an application - dynamically created during a GitLab CI/CD pipeline, a job that runs prior to the DAST scan must - persist the application's domain in an `environment_url.txt` file. DAST automatically parses the - `environment_url.txt` file to find its scan target. + - Add the URL in an `environment_url.txt` file at the root of your project. This is + useful for testing in dynamic environments. To run DAST against an application + dynamically created during a GitLab CI/CD pipeline, a job that runs prior to + the DAST scan must persist the application's domain in an `environment_url.txt` + file. DAST automatically parses the `environment_url.txt` file to find its + scan target. - For example, in a job that runs prior to DAST, you could include code that looks similar to: + For example, in a job that runs prior to DAST, you could include code that + looks similar to: - ```yaml - script: - - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.domain.com > environment_url.txt - artifacts: - paths: [environment_url.txt] - when: always - ``` - - You can see an example of this in our [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) file. + ```yaml + script: + - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.domain.com > environment_url.txt + artifacts: + paths: [environment_url.txt] + when: always + ``` -If both values are set, the `DAST_WEBSITE` value takes precedence. + You can see an example of this in our + [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) + file. The included template creates a `dast` job in your CI/CD pipeline and scans your project's running application for possible vulnerabilities. The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) -that you can later download and analyze. Due to implementation limitations we +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast) +that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) -is used to run the tests on the specified URL and scan it for possible vulnerabilities. +is used to run the tests on the specified URL and scan it for possible +vulnerabilities. By default, the DAST template uses the latest major version of the DAST Docker image. Using the `DAST_VERSION` variable, you can choose how DAST updates: -- Automatically update DAST with new features and fixes by pinning to a major version (such as `1`). +- Automatically update DAST with new features and fixes by pinning to a major + version (such as `1`). - Only update fixes by pinning to a minor version (such as `1.6`). - Prevent all updates by pinning to a specific version (such as `1.6.4`). -Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. +Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) +page. ## Deployment options @@ -145,7 +162,7 @@ on how to configure Review Apps for DAST. If your application utilizes Docker containers you have another option for deploying and scanning with DAST. After your Docker build job completes and your image is added to your container registry, you can utilize the image as a -[service](../../../ci/docker/using_docker_images.md#what-is-a-service). +[service](../../../ci/services/index.md). By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. @@ -154,7 +171,7 @@ stages: - build - dast -include: +include: - template: DAST.gitlab-ci.yml # Deploys the container to the GitLab container registry @@ -261,7 +278,7 @@ that you periodically confirm the scanner's authentication is still working as t time due to authentication changes to the application. Create masked CI/CD variables to pass the credentials that DAST uses. -To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). +To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables). Note that the key of the username variable must be `DAST_USERNAME` and the key of the password variable must be `DAST_PASSWORD`. @@ -287,7 +304,7 @@ variables: ``` The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. @@ -459,16 +476,14 @@ variables: #### Import API specification from a file -If your API specification is in your repository, you can provide the specification's -filename directly as the target. The specification file is expected to be in the -`/zap/wrk` directory. +If your API specification file is in your repository, you can provide its filename as the target. +The API specification file must be in the `/zap/wrk` directory. ```yaml dast: - script: + before_script: - mkdir -p /zap/wrk - cp api-specification.yml /zap/wrk/api-specification.yml - - /analyze -t $DAST_WEBSITE variables: GIT_STRATEGY: fetch DAST_API_SPECIFICATION: api-specification.yml @@ -486,6 +501,12 @@ host referenced may be different than the host of the API's review instance. This can cause incorrect URLs to be imported, or a scan on an incorrect host. Use the `DAST_API_HOST_OVERRIDE` CI/CD variable to override these values. +WARNING: +When using the API host override feature, you cannot use the `$DAST_WEBSITE` variable to override the hostname. +A host override is _only_ supported when importing the API specification from a URL. Attempts to override the +host throw an error when the API specification is imported from a file. This is due to a limitation in the +ZAP OpenAPI extension. + For example, with a OpenAPI V3 specification containing: ```yaml @@ -505,10 +526,6 @@ variables: DAST_API_HOST_OVERRIDE: api-test.host.com ``` -Note that using a host override is ONLY supported when importing the API specification from a URL. -It doesn't work and is ignored when importing the specification from a file. This is due to a -limitation in the ZAP OpenAPI extension. - #### Authentication using headers Tokens in request headers are often used as a way to authenticate API requests. @@ -526,7 +543,8 @@ variables: ### URL scan -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/273141) in GitLab 13.11. A URL scan allows you to specify which parts of a website are scanned by DAST. @@ -550,26 +568,19 @@ category/shoes/page1.html ``` To scan the URLs in that file, set the CI/CD variable `DAST_PATHS_FILE` to the path of that file. +The file can be checked into the project repository or generated as an artifact by a job that +runs before DAST. + +By default, DAST scans do not clone the project repository. Instruct the DAST job to clone +the project by setting `GIT_STRATEGY` to fetch. Give a file path relative to `CI_PROJECT_DIR` to `DAST_PATHS_FILE`. ```yaml include: - template: DAST.gitlab-ci.yml variables: - DAST_PATHS_FILE: url_file.txt -``` - -By default, DAST scans do not clone the project repository. If the file is checked in to the project, instruct the DAST job to clone the project by setting GIT_STRATEGY to fetch. The file is expected to be in the `/zap/wrk` directory. - -```yaml -dast: - script: - - mkdir -p /zap/wrk - - cp url_file.txt /zap/wrk/url_file.txt - - /analyze -t $DAST_WEBSITE - variables: - GIT_STRATEGY: fetch - DAST_PATHS_FILE: url_file.txt + GIT_STRATEGY: fetch + DAST_PATHS_FILE: url_file.txt # url_file.txt lives in the root directory of the project ``` ##### Use `DAST_PATHS` CI/CD variable @@ -584,7 +595,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_PATHS=/page1.html,/category1/page1.html,/page3.html + DAST_PATHS: "/page1.html,/category1/page1.html,/page3.html" ``` When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: @@ -643,7 +654,7 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | | `DAST_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | | `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | +| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/293595) in GitLab 13.8, to be removed in 14.0. Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | @@ -656,7 +667,7 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be in `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | | `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | @@ -708,6 +719,22 @@ 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" ``` +### Bleeding-edge vulnerability definitions + +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` CI/CD variable as shown in the +following configuration: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_INCLUDE_ALPHA_VULNERABILITIES: "true" +``` + ### Cloning the project's repository The DAST job does not require the project's repository to be present when running, so by default @@ -747,7 +774,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: -- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites). +- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisite). - Docker Container Registry with a locally available copy of the DAST [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry). @@ -798,8 +825,9 @@ Alternatively, you can use the CI/CD variable `SECURE_ANALYZERS_PREFIX` to overr > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. -> - The saved scans feature was [added](https://gitlab.com/groups/gitlab-org/-/epics/5100) in -> GitLab 13.9. +> - The saved scans feature was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5100) in GitLab 13.9. +> - The option to select a branch was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4847) in GitLab 13.10. +> - DAST branch selection [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/322672) in GitLab 13.11. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must start it manually. @@ -811,6 +839,8 @@ An on-demand DAST scan: - Is associated with your project's default branch. - Is saved on creation so it can be run later. +In GitLab 13.10 and later, you can select to run an on-demand scan against a specific branch. + ### On-demand scan modes An on-demand scan can be run in active or passive mode: @@ -843,6 +873,7 @@ To run an on-demand scan, either: 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. 1. Complete the **Scan name** and **Description** fields. +1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown. 1. In **Scanner profile**, select a scanner profile from the dropdown. 1. In **Site profile**, select a site profile from the dropdown. 1. To run the on-demand scan now, select **Save and run scan**. Otherwise select **Save scan** to @@ -877,6 +908,9 @@ To run a saved on-demand scan: 1. Select the **Saved Scans** tab. 1. In the scan's row select **Run scan**. + If the branch saved in the scan no longer exists, you must first + [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. + The on-demand DAST scan runs and the project's dashboard shows the results. ### Edit an on-demand scan @@ -911,6 +945,14 @@ A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. - **Target URL**: The URL that DAST runs against. +- **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. +- **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. +- **Authentication**: + - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. + - **Username**: The username used to authenticate to the website. + - **Password**: The password used to authenticate to the website. + - **Username form field**: The name of username field at the sign-in HTML form. + - **Password form field**: The name of password field at the sign-in HTML form. #### Site profile validation @@ -926,7 +968,7 @@ follows: - _Header validation_ requires the header `Gitlab-On-Demand-DAST` be added to the target site, with a value unique to the project. The validation process checks that the header is present, and checks its value. - + Both methods are equivalent in functionality. Use whichever is feasible. #### Create a site profile @@ -950,7 +992,9 @@ To edit an existing site profile: 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. 1. Edit the fields then select **Save profile**. -The site profile is updated with the edited details. +If a site profile is linked to a security policy, a user cannot edit the profile from this page. See +[Scan Policies](../policies/index.md) +for more information. #### Delete a site profile @@ -962,7 +1006,9 @@ To delete an existing site profile: 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. 1. Select **Delete** to confirm the deletion. -The site profile is deleted. +If a site profile is linked to a security policy, a user cannot delete the profile from this page. +See [Scan Policies](../policies/index.md) +for more information. #### Validate a site profile @@ -1084,7 +1130,9 @@ To edit a scanner profile: 1. Edit the form. 1. Select **Save profile**. -The scanner profile is updated with the edited details. +If a scanner profile is linked to a security policy, a user cannot edit the profile from this page. +See [Scan Policies](../policies/index.md) +for more information. #### Delete a scanner profile @@ -1096,7 +1144,9 @@ To delete a scanner profile: 1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. 1. Select **Delete**. -The scanner profile is deleted. +If a scanner profile is linked to a security policy, a user cannot delete the profile from this +page. See [Scan Policies](../policies/index.md) +for more information. ## Reports @@ -1145,38 +1195,6 @@ dast: - gl-dast-report.json ``` -## Security Dashboard - -The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects and pipelines. Read more about the -[Security Dashboard](../security_dashboard/index.md). - -## Bleeding-edge vulnerability definitions - -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` CI/CD variable as shown in the -following configuration: - -```yaml -include: - template: DAST.gitlab-ci.yml - -variables: - DAST_INCLUDE_ALPHA_VULNERABILITIES: "true" -``` - -## Interacting with the vulnerabilities - -Once a vulnerability is found, you can interact with it. Read more on how to -[address the vulnerabilities](../index.md#addressing-vulnerabilities). - -## Vulnerabilities database update - -For more information about the vulnerabilities database update, check the -[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). - ## Optimizing DAST By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If @@ -1188,70 +1206,3 @@ artifacts, add the following to your `gitlab-ci.yml` file: dast: dependencies: [] ``` - -## Troubleshooting - -### Running out of memory - -By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25% -of the total memory on the host. -Since it keeps most of its information in memory during a scan, -it's possible for DAST to run out of memory while scanning large applications. -This results in the following error: - -```plaintext -[zap.out] java.lang.OutOfMemoryError: Java heap space -``` - -Fortunately, it's straightforward to increase the amount of memory available -for DAST by using the `DAST_ZAP_CLI_OPTIONS` CI/CD variable: - -```yaml -include: - - template: DAST.gitlab-ci.yml - -variables: - DAST_ZAP_CLI_OPTIONS: "-Xmx3072m" -``` - -Here, DAST is being allocated 3072 MB. -Change the number after `-Xmx` to the required memory amount. - -### DAST job exceeding the job timeout - -If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). - -### Getting warning message `gl-dast-report.json: no matching files` - -For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). - -### Getting error `dast job: chosen stage does not exist` when including DAST CI template - -Newer versions of the DAST CI template do not define stages in order to avoid -overwriting stages from other CI files. If you've recently started using -`DAST.latest.gitlab-ci.yml` or upgraded to a new major release of GitLab and -began receiving this error, you will need to define a `dast` stage with your -other stages. Please note that you must have a running application for DAST to -scan. If your application is set up in your pipeline, it must be deployed - in a stage _before_ the `dast` stage: - -```yaml -stages: - - deploy # DAST needs a running application to scan - - dast - -include: - - template: DAST.latest.gitlab-ci.yml -``` - -<!-- ## 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/application_security/dependency_list/img/dependency_list_v12_10.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_10.png Binary files differdeleted file mode 100644 index 2755b42f1e4..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_10.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png b/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png Binary files differnew file mode 100644 index 00000000000..5b2bd985ce4 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 6ed3b15d829..25b7615a8ae 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -26,7 +26,7 @@ To view your project's dependencies, ensure you meet the following requirements: ## View a project's dependencies - + GitLab displays dependencies with the following information: @@ -44,7 +44,8 @@ can also be sorted by name or by the packager that installed them. If a dependency has known vulnerabilities, view them by clicking the arrow next to the dependency's name or the badge that indicates how many known vulnerabilities exist. For each -vulnerability, its severity and description appears below it. +vulnerability, its severity and description appears below it. To view more details of a vulnerability, +select the vulnerability’s description. The [vulnerability's details](../vulnerabilities) page is opened. ### Dependency paths diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index f87ea8edc7b..53387acefef 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -105,7 +105,7 @@ include: The included template creates dependency scanning jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[dependency scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning) +[dependency scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest dependency scanning artifact available. @@ -183,10 +183,11 @@ The following variables are used for configuring specific analyzers (used for a | `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | | `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | | `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. | +| `GEMNASIUM_DB_UPDATE_DISABLED` | `gemnasium` | `"false"` | Disable automatic updates for the `gemnasium-db` advisory database (For usage see: [examples](#hosting-a-copy-of-the-gemnasium_db-advisory-database))| | `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`. Maven and Gradle use the Java version specified by this value. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -214,7 +215,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Using private Maven repositories @@ -505,6 +506,50 @@ ensure that it can reach your private repository. Here is an example configurati setuptools.ssl_support.cert_paths = ['internal.crt'] ``` +## Hosting a copy of the gemnasium_db advisory database + +The [gemnasium_db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) Git repository is +used by `gemnasium`, `gemnasium-maven`, and `gemnasium-python` as the source of vulnerability data. +This repository updates at scan time to fetch the latest advisories. However, due to a restricted +networking environment, running this update is sometimes not possible. In this case, a user can do +one of the following: + +- [Host a copy of the advisory database](#host-a-copy-of-the-advisory-database) +- [Use a local clone](#use-a-local-clone) + +### Host a copy of the advisory database + +If [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is not reachable +from within the environment, the user can host their own Git copy. Then the analyzer can be +instructed to update the database from the user's copy by using `GEMNASIUM_DB_REMOTE_URL`: + +```yaml +variables: + GEMNASIUM_DB_REMOTE_URL: https://users-own-copy.example.com/gemnasium-db/.git + +... +``` + +### Use a local clone + +If a hosted copy is not possible, then the user can clone [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) +or create an archive before the scan and point the analyzer to the directory (using: +`GEMNASIUM_DB_LOCAL_PATH`). Turn off the analyzer's self-update mechanism (using: +`GEMNASIUM_DB_UPDATE_DISABLED`). In this example, the database directory is created in the +`before_script`, before the `gemnasium` analyzer's scan job: + +```yaml +... + +gemnasium-dependency_scanning: + variables: + GEMNASIUM_DB_LOCAL_PATH: ./gemnasium-db-local + GEMNASIUM_DB_UPDATE_DISABLED: "true" + before_script: + - mkdir $GEMNASIUM_DB_LOCAL_PATH + - tar -xzf gemnasium_db.tar.gz -C $GEMNASIUM_DB_LOCAL_PATH +``` + ## Limitations ### Referencing local dependencies using a path in JavaScript projects diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png Binary files differdeleted file mode 100644 index 8e7bcf09428..00000000000 --- a/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png Binary files differindex 54ccfa24374..55694fc7926 100644 --- a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png +++ b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png Binary files differdeleted file mode 100644 index db698995469..00000000000 --- a/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/img/multi_select_v12_9.png b/doc/user/application_security/img/multi_select_v12_9.png Binary files differdeleted file mode 100644 index ec3648bff08..00000000000 --- a/doc/user/application_security/img/multi_select_v12_9.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif Binary files differdeleted file mode 100644 index 562ffe7e329..00000000000 --- a/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index b0457ec0690..1ba2161362c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -178,43 +178,6 @@ authorization credentials. By default, content of specific headers are masked in reports. You can specify the list of all headers to be masked. For details, see [Hide sensitive information](dast/index.md#hide-sensitive-information). -## View details of an API Fuzzing vulnerability - -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. - -Faults detected by API Fuzzing occur in the live web application, and require manual investigation -to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a -severity of Unknown. To facilitate investigation of the fuzzing faults, detailed information is -provided about the HTTP messages sent and received along with a description of the modification(s) -made. - -Follow these steps to view details of a fuzzing fault: - -1. You can view faults in a project, or a merge request: - - - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** - page. This page shows all vulnerabilities from the default branch only. - - In a merge request, go the merge request's **Security** section and click the **Expand** - button. API Fuzzing faults are available in a section labeled - **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault - details. - -1. Click the fault's title to display the fault's details. The table below describes these details. - -| Field | Description | -|:-----------------|:------------------------------------------------------------------ | -| Description | Description of the fault including what was modified. | -| Project | Namespace and project in which the vulnerability was detected. | -| Method | HTTP method used to detect the vulnerability. | -| URL | URL at which the vulnerability was detected. | -| Request | The HTTP request that caused the fault. | -| Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | -| Actual Response | Response received from fuzzed request. | -| Evidence | How we determined a fault occurred. | -| Identifiers | The fuzzing check used to find this fault. | -| Severity | Severity of the finding is always Unknown. | -| Scanner Type | Scanner used to perform testing. | - ## Addressing vulnerabilities > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. @@ -265,15 +228,7 @@ If you already have an open issue, you can link to it from the vulnerability. To link to an existing issue: 1. Open the vulnerability. -1. In the **Related Issues** section, select the plus (**{plus}**) icon. -1. In the text box that appears, type an issue number or paste an issue link. - - Type `#` followed by a number to show an autocomplete menu. - - You can enter multiple issues at once. Press the space bar after each issue number or link to converts them to tags. -1. Select **Add**. - -To remove an issue, to the right of the issue number, select **{close}**. - - +1. [Add a linked issue](../project/issues/related_issues.md). ### Apply an automatic remediation for a vulnerability @@ -311,7 +266,7 @@ request created to automatically solve the issue. If this action is available: 1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. - +  A merge request is created. It that applies the solution to the source branch. @@ -407,7 +362,7 @@ to pass a username and password. You can set it under your project's settings so that your credentials aren't exposed in `.gitlab-ci.yml`. If the username is `myuser` and the password is `verysecret` then you would -[set the following variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) +[set the following variable](../../ci/variables/README.md#custom-cicd-variables) under your project's settings: | Type | Key | Value | @@ -616,9 +571,8 @@ Instructions are available in the [legacy template project](https://gitlab.com/g This is the current default behavior, because the job's status indicates success or failure of the analyzer itself. Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), -[Merge Request widget](sast/index.md) +[Merge Request widget](#view-security-scan-information-in-merge-requests) or [Security Dashboard](security_dashboard/index.md). -There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. ### Error: job `is used for configuration only, and its script should not be executed` diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md new file mode 100644 index 00000000000..208fbdfa5f3 --- /dev/null +++ b/doc/user/application_security/policies/index.md @@ -0,0 +1,183 @@ +--- +stage: Protect +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 +--- + +# Scan Policies **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> - Deployed behind a feature flag, disabled by default. +> - Disabled on GitLab.com. + +Scan Policies in GitLab provide security teams a way to require scans of their choice to be run +whenever a project pipeline runs according to the configuration specified. Security teams can +therefore be confident that the scans they set up have not been changed, altered, or disabled. You +can access these by navigating to your project's **Security & Compliance > Scan Policies** page. + +GitLab supports the following security policies: + +- [Scan Execution Policy](#scan-execution-policy-schema) + +WARNING: +Scan Policies is under development and is not ready for production use. It's deployed behind a +feature flag that's disabled by default. + +NOTE: +We recommend using the [Security Policies project](#security-policies-project) +exclusively for managing policies for the project. Do not add your application's source code to such +projects. + +## Enable or disable scan policies + +Scan Policies is under development and is not ready for production use. It's deployed behind a +feature flag that's disabled by default. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it for your instance. Scan Policies can be enabled or disabled per-project. + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:security_orchestration_policies_configuration) +# or by project +Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:security_orchestration_policies_configuration) +# or by project +Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +``` + +## Security Policies project + +The Security Policies feature is a repository to store policies. All security policies are stored as +the `.gitlab/security-policies/policy.yml` YAML file with this format: + +```yaml +--- +scan_execution_policy: +- name: Enforce DAST in every pipeline + description: This policy enforces pipeline configuration to have a job with DAST scan + enabled: true + rules: + - type: pipeline + branch: master + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B +- name: Enforce DAST in every pipeline in main branch + description: This policy enforces pipeline configuration to have a job with DAST scan for main branch + enabled: true + rules: + - type: pipeline + branch: main + actions: + - scan: dast + scanner_profile: Scanner Profile C + site_profile: Site Profile D +``` + +### Scan Execution Policies Schema + +The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan_execution_policy` | `array` of Scan Execution Policy | | List of scan execution policies (maximum 5) | + +### Scan Execution Policy Schema + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `name` | `string` | | Name of the policy. | +| `description` (optional) | `string` | | Description of the policy. | +| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | | List of rules that the policy applies. | +| `actions` | `array` of actions | | List of actions that the policy enforces. | + +### `pipeline` rule type + +This rule enforces the defined actions whenever the pipeline runs for a selected branch. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `type` | `string` | `pipeline` | The rule's type. | +| `branch` | `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | + +### `scan` action type + +This action executes the selected `scan` with additional parameters when conditions for at least one +rule in the defined policy are met. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan` | `string` | `dast` | The action's type. | +| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. | +| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. | + +Note the following: + +- You must create the [site profile](../dast/index.md#site-profile) and [scanner profile](../dast/index.md#scanner-profile) + with selected names for each project that is assigned to the selected Security Policy Project. + Otherwise, the policy is not applied and a job with an error message is created instead. +- Once you associate the site profile and scanner profile by name in the policy, it is not possible + to modify or delete them. If you want to modify them, you must first disable the policy by setting + the `active` flag to `false`. + +Here's an example: + +```yaml +--- +scan_execution_policy: +- name: Enforce DAST in every release pipeline + description: This policy enforces pipeline configuration to have a job with DAST scan for release branches + enabled: true + rules: + - type: pipeline + branch: release/* + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B +- name: Enforce DAST in every pipeline in main branch + description: This policy enforces pipeline configuration to have a job with DAST scan for main branch + enabled: true + rules: + - type: pipeline + branch: main + actions: + - scan: dast + scanner_profile: Scanner Profile C + site_profile: Site Profile D +``` + +In this example, the DAST scan runs with the scanner profile `Scanner Profile A` and the site +profile `Site Profile B` for every pipeline executed on branches that match the +`release/*` wildcard (for example, branch name `release/v1.2.1`); and the DAST scan runs with +the scanner profile `Scanner Profile C` and the site profile `Site Profile D` for every pipeline executed on `main` branch. + +NOTE: +All scanner and site profiles must be configured and created for each project that is assigned to the selected Security Policy Project. +If they are not created, the job will fail with the error message. + +## Security Policy project selection + +When the Security Policy project is created and policies are created within that repository, you +must create an association between that project and the project you want to apply policies to. To do +this, navigate to your project's **Security & Compliance > Policies**, select +**Security policy project** from the dropdown menu, then select the **Create policy** button to save +changes. + +You can always change the **Security policy project** by navigating to your project's +**Security & Compliance > Policies** and modifying the selected project. + +## Roadmap + +See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) +for more information on the product direction of Container Network Security. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 83f85951388..c085dafac12 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -43,6 +43,19 @@ dedicated containers for each analysis. SAST is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. +## SAST analyzer features + +For an analyzer to be considered Generally Available, it is expected to minimally +support the following features: + +- [Customizable configuration](index.md#available-variables) +- [Customizable rulesets](index.md#customize-rulesets) +- [Scan projects](index.md#supported-languages-and-frameworks) +- [Multi-project support](index.md#multi-project-support) +- [Offline support](index.md#running-sast-in-an-offline-environment) +- [Emits JSON report format](index.md#reports-json-format) +- [SELinux support](index.md#running-sast-in-selinux) + ## Official default analyzers Any custom change to the official analyzers can be achieved by using a diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fffff4efba6..cbd05f6267e 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -64,32 +64,36 @@ GitLab SAST supports a variety of languages, package managers, and frameworks. O You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). -| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | -|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | -| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | -| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | -| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | -| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | -| 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) | -| Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | -| Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | -| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | -| Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | -| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | -| Python | [Semgrep](https://semgrep.dev) | 13.9 | -| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | -| Ruby | [brakeman](https://brakemanscanner.org) | 13.9 | -| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | -| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | -| Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | +| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | +|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | +| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | +| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | +| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | +| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | +| 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) | +| Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | +| JavaScript | [Semgrep](https://semgrep.dev) | 13.10 | +| Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| Kotlin (General) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 13.11 | +| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | +| Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | +| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | +| Python | [Semgrep](https://semgrep.dev) | 13.9 | +| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | +| React | [Semgrep](https://semgrep.dev) | 13.10 | +| Ruby | [brakeman](https://brakemanscanner.org) | 13.9 | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | +| TypeScript | [Semgrep](https://semgrep.dev) | 13.10 | Note that the Java analyzers can also be used for variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), @@ -172,7 +176,7 @@ The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast) +[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. @@ -441,7 +445,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. #### Docker images @@ -513,6 +517,7 @@ removed, or promoted to regular features at any time. Experimental features available are: - Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +- Enable the [semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/). #### Enable experimental features @@ -532,7 +537,7 @@ The SAST tool emits a JSON report file. For more information, see the [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). The JSON report file can be downloaded from the CI pipelines page, or the -pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/pipelines/job_artifacts.md#defining-artifacts-in-gitlab-ciyml) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). +pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/README.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). Here's an example SAST report: @@ -703,8 +708,21 @@ offline environment, certificate verification with an external source is not pos self-signed certificate or disable certificate verification. Refer to the package manager's documentation for instructions. +## Running SAST in SELinux + +By default SAST analyzers are supported in GitLab instances hosted on SELinux. Adding a `before_script` in an [overriden SAST job](#overriding-sast-jobs) may not work as runners hosted on SELinux have restricted permissions. + ## Troubleshooting +### SAST debug logging + +Increase the [Secure scanner log verbosity](#logging-level) to `debug` in a global CI variable to help troubleshoot SAST jobs. + +```yaml +variables: + SECURE_LOG_LEVEL: "debug" +``` + ### `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`. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index d2a576e9e03..f137ec26114 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -129,22 +129,10 @@ The included template creates Secret Detection jobs in your CI/CD pipeline and s your project's source code for secrets. The results are saved as a -[Secret Detection report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssecret_detection) +[Secret Detection report artifact](../../../ci/yaml/README.md#artifactsreportssecret_detection) that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. -### Post-processing - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. - -Upon detection of a secret, GitLab supports post processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. - -GitLab currently supports post-processing for following service providers: - -- Amazon Web Services (AWS) - -Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). - ### Customizing settings The Secret Detection scan settings can be changed through [CI/CD variables](#available-variables) @@ -249,6 +237,34 @@ From highest to lowest severity, the logging levels are: - `info` (default) - `debug` +## Post-processing and revocation + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. + +Upon detection of a secret, GitLab supports post-processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. + +GitLab currently supports post-processing for following service providers: + +- Amazon Web Services (AWS) + +Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). + +NOTE: +Post-processing is currently limited to a project's default branch, see the above epic for future efforts to support additional branches. + +```mermaid +sequenceDiagram + autonumber + Rails->>+Sidekiq: gl-secret-detection-report.json + Sidekiq-->+Sidekiq: BuildFinishedWorker + Sidekiq-->+RevocationAPI: GET revocable keys types + RevocationAPI-->>-Sidekiq: OK + Sidekiq->>+RevocationAPI: POST revoke revocable keys + RevocationAPI-->>-Sidekiq: ACCEPTED + RevocationAPI-->>+Cloud Vendor: revoke revocable keys + Cloud Vendor-->>+RevocationAPI: ACCEPTED +``` + ## Full History Secret Scan GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png Binary files differnew file mode 100644 index 00000000000..cc9f0061a31 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png Binary files differdeleted file mode 100644 index 6ccae80e80e..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 8a2c40406e2..326c88f9eef 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -39,7 +39,7 @@ The security dashboard and vulnerability report displays information about vulne 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). -1. The configured jobs must use the [new `reports` syntax](../../../ci/pipelines/job_artifacts.md#artifactsreports). +1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports). 1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. If you're using the shared runners on GitLab.com, this is already the case. @@ -71,17 +71,23 @@ CSV file containing details of the resources scanned. ## Project Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in GitLab 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285476) in GitLab 13.10, options to zoom in on a date range, and download the vulnerabilities chart. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualise data between given dates. At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. Access it by navigating to **Security & Compliance > Security Dashboard**. We display historical data up to 365 days. The chart's data is updated daily. - + Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows only the graph for vulnerabilities with **high** severity. +To zoom in, select the left-most icon, then select the desired rangeby dragging across the chart. Select **Remove Selection** (**{redo}**) to reset to the original date range. + +To download an SVG image of the chart, select **Save chart to an image** (**{download}**). + ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. @@ -152,7 +158,7 @@ found in those projects' default branches. ## Keeping the dashboards up to date The Security Dashboard displays information from the results of the most recent -security scan on the [default branch](../../project/repository/branches/index.md#default-branch), +security scan on the [default branch](../../project/repository/branches/default.md), which means that security scans are performed every time the branch is updated. If the default branch is updated infrequently, scans are run infrequently and the diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png Binary files differnew file mode 100644 index 00000000000..05df41483c4 --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png Binary files differdeleted file mode 100644 index a668ce1a3b8..00000000000 --- a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png +++ /dev/null diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 747d31df356..ced4669e241 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -221,7 +221,7 @@ to set the status for each alert: By default, the list doesn't display resolved or dismissed alerts. To show these alerts, clear the checkbox **Hide dismissed alerts**. - + Clicking an alert's name takes the user to the [alert details page](../../../operations/incident_management/alerts.md#alert-details-page). diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png Binary files differdeleted file mode 100644 index a3034a7db04..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 416db5b07fc..b98d28f8c9f 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -50,7 +50,7 @@ From a vulnerability you can create either: - [A Jira issue](#create-a-jira-issue-for-a-vulnerability). Creating a Jira issue requires that -[Jira integration](../../project/integrations/jira_integrations.md) is enabled on the project. Note +[Jira integration](../../../integration/jira/index.md) is enabled on the project. Note that when Jira integration is enabled, the GitLab issue feature is not available. ### Create a GitLab issue for a vulnerability diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_10.png Binary files differindex f9f60810f20..f9f60810f20 100644 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_10.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 583859e2541..8f7740f9bfc 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** The Vulnerability Report provides information about vulnerabilities from scans of the branch most -recently merged into the default branch. It is available at the instance, group, and project level. +recently merged into the default branch. It is available for groups, projects, and the Security Center. At all levels, the Vulnerability Report contains: @@ -36,6 +36,7 @@ From the Vulnerability Report you can: - [Filter the list of vulnerabilities](#filter-the-list-of-vulnerabilities). - [View more details about a vulnerability](#view-details-of-a-vulnerability). +- [View vulnerable source location](#view-vulnerable-source-location) (if available). - [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). - [Change the status of vulnerabilities](#change-status-of-vulnerabilities). - [Export details of vulnerabilities](#export-vulnerability-details). @@ -72,7 +73,7 @@ The content of the Project filter depends on the current level: | Level | Content of the Project filter | |:---------------|:------------------------------| -| Instance level | Only projects you've [added to the instance-level Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | +| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | | Group level | All projects in the group. | | Project level | Not applicable. | @@ -99,6 +100,16 @@ Selection behavior when using the Activity filter: To view more details of a vulnerability, select the vulnerability's **Description**. The [vulnerability's details](../vulnerabilities) page is opened. +## View vulnerable source location + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267509) in GitLab 13.10. + +Some security scanners output the filename and line number of a potential vulnerability. When +that information is available, the vulnerability's details include a link to the relevant file, +in the default branch. + +To view the relevant file, select the filename in the vulnerability's details. + ## View issues raised for a vulnerability The **Activity** column indicates the number of issues that have been created for the vulnerability. @@ -108,12 +119,14 @@ Hover over an **Activity** entry and select a link go to that issue. ## Change status of vulnerabilities +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292636) in GitLab 13.10, all statuses became selectable. + To change the status of vulnerabilities in the table: 1. Select the checkbox for each vulnerability you want to update the status of. 1. In the dropdown that appears select the desired status, then select **Change status**. - + ## Export vulnerability details diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 6d6460ca50f..8313b20e795 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -374,7 +374,7 @@ comment - content which is not included in the output document ### Colors -It’s possible to have color written in `HEX`, `RGB`, or `HSL` format rendered with a color indicator. +It's possible to have color written in `HEX`, `RGB`, or `HSL` format rendered with a color indicator. Supported formats (named colors are not supported): - HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 77b9dbb1c7e..31accfdd9e4 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,13 +4,11 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Kubernetes Agent **(PREMIUM SELF)** +# GitLab Kubernetes Agent **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. > - [In GitLab 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300960), KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - Introduced in GitLab 13.11, the GitLab Kubernetes Agent became available to every project on GitLab.com. The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) is an active in-cluster component for solving GitLab and Kubernetes integration @@ -68,7 +66,7 @@ For more details, please refer to our [full architecture documentation](https:// The setup process involves a few steps to enable GitOps deployments: -1. [Install the Agent server](#install-the-kubernetes-agent-server) for your GitLab instance. +1. [Set up the Kubernetes Agent Server](#set-up-the-kubernetes-agent-server) for your GitLab instance. 1. [Define a configuration repository](#define-a-configuration-repository). 1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). 1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). @@ -83,7 +81,7 @@ neither stable nor versioned yet. For this reason, GitLab only guarantees compat between corresponding major.minor (X.Y) versions of GitLab and its cluster side component, `agentk`. -Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk`to install follow: +Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk` to install follow: 1. Open the [`GITLAB_KAS_VERSION`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch. 1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION) @@ -91,88 +89,14 @@ Upgrade your agent installations together with GitLab upgrades. To decide which The available `agentk` and `kas` versions can be found in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). -### Install the Kubernetes Agent Server **(FREE SELF)** - -[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, -the GitLab Kubernetes Agent Server (KAS) is available on GitLab.com under `wss://kas.gitlab.com`. -If you are a GitLab.com user, skip this step and directly -[set up the configuration repository](#define-a-configuration-repository) -for your agent. - -The GitLab Kubernetes Agent Server (KAS) can be installed through Omnibus GitLab or -through the GitLab Helm Chart. If you don't already have -GitLab installed, please refer to our [installation -documentation](https://docs.gitlab.com/ee/install/README.html). -You can install the KAS within GitLab as explained below according to your GitLab installation method. -You can also opt to use an [external KAS](#use-an-external-kas-installation). - -#### Install KAS with Omnibus - -For [Omnibus](https://docs.gitlab.com/omnibus/) package installations: - -1. Edit `/etc/gitlab/gitlab.rb` to enable the Kubernetes Agent Server: - - ```plaintext - gitlab_kas['enable'] = true - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - -To configure any additional options related to GitLab Kubernetes Agent Server, -refer to the **Enable GitLab KAS** section of the -[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template). - -#### Install KAS with GitLab Helm Chart - -For GitLab [Helm Chart](https://gitlab.com/gitlab-org/charts/gitlab) installations, consider the following Helm v3 example. -If you're using Helm v2, you must modify this example. See our [notes regarding deploy with Helm](https://docs.gitlab.com/charts/installation/deployment.html#deploy-using-helm). - -You must set `global.kas.enabled=true` for the KAS to be properly installed and configured: - -```shell -helm repo add gitlab https://charts.gitlab.io/ -helm repo update -helm upgrade --install gitlab gitlab/gitlab \ - --timeout 600s \ - --set global.hosts.domain=<YOUR_DOMAIN> \ - --set global.hosts.externalIP=<YOUR_IP> \ - --set certmanager-issuer.email=<YOUR_EMAIL> \ - --set global.kas.enabled=true -``` - -To specify other options related to the KAS sub-chart, create a `gitlab.kas` sub-section -of your `values.yaml` file: - -```shell -gitlab: - kas: - # put your KAS custom options here -``` - -For details, read [Using the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitlab/kas/). - -#### Use an external KAS installation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299850) in GitLab 13.10. +### Set up the Kubernetes Agent Server -Besides installing KAS with GitLab, you can opt to configure GitLab to use an external KAS. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Kubernetes Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. -For GitLab instances installed through the GitLab Helm Chart, see [how to configure your external KAS](https://docs.gitlab.com/charts/charts/globals.html#external-kas). +To use the KAS: -For GitLab instances installed through Omnibus packages: - -1. Edit `/etc/gitlab/gitlab.rb` adding the paths to your external KAS: - - ```ruby - gitlab_kas['enable'] = false - gitlab_kas['api_secret_key'] = 'Your shared secret between GitLab and KAS' - - gitlab_rails['gitlab_kas_enabled'] = true - gitlab_rails['gitlab_kas_external_url'] = 'wss://kas.gitlab.example.com' # User-facing URL for the in-cluster agentk - gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com' # Internal URL for the GitLab backend - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). +- If you are a self-managed user, follow the instructions to [install the Kubernetes Agent Server](../../../administration/clusters/kas.md). +- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. ### Define a configuration repository @@ -200,23 +124,9 @@ documentation on the [Kubernetes Agent configuration repository](repository.md). ### Create an Agent record in GitLab -Next, create an GitLab Rails Agent record so the Agent can associate itself with +Next, create a GitLab Rails Agent record to associate it with the configuration repository project. Creating this record also creates a Secret needed to configure -the Agent in subsequent steps. You can create an Agent record either: - -- Through the Rails console: - - ```ruby - project = ::Project.find_by_full_path("path-to/your-configuration-project") - # agent-name should be the same as specified above in the config.yaml - agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) - token = ::Clusters::AgentToken.create(agent: agent) - token.token # this will print out the token you need to use on the next step - ``` - - For full details, read [Starting a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -- Through GraphQL: **(PREMIUM SELF)** +the Agent in subsequent steps. You can create an Agent record with GraphQL: ```graphql mutation createAgent { @@ -257,23 +167,35 @@ the Agent in subsequent steps. You can create an Agent record either: ### Install the Agent into the cluster -Next, install the in-cluster component of the Agent. +To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, +for example, `gitlab-kubernetes-agent`, run: -NOTE: -For GitLab.com users, the KAS is available at `wss://kas.gitlab.com`. +```shell +kubectl create namespace gitlab-kubernetes-agent +``` -#### One-liner installation +To perform a one-liner installation, run the command below. Make sure to replace: -Replace the value of `agent-token` below with the token received from the previous step. Also, replace `kas-address` with the configured access of the Kubernetes Agent Server: +- `your-agent-token` with the token received from the previous step. +- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. +- `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. ```shell -docker run --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:latest generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version latest | kubectl apply -f - +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version stable --namespace gitlab-kubernetes-agent | kubectl apply -f - ``` +Set `--agent-version` to the latest released patch version matching your +GitLab installation's major and minor versions. For example, if you have +GitLab v13.9.0, set `--agent-version=v13.9.1`. + +WARNING: +Version `stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for +testing purposes but for production please make sure to specify a matching version explicitly. + To find out the various options the above Docker container supports, run: ```shell -docker run --rm -it registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:latest generate --help +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help ``` #### Advanced installation @@ -286,17 +208,11 @@ Otherwise, you can follow below for fully manual, detailed installation steps. After generating the token, you must apply it to the Kubernetes cluster. -1. If you haven't previously defined or created a namespace, run the following command: - - ```shell - kubectl create namespace <YOUR-DESIRED-NAMESPACE> - ``` +To create your Secret, run: -1. Run the following command to create your Secret: - - ```shell - kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' - ``` +```shell +kubectl create secret generic -n <YOUR_NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +``` The following example file contains the Kubernetes resources required for the Agent to be installed. You can modify this @@ -314,7 +230,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) to use an unencrypted WebSockets connection. - When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`). + When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`). - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. In this case, you may specify `kas-address` value as `grpc://gitlab-kas.<your-namespace>:5005`) to use gRPC directly, where `gitlab-kas` @@ -326,7 +242,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) to learn more about it. - - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. + - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. - If you defined your own secret name, replace `gitlab-agent-token` with your secret name in the `secretName:` section. @@ -370,7 +286,8 @@ spec: serviceAccountName: gitlab-agent containers: - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + # Make sure to specify a matching version for production + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:stable" args: - --token-file=/config/token - --kas-address @@ -549,7 +466,7 @@ cilium: ## Management interfaces Users with at least the [Developer](../../permissions.md) can access the user interface -for the GitLab Kubernetes agent at **Operations > Kubernetes** and selecting the +for the GitLab Kubernetes agent at **Operations > Kubernetes** under the **GitLab Agent managed clusters** tab. This page lists all registered agents for the current project, and the configuration directory for each agent: @@ -561,36 +478,17 @@ Additional management interfaces are planned for the GitLab Kubernetes Agent. ## Troubleshooting If you face any issues while using GitLab Kubernetes Agent, you can read the -service logs with the following commands: - -- KAS pod logs - Tail these logs with the - `kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>` - command. In Omnibus GitLab, the logs reside in `/var/log/gitlab/gitlab-kas/`. -- Agent pod logs - Tail these logs with the - `kubectl logs -f -l=app=gitlab-agent -n <YOUR-DESIRED-NAMESPACE>` command. - -### KAS logs - GitOps: failed to get project info - -```plaintext -{"level":"warn","time":"2020-10-30T08:37:26.123Z","msg":"GitOps: failed to get project info","agent_id":4,"project_id":"root/kas-manifest001","error":"error kind: 0; status: 404"} -``` - -This error is shown if the specified manifest project `root/kas-manifest001` -doesn't exist, or if a project is private. To fix it, make sure the project exists -and its visibility is [set to public](../../../public_access/public_access.md). +service logs with the following command -### KAS logs - Configuration file not found - -```plaintext -time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\ +```shell +kubectl logs -f -l=app=gitlab-agent -n <YOUR-DESIRED-NAMESPACE> ``` -This error is shown if the path to the configuration project was specified incorrectly, -or if the path to `config.yaml` inside the project is not valid. +GitLab administrators can additionally view the [Kubernetes Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). ### Agent logs - Transport: Error while dialing failed to WebSocket dial -```plaintext +```json {"level":"warn","time":"2020-11-04T10:14:39.368Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""} ``` @@ -610,7 +508,7 @@ may try using them to create objects in Kubernetes directly for more troubleshoo ### Agent logs - Error while dialing failed to WebSocket dial: failed to send handshake request -```plaintext +```json {"level":"warn","time":"2020-10-30T09:50:51.173Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""} ``` @@ -626,7 +524,7 @@ issue is in progress, directly edit the deployment with the ### Agent logs - Decompressor is not installed for grpc-encoding -```plaintext +```json {"level":"warn","time":"2020-11-05T05:25:46.916Z","msg":"GetConfiguration.Recv failed","error":"rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""} ``` @@ -635,7 +533,7 @@ To fix it, make sure that both `agentk` and KAS use the same versions. ### Agent logs - Certificate signed by unknown authority -```plaintext +```json {"level":"error","time":"2021-02-25T07:22:37.158Z","msg":"Reverse tunnel","mod_name":"reverse_tunnel","error":"Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""} ``` @@ -652,17 +550,17 @@ kubectl -n gitlab-agent create configmap ca-pemstore --from-file=myCA.pem Then in `resources.yml`: -```plaintext +```yaml spec: serviceAccountName: gitlab-agent containers: - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" args: - --token-file=/config/token - --kas-address - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab - # - wss://gitlab.host.tld:443/-/kubernetes-agent + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ volumeMounts: - name: token-volume mountPath: /config @@ -684,16 +582,16 @@ Then in `resources.yml`: Alternatively, you can mount the certificate file at a different location and include it using the `--ca-cert-file` agent parameter: -```plaintext +```yaml containers: - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" args: - --ca-cert-file=/tmp/myCA.pem - --token-file=/config/token - --kas-address - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab - # - wss://gitlab.host.tld:443/-/kubernetes-agent + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ volumeMounts: - name: token-volume mountPath: /config diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 60d8cd352fc..9caa4a89daf 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -4,10 +4,10 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Kubernetes Agent configuration repository **(PREMIUM SELF)** +# Kubernetes Agent configuration repository **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. -> - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. WARNING: This feature might not be available to you. Check the **version history** note above for details. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 5c3b276b90c..b11ca7aac12 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -91,7 +91,7 @@ apps were fetched from the central Helm stable repository (`https://kubernetes-c This repository [was deleted](https://github.com/helm/charts#deprecation-timeline) on November 13, 2020. This causes the installation CI/CD pipeline to fail. Upgrade to GitLab 13.6, or alternatively, you can -use the following `.gitlab-ci.yml`, which has been tested on GitLab 13.5: +use the following `.gitlab-ci.yml`, which has been tested in GitLab 13.5: ```yaml include: @@ -1001,8 +1001,8 @@ Logs produced by pods running **GitLab Managed Apps** can be browsed using ## Install with one click WARNING: -The one click installation method is scheduled for removal in GitLab 14.0. The removal -of this feature from GitLab does not affect installed applications to avoid breaking +The one-click installation method is deprecated and scheduled for removal in [GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). +This removal does not affect installed applications to avoid breaking changes. Following GitLab 14.0, users can take ownership of already installed applications using our documentation. @@ -1062,7 +1062,7 @@ supported by GitLab before installing any of the applications. used to install the GitLab-managed apps. GitLab runs each `helm` command in a pod in the `gitlab-managed-apps` namespace inside the cluster. -- For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage +- For clusters created in GitLab 13.6 and newer, GitLab uses Helm 3 to manage applications. - For clusters created on versions of GitLab prior to 13.6, GitLab uses Helm 2 with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. Prior @@ -1239,7 +1239,7 @@ of a WAF are: By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), which is a toolkit for real-time web application monitoring, logging, and access -control. GitLab applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), +control. GitLab applies the [OWASP's Core Rule Set](https://coreruleset.org/), which provides generic attack detection capabilities. This feature: @@ -1314,7 +1314,7 @@ tracked over time: - The total amount of traffic to your application. - The proportion of traffic that's considered anomalous by the Web Application - Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/). + Firewall's default [OWASP ruleset](https://coreruleset.org/). If a significant percentage of traffic is anomalous, investigate it for potential threats by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md new file mode 100644 index 00000000000..74c48d1a010 --- /dev/null +++ b/doc/user/clusters/integrations.md @@ -0,0 +1,68 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Cluster integrations **(FREE)** + +GitLab provides several ways to integrate applications to your +Kubernetes cluster. + +To enable cluster integrations, first add a Kubernetes cluster to a GitLab +[project](../project/clusters/add_remove_clusters.md) or [group](../group/clusters/index.md#group-level-kubernetes-clusters). + +## Prometheus cluster integration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. + +You can integrate your Kubernetes cluster with +[Prometheus](https://prometheus.io/) for monitoring key metrics of your +apps directly from the GitLab UI. + +Once enabled, you will see metrics from services available in the +[metrics library](../project/integrations/prometheus_library/index.md). + +Prerequisites: + +To benefit from this integration, you must have Prometheus +installed in your cluster with the following requirements: + +1. Prometheus must be installed inside the `gitlab-managed-apps` namespace. +1. The `Service` resource for Prometheus must be named `prometheus-prometheus-server`. + +You can use the following commands to install Prometheus to meet the requirements for cluster integrations: + +```shell +# Create the require Kubernetes namespace +kubectl create ns gitlab-managed-apps + +# Download Helm chart values that is compatible with the requirements above. +# You should substitute the tag that corresponds to the GitLab version in the url +# - https://gitlab.com/gitlab-org/gitlab/-/raw/<tag>/vendor/prometheus/values.yaml +# +wget https://gitlab.com/gitlab-org/gitlab/-/raw/v13.9.0-ee/vendor/prometheus/values.yaml + +# Add the Prometheus community helm repo +helm repo add prometheus-community https://prometheus-community.github.io/helm-charts + +# Install Prometheus +helm install prometheus prometheus-community/prometheus -n gitlab-managed-apps --values values.yaml +``` + +Alternatively, you can use your preferred installation method to install +Prometheus as long as you meet the requirements above. + +### Enable Prometheus integration for your cluster + +To enable the Prometheus integration for your cluster: + +1. Go to the cluster's page: + - For a [project-level cluster](../project/clusters/index.md), navigate to your project's + **Operations > Kubernetes**. + - For a [group-level cluster](../group/clusters/index.md), navigate to your group's + **Kubernetes** page. +1. Select the **Integrations** tab. +1. Check the **Enable Prometheus integration** checkbox. +1. Click **Save changes**. +1. Go to the **Health** tab to see your cluster's metrics. diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png Binary files differnew file mode 100644 index 00000000000..95e176b71b8 --- /dev/null +++ b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png Binary files differdeleted file mode 100644 index b2ac4f95e0d..00000000000 --- a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png +++ /dev/null diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index f1dfc431f25..8f620fe41bb 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -17,7 +17,7 @@ for merging into production. To access the Compliance Dashboard for a group, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu. - + NOTE: The Compliance Dashboard shows only the latest MR on each project. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 6c734a76059..823a0561beb 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -115,7 +115,7 @@ the `license_management` job, so you must migrate to the `license_scanning` job `License-Scanning.gitlab-ci.yml` template. The results are saved as a -[License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning) +[License Compliance report artifact](../../../ci/yaml/README.md#artifactsreportslicense_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder) @@ -157,7 +157,7 @@ The `license_management` image already embeds many auto-detection scripts, langu and packages. Nevertheless, it's almost impossible to cover all cases for all projects. That's why sometimes it's necessary to install extra packages, or to have extra steps in the project automated setup, like the download and installation of a certificate. -For that, a `LICENSE_MANAGEMENT_SETUP_CMD` CI/CD variable can be passed to the container, +For that, a `SETUP_CMD` CI/CD variable can be passed to the container, with the required commands to run before the license detection. If present, this variable overrides the setup step necessary to install all the packages @@ -171,7 +171,7 @@ include: - template: Security/License-Scanning.gitlab-ci.yml variables: - LICENSE_MANAGEMENT_SETUP_CMD: sh my-custom-install-script.sh + SETUP_CMD: sh my-custom-install-script.sh ``` In this example, `my-custom-install-script.sh` is a shell script at the root @@ -490,7 +490,7 @@ example: } ``` -If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-custom-variable) +If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-cicd-variable) following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). #### Custom root certificates for Conan @@ -759,6 +759,29 @@ An approval is optional when a license report: ## Troubleshooting +### ASDF_PYTHON_VERSION does not automatically install the version + +Defining a non-latest Python version in ASDF_PYTHON_VERSION [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: + +1. Define the required version by setting the `ASDF_PYTHON_VERSION` CI/CD variable. +1. Pass a custom script to the `SETUP_CMD` CI/CD variable to install the required version and dependencies. + +For example: + +```yaml +include: + - template: Security/License-Scanning.gitlab-ci.yml + +license_scanning: + SETUP_CMD: ./setup.sh + ASDF_PYTHON_VERSION: "3.7.2" + before_script: + - echo "asdf install python 3.7.2 && pip install -r requirements.txt" > setup.sh + - chmod +x setup.sh + - apt-get -y update + - apt-get -y install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git +``` + ### `ERROR -- : asdf: No preset version installed for command` This error occurs when the version of the tools used by your project diff --git a/doc/user/discussions/img/mr_review_new_comment_v13_11.png b/doc/user/discussions/img/mr_review_new_comment_v13_11.png Binary files differnew file mode 100644 index 00000000000..6b4899bf67f --- /dev/null +++ b/doc/user/discussions/img/mr_review_new_comment_v13_11.png diff --git a/doc/user/discussions/img/review_preview.png b/doc/user/discussions/img/review_preview.png Binary files differdeleted file mode 100644 index e69a58dbb91..00000000000 --- a/doc/user/discussions/img/review_preview.png +++ /dev/null diff --git a/doc/user/discussions/img/review_preview_v13_11.png b/doc/user/discussions/img/review_preview_v13_11.png Binary files differnew file mode 100644 index 00000000000..79e33aa0991 --- /dev/null +++ b/doc/user/discussions/img/review_preview_v13_11.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 0ac79a011ca..aa49f9468be 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -119,7 +119,7 @@ the unresolved threads.  -Hitting **Submit issue** causes all threads to be marked as resolved and +Hitting **Create issue** causes all threads to be marked as resolved and add a note referring to the newly created issue.  @@ -269,10 +269,10 @@ Additionally, locked issues and merge requests can't be reopened. ## Confidential Comments > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9. -> - It's [deployed behind a feature flag](../feature_flags.md), 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. **(FREE SELF)** +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -285,7 +285,7 @@ To create a confidential comment, select the **Make this comment confidential** ## Merge request reviews -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. When looking at a merge request diff, you are able to start a review. @@ -334,22 +334,28 @@ comment itself.  +### Adding a new comment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. + +If you have a review in progress, you will be presented with the option to **Add to review**: + + + ### Submitting a review If you have any comments that have not been submitted, a bar displays at the bottom of the screen with two buttons: -- **Discard**: Discards all comments that have not been submitted. -- **Finish review**: Opens a list of comments ready to be submitted for review. - Clicking **Submit review** publishes all comments. Any quick actions - submitted are performed at this time. +- **Pending comments**: Opens a list of comments ready to be submitted for review. +- **Submit review**: Publishes all comments. Any quick actions submitted are performed at this time. Alternatively, to finish the entire review from a pending comment: -- Click the **Finish review** button on the comment. +- Click the **Submit review** button on the comment. - Use the `/submit_review` [quick action](../project/quick_actions.md) in the text of non-review comment. - + Submitting the review sends a single email to every notifiable user of the merge request with all the comments associated to it. @@ -486,11 +492,9 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ### Batch Suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). -> - It was deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) on GitLab 13.2. -> - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batch-suggestions). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. You can apply multiple suggestions at once to reduce the number of commits added to your branch to address your reviewers' requests. @@ -540,7 +544,7 @@ 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. + Click the button again to unassign the commenter.  @@ -562,24 +566,3 @@ To disable it: ```ruby Feature.disable(:confidential_notes) ``` - -## Enable or disable Batch Suggestions **(FREE SELF)** - -Batch Suggestions is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:batch_suggestions) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:batch_suggestions) -``` diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index a6be4c69f81..5be28de4101 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -18,9 +18,9 @@ may be unavailable to you. In this case, you'll see a warning like this in the feature documentation: -WARNING: -This feature might not be available to you. Review the **version history** note -on this page for details. +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. In the version history note, you'll find information on the state of the feature flag, including whether the feature is on ("enabled by default") or @@ -41,3 +41,17 @@ although changing a feature's default state isn't recommended. If you're a GitLab.com user and the feature is disabled, be aware that GitLab may be working on the feature for potential release in the future. + +## Risks when enabling features still in development + +Features that are disabled by default may change or be removed without notice in a future version of GitLab. + +Data corruption, stability degradation, or performance degradation might occur if +you enable a feature that's disabled by default. Problems caused by using a default +disabled feature aren't covered by GitLab support, unless you were directed by GitLab +to enable the feature. + +## Risks when disabling released features + +In most cases, the feature flag code is removed in a future version of GitLab. +If and when that occurs, from that point onward you can't keep the feature in a disabled state. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index c61e49993e6..6e38534b044 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -50,7 +50,7 @@ Projects can be backed up in their entirety by exporting them either [through th With exports, be sure to take note of [what is and is not](../project/settings/import_export.md#exported-contents), included in a project export. -Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki are included [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). +Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki are included [if they were uploaded after 2020-08-22](../project/wiki/index.md#create-a-new-wiki-page). ## Alternative SSH port @@ -113,7 +113,7 @@ or over the repository size limit, you can [reduce your repository size with Git | Setting | GitLab.com | Default | | ----------- | ----------- | ------------- | -| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | +| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | Unlimited | | Maximum import size | 5 GB | Unlimited ([Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to unlimited in GitLab 13.8. | NOTE: @@ -121,7 +121,7 @@ NOTE: ## IP range -GitLab.com is using the IP range `34.74.90.64/28` for traffic from its Web/API +GitLab.com uses the IP ranges `34.74.90.64/28` and `34.74.226.0/24` for traffic from its Web/API fleet. This whole range is solely allocated to GitLab. You can expect connections from webhooks or repository mirroring to come from those IPs and allow them. @@ -205,7 +205,7 @@ can be used for: - Downloading assets from a CDN - Any other commands that must run before the `git init` -To use this feature, define a [CI/CD variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) called +To use this feature, define a [CI/CD variable](../../ci/variables/README.md#custom-cicd-variables) called `CI_PRE_CLONE_SCRIPT` that contains a bash script. [This example](../../development/pipelines.md#pre-clone-step) diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index 651bb7c055e..aa356bee8e3 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -31,7 +31,7 @@ When bulk editing issues in a group, you can edit the following attributes: - [Epic](../epics/index.md) - [Milestone](../../project/milestones/index.md) - [Labels](../../project/labels.md) -- [Health status](../../project/issues/index.md#health-status) +- [Health status](../../project/issues/managing_issues.md#health-status) - [Iteration](../iterations/index.md) To update multiple project issues at the same time: diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index d9167388e66..87b259df9d8 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -86,7 +86,7 @@ your cluster, which can cause deployment jobs to fail. To clear the cache: -1. Navigate to your group’s **Kubernetes** page, +1. Navigate to your group's **Kubernetes** page, and select your cluster. 1. Expand the **Advanced settings** section. 1. Click **Clear cluster cache**. @@ -107,7 +107,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) +[environment-specific CI/CD variables](../../../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) work. While evaluating which environment matches the environment scope of a diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 813d2b8e265..016bda329b2 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -62,7 +62,7 @@ GitLab administrators can Within this section, you can configure the group where all the custom project templates are sourced. Every project _template_ directly under the group namespace is -available to every signed-in user, if all enabled [project features](../project/settings/index.md#sharing-and-permissions) are set to **Everyone With Access**. +available to every signed-in user, if all enabled [project features](../project/settings/index.md#sharing-and-permissions) except for GitLab Pages are set to **Everyone With Access**. However, private projects will be available only if the user is a member of the project. diff --git a/doc/user/group/devops_adoption/img/group_devops_adoption_v13_11.png b/doc/user/group/devops_adoption/img/group_devops_adoption_v13_11.png Binary files differnew file mode 100644 index 00000000000..a6ece47ba9a --- /dev/null +++ b/doc/user/group/devops_adoption/img/group_devops_adoption_v13_11.png diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md new file mode 100644 index 00000000000..920421ef9bb --- /dev/null +++ b/doc/user/group/devops_adoption/index.md @@ -0,0 +1,60 @@ +--- +stage: Manage +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Group DevOps Adoption **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11. +> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-group-devops-adoption). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). + +To access Group DevOps Adoption, navigate to your group sidebar and select **Analytics > DevOps Adoption** + +Group DevOps Adoption shows you how individual groups and sub-groups within your organization use the following features: + +- Issues +- Merge Requests +- Approvals +- Runners +- Pipelines +- Deployments +- Scans + +When managing groups in the UI, you can manage your sub-groups with the **Add/Remove sub-groups** +button, in the top right hand section of your Groups pages. + +DevOps Adoption allows you to: + +- Verify whether you are getting the return on investment that you expected from GitLab. +- Identify specific sub-groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. +- Find the sub-groups that have adopted certain features and can provide guidance to other sub-groups on how to use those features. + + + +## Enable or disable Group DevOps Adoption **(ULTIMATE)** + +Group DevOps Adoption 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. + +To enable it: + +```ruby +Feature.enable(:group_devops_adoption) +``` + +To disable it: + +```ruby +Feature.disable(:group_devops_adoption) +``` diff --git a/doc/user/group/epics/img/epic_board_v13_10.png b/doc/user/group/epics/img/epic_board_v13_10.png Binary files differindex 5148e6dd4ec..5a14d9288d3 100644 --- a/doc/user/group/epics/img/epic_board_v13_10.png +++ b/doc/user/group/epics/img/epic_board_v13_10.png diff --git a/doc/user/group/epics/img/epics_search.png b/doc/user/group/epics/img/epics_search.png Binary files differdeleted file mode 100644 index 96335527468..00000000000 --- a/doc/user/group/epics/img/epics_search.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_search_v13_11.png b/doc/user/group/epics/img/epics_search_v13_11.png Binary files differnew file mode 100644 index 00000000000..c11aca96a99 --- /dev/null +++ b/doc/user/group/epics/img/epics_search_v13_11.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 1cb024ceb01..12377b3926d 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -81,7 +81,7 @@ to: > - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. -Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/index.md#health-status), which then appears on your Epic tree. +Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/managing_issues.md#health-status), which then appears on your Epic tree. ## Multi-level child epics **(ULTIMATE)** diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 3c5e140965a..1999e5ba214 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -110,15 +110,17 @@ link in the issue sidebar. > - 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. +> - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. 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: +that of issues and merge requests) based on following parameters: - Title or description - Author name / username - Labels +- Reaction emoji - + To search, go to the list of epics and select the field **Search or filter results**. It displays a dropdown menu, from which you can add an author. You can also enter plain @@ -321,3 +323,36 @@ To remove a child epic from a parent epic: 1. Select the <kbd>x</kbd> button in the parent epic's list of epics. 1. Select **Remove** in the **Remove epic** warning message. + +## Cached epic count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299540) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-epic-count). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +In a group, the sidebar displays the total count of open epics and this value is cached if higher +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +### Enable or disable cached epic count **(PREMIUM SELF)** + +Cached epic count in the left sidebar is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it. + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_open_epics_count) +``` + +To enable it: + +```ruby +Feature.enable(:cached_sidebar_open_epics_count) +``` diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 302f12273cb..e84e35607e3 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -57,6 +57,7 @@ The following resources are migrated to the target instance: - due date - created at - updated at + - iid ([Introduced in 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/326157)) - Iterations ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/292428)) - iid - title @@ -66,6 +67,10 @@ The following resources are migrated to the target instance: - due date - created at - updated at +- Badges ([Introduced in 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/292431)) + - name + - link URL + - image URL Any other items are **not** migrated. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 36d292f670d..d070277beed 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -7,21 +7,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Groups **(FREE)** -In GitLab, you can put related projects together in a group. +In GitLab, you use groups to manage one or more related projects at the same time. -For example, you might create a group for your company members and a subgroup for each individual team. -You can name the group `company-team`, and the subgroups `backend-team`, `frontend-team`, and `production-team`. +You can use groups to manage permissions for your projects. If someone has access to +the group, they get access to all the projects in the group. -Then you can: +You can also view all of the issues and merge requests for the projects in the group, +and view analytics that show the group's activity. -- Grant members access to multiple projects at once. -- Add to-do items for all of the group members at once. -- View the [issues](../project/issues/index.md#issues-list) and - [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) - for all projects in the group, together in a single list view. -- [Bulk edit](../group/bulk_editing/index.md) issues, epics, and merge requests. +You can use groups to communicate with all of the members of the group at once. -You can also create [subgroups](subgroups/index.md). +For larger organizations, you can also create [subgroups](subgroups/index.md). ## View groups @@ -140,7 +136,7 @@ To remove a member from a group: 1. From the left menu, select **Members**. 1. Next to the member you want to remove, select **Delete**. 1. Optional. On the **Remove member** confirmation box, select the - **Also unassign this user from related issues and merge requests** checkbox. + **Also unassign this user from linked issues and merge requests** checkbox. 1. Select **Remove member**. ## Filter and sort members in a group @@ -261,6 +257,9 @@ To view the activity feed in Atom format, select the > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. +NOTE: +In GitLab 13.11, you can [replace this form with a modal window](#share-a-group-modal-window). + Similar to how you [share a project with a group](../project/members/share_project_with_groups.md), you can share a group with another group. Members get direct access to the shared group. This is not valid for inherited members. @@ -277,6 +276,27 @@ To share a given group, for example, `Frontend` with another group, for example, All the members of the `Engineering` group are added to the `Frontend` group. +### Share a group modal window + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11. +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - Replaces the existing form with buttons to open a modal window. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../project/members/index.md#enable-or-disable-modal-window). **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +In GitLab 13.11, you can optionally replace the sharing form with a modal window. +To share a group after enabling this feature: + +1. Go to your group's page. +1. In the left sidebar, go to **Members**, and then select **Invite a group**. +1. Select a group, and select a **Max access level**. +1. (Optional) Select an **Access expiration date**. +1. Select **Invite**. + ## Manage group memberships via LDAP **(PREMIUM SELF)** 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. @@ -322,25 +342,6 @@ LDAP user permissions can be manually overridden by an administrator. To overrid Now you can edit the user's permissions from the **Members** page. -## Group wikis **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. - -Group wikis work the same way as [project wikis](../project/wiki/index.md). - -Group wikis can be edited by members with [Developer permissions](../../user/permissions.md#group-members-permissions) -and above. - -You can move group wiki repositories by using the [Group repository storage moves API](../../api/group_repository_storage_moves.md). - -There are a few limitations compared to project wikis: - -- Git LFS is not supported. -- Group wikis are not included in global search. -- Changes to group wikis don't show up in the group's activity feed. - -For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). - ## Transfer a group You can transfer groups in the following ways: @@ -387,16 +388,10 @@ because the project cannot be moved. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. -By default, when you create a new project in GitLab, the initial branch is called `master`. -For groups, a group owner can customize the initial branch name to something -else. This way, every new project created under that group from then on starts from the custom branch name rather than `master`. - -To use a custom name for the initial branch: - -1. Go to the group's **Settings > Repository** page. -1. Expand the **Default initial branch name** section. -1. Change the default initial branch to a custom name of your choice. -1. Select **Save changes**. +When you create a new project in GitLab, a default branch is created with the +first push. The group owner can +[customize the initial branch](../project/repository/branches/default.md#group-level-custom-initial-branch-name) +for the group's projects to meet your group's needs. ## Remove a group @@ -434,7 +429,7 @@ To prevent a project from being shared with other groups: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. -1. Select **Prevent sharing a project within <group_name> with other groups**. +1. Select **Prevent sharing a project within `<group_name>` with other groups**. 1. Select **Save changes**. ## Prevent members from being added to a group **(PREMIUM)** @@ -460,33 +455,36 @@ API requests to add a new user to a project are not possible. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.1. -NOTE: -IP access restrictions are not functioning as expected on GitLab.com. If enabled, -users cannot perform Git operations through SSH, or access projects in the UI. -For more information, [see this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). - To ensure only people from your organization can access particular -resources, you can restrict access to groups by IP address. This setting applies to all subgroups, -projects, issues, and so on. - -IP access restrictions can be configured at the group level only. +resources, you can restrict access to groups by IP address. This group-level setting +applies to: -This restriction applies to: - -- The GitLab UI. +- The GitLab UI, including subgroups, projects, and issues. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. -- [In GitLab 12.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/32113), Git actions via SSH. -Administrators and group owners are able to access the group regardless of the IP restriction. +You should consider these security implications before configuring IP address restrictions: + +- **SSH requests**: While you can restrict HTTP traffic on GitLab.com with IP address restrictions, + they cause SSH requests, including Git operations over SSH, to fail. For more information, + read [issue 271673](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). +- **Administrators and group owners**: Users with these permission levels can always + access the group settings, regardless of IP restriction, but they cannot access projects + belonging to the group when accessing from a disallowed IP address. +- **GitLab API and runner activities**: Only the [Groups](../../api/groups.md) + and [Projects](../../api/projects.md) APIs are protected by IP address restrictions. + When you register a runner, it is not bound by the IP restrictions. When the runner + requests a new job or an update to a job's state, it is also not bound by + the IP restrictions. But when the running CI/CD job sends Git requests from a + restricted IP address, the IP restriction prevents code from being cloned. To restrict group access by IP address: -1. Go to the group’s **Settings > General** page. +1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. 1. In the **Allow access to the following IP addresses** field, enter IP address ranges in CIDR notation. 1. Select **Save changes**. - +  ## Restrict group access by domain **(PREMIUM)** @@ -638,6 +636,7 @@ The group's new subgroups have push rules set for them based on either: ## Related topics +- [Group wikis](../project/wiki/index.md) - [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). **(FREE SELF)** - [Repositories analytics](repositories_analytics/index.md): View overall activity of all projects with code coverage. **(PREMIUM)** - [Contribution analytics](contribution_analytics/index.md): View the contributions (pushes, merge requests, @@ -662,3 +661,15 @@ The group's new subgroups have push rules set for them based on either: - [Lock the sharing with group feature](#prevent-a-project-from-being-shared-with-groups). - [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. + +## Troubleshooting + +### Verify if access is blocked by IP restriction + +If a user sees a 404 when they would normally expect access, and the problem is limited to a specific group, search the `auth.log` rails log for one or more of the following: + +- `json.message`: `'Attempting to access IP restricted group'` +- `json.allowed`: `false` + +In viewing the log entries, compare the `remote.ip` with the list of +[allowed IPs](#restrict-group-access-by-ip-address) for the group. diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png Binary files differdeleted file mode 100644 index 0e338b99e4c..00000000000 --- a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png +++ /dev/null diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png Binary files differnew file mode 100644 index 00000000000..1ef49191a13 --- /dev/null +++ b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png diff --git a/doc/user/group/insights/img/insights_sidebar_link_v12_8.png b/doc/user/group/insights/img/insights_sidebar_link_v12_8.png Binary files differdeleted file mode 100644 index 9a6d6bae766..00000000000 --- a/doc/user/group/insights/img/insights_sidebar_link_v12_8.png +++ /dev/null diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index b559e6806e9..4975b27a66d 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -13,14 +13,12 @@ Configure the Insights that matter for your groups to explore data such as triage hygiene, issues created/closed per a given period, average time for merge requests to be merged and much more. - + ## View your group's Insights You can access your group's Insights by clicking the **Analytics > Insights** -link in the left sidebar: - - +link in the left sidebar. ## Configure your Insights diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 8e125a0cc6e..38d209f04ca 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -8,11 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Iterations **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in GitLab 13.1. -> - It was deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) on GitLab 13.2. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-group. -> - It's recommended for production use. +> - Deployed behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 13.2. +> - Enabled on GitLab.com. +> - Able to be enabled or disabled per-group. +> - Recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(PREMIUM ONLY)** > - Moved to GitLab Premium in 13.9. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 42522723047..ef47ceadd88 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -69,7 +69,7 @@ For each day that a coverage report was generated by a job in a project's pipeli If the project's code coverage was calculated more than once in a day, we will take the last value from that day. NOTE: -[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/index.md#default-branch). In earlier versions, it is taken from the `master` branch. +[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/default.md). In earlier versions, it is taken from the `master` branch. <!-- ## Troubleshooting diff --git a/doc/user/group/roadmap/img/roadmap_filters_v13_11.png b/doc/user/group/roadmap/img/roadmap_filters_v13_11.png Binary files differnew file mode 100644 index 00000000000..d2a76b4edce --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_filters_v13_11.png diff --git a/doc/user/group/roadmap/img/roadmap_filters_v13_8.png b/doc/user/group/roadmap/img/roadmap_filters_v13_8.png Binary files differdeleted file mode 100644 index d826909b022..00000000000 --- a/doc/user/group/roadmap/img/roadmap_filters_v13_8.png +++ /dev/null diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 9b3ae75b39c..88d43715c58 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -42,6 +42,7 @@ toggle the list of the milestone bars. > - Filtering roadmaps by milestone is recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM SELF)** > - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.9. +> - Filtering by epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218623) in GitLab 13.11. WARNING: Filtering roadmaps by milestone might not be available to you. Check the **version history** note above for details. @@ -69,8 +70,10 @@ You can also filter epics in the Roadmap view by the epics': - Label - Milestone - Confidentiality +- Epic +- Your Reaction - + Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 9f2cafd456b..a9b1901bc8c 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -84,6 +84,16 @@ To access the Credentials inventory of a group, navigate to **{shield}** **Secur This feature is similar to the [Credentials inventory for self-managed instances](../../admin_area/credentials_inventory.md). +### Revoke a group-managed account's personal access token + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214811) in GitLab 13.5. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267184) in GitLab 13.10. + +Group owners can revoke the personal access tokens of accounts in their group. To do so, select +the Personal Access Tokens tab, and select Revoke. + +When a personal access token is revoked, the group-managed account user is notified by email. + ## Limiting lifetime of personal access tokens of users in Group-managed accounts **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118893) in GitLab 12.10. diff --git a/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png Binary files differdeleted file mode 100644 index f9c63970f16..00000000000 --- a/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png +++ /dev/null diff --git a/doc/user/group/saml_sso/img/scim_provisioning_status.png b/doc/user/group/saml_sso/img/scim_provisioning_status.png Binary files differdeleted file mode 100644 index 41466ec9276..00000000000 --- a/doc/user/group/saml_sso/img/scim_provisioning_status.png +++ /dev/null diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 004efe7b244..f2f28046443 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -10,24 +10,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 11.0. This page describes SAML for Groups. For instance-wide SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md). +[View the differences between SaaS and Self-Managed Authentication and Authorization Options](../../../administration/auth/README.md#saas-vs-self-managed-comparison). SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. -If you follow our guidance to automate user provisioning using [SCIM](scim_setup.md) or [group-managed accounts](group_managed_accounts.md), you do not need to create such accounts manually. - -User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group. +User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group automatically. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. SAML SSO is only configurable at the top-level group. -## Configuring your Identity Provider +If required, you can find [a glossary of common terms](../../../integration/saml.md#glossary-of-common-terms). -1. Navigate to the group and select **Settings > SAML SSO**. -1. Configure your SAML server using the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [specific identity provider documentation](#providers) for more details. +## Configuring your identity provider + +1. Navigate to the GitLab group and select **Settings > SAML SSO**. +1. Configure your SAML identity provider using the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. + Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). + See [specific identity provider documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. 1. Configure [required assertions](#assertions) at minimum containing the user's email address. -1. While the default is enabled for most SAML providers, please ensure the app is set to have [Service Provider](#glossary) initiated calls in order to link existing GitLab accounts. +1. While the default is enabled for most SAML providers, please ensure the app is set to have service provider + initiated calls in order to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab).  @@ -57,30 +61,25 @@ We recommend setting the NameID format to `Persistent` unless using a field (suc ### Assertions For users to be created with the right information with the improved [user access and management](#user-access-and-management), -the following user details need to be passed to GitLab as SAML assertions. +the user details need to be passed to GitLab as SAML assertions. -| Field | Supported keys | -|-----------------|----------------| -| Email (required)| `email`, `mail` | -| Username | `username`, `nickname` | -| Full Name | `name` | -| First Name | `first_name`, `firstname`, `firstName` | -| Last Name | `last_name`, `lastname`, `lastName` | +At a minimum, the user's email address *must* be specified as an assertion named `email` or `mail`. +See [the assertions list](../../../integration/saml.md#assertions) for other available claims. ### Metadata configuration -GitLab provides metadata XML that can be used to configure your Identity Provider. +GitLab provides metadata XML that can be used to configure your identity provider. 1. Navigate to the group and select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. -1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. +1. Follow your identity provider's documentation and paste the metadata URL when it's requested. ## Configuring GitLab After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. Navigate to the group's **Settings > SAML SSO**. -1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. +1. Find the SSO URL from your identity provider and enter it the **Identity provider single sign-on URL** field. 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. 1. Select the access level to be applied to newly added users in the **Default membership role** field. The default access level is 'Guest'. 1. Select the **Enable SAML authentication for this group** toggle switch. @@ -89,7 +88,7 @@ After you set up your identity provider to work with GitLab, you must configure  NOTE: -Please note that the certificate [fingerprint algorithm](#additional-providers-and-setup-options) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. +Please note that the certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. ### SSO enforcement @@ -97,32 +96,42 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. +- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. -With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. +With this option enabled, users (except owners) must go through your group's GitLab single sign-on URL if they wish to access group resources through the UI. Users can't be manually added as members. + +SSO enforcement does not affect sign in or access to any resources outside of the group. Users can view which groups and projects they are a member of without SSO sign in. However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab prompts the user to sign in again through SSO. -We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). +We intend to add a similar SSO requirement for [API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). -When SSO enforcement is enabled for a group, users can't share a project in the group outside the top-level group, even if the project is forked. +SSO has the following effects when enabled: -## Providers +- For groups, users can't share a project in the group outside the top-level group, + even if the project is forked. +- For a Git activity, users must be signed-in through SSO before they can push to or + pull from a GitLab repository. +<!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> -NOTE: -GitLab is unable to provide full support for integrating identity providers that are not listed here. +## Providers -| Provider | Documentation | -|----------|---------------| -| Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) | -| Okta | [Setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) | -| OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) | +The SAML standard means that a wide range of identity providers will work with GitLab. Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. When [configuring your identity 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. +For providers not listed below, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#notes-on-configuring-your-identity-provider) +for additional guidance on information your identity provider may require. + +Please note that GitLab provides the following for guidance only. +If you have any questions on configuring the SAML app, please contact your provider's support. + ### Azure setup notes +Please follow the Azure documentation on [configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) with the notes below for consideration. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regard to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). @@ -142,6 +151,8 @@ We recommend: ### Okta setup notes +Please follow the Okta documentation on [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) with the notes below for consideration. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ). @@ -165,7 +176,7 @@ OneLogin supports their own [GitLab (SaaS)](https://onelogin.service-now.com/sup application. If you decide to use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), -we recommend the following settings: +we recommend the ["Use the OneLogin SAML Test Connector" documentation](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) with the following settings: | GitLab Setting | OneLogin Field | |--------------|----------------| @@ -178,40 +189,6 @@ we recommend the following settings: Recommended `NameID` value: `OneLogin ID`. -### Additional providers and setup options - -The SAML standard means that a wide range of identity providers will work with GitLab. Unfortunately we have not verified connections with all SAML providers. -For more information, see our [discussion on providers](#providers). - -Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. Examples: - -- [ADFS (Active Directory Federation Services)](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) -- [Auth0](https://auth0.com/docs/protocols/saml-protocol/configure-auth0-as-saml-identity-provider) -- [Google Workspace](https://support.google.com/a/answer/6087519?hl=en) -- [JumpCloud](https://support.jumpcloud.com/support/s/article/single-sign-on-sso-with-gitlab-2019-08-21-10-36-47) -- [PingOne by Ping Identity](https://docs.pingidentity.com/bundle/pingone/page/xsh1564020480660-1.html) - -Your Identity Provider may require additional configuration, such as the following: - -| Field | Value | Notes | -|-------|-------|-------| -| SAML Profile | Web browser SSO profile | GitLab uses SAML to sign users in via their browser. We don't make requests direct to the Identity Provider. | -| SAML Request Binding | HTTP Redirect | GitLab (the service provider) redirects users to your Identity Provider with a base64 encoded `SAMLRequest` HTTP parameter. | -| SAML Response Binding | HTTP POST | Your Identity Provider responds to users with an HTTP form including the `SAMLResponse`, which a user's browser submits back to GitLab. | -| Sign SAML Response | Yes | We require this to prevent tampering. | -| X.509 Certificate in response | Yes | This is used to sign the response and checked against the provided fingerprint. | -| Fingerprint Algorithm | SHA-1 | We need a SHA-1 hash of the certificate used to sign the SAML Response. | -| Signature Algorithm | SHA-1/SHA-256/SHA-384/SHA-512 | Also known as the Digest Method, this can be specified in the SAML response. It determines how a response is signed. | -| Encrypt SAML Assertion | No | TLS is used between your Identity Provider, the user's browser, and GitLab. | -| Sign SAML Assertion | Optional | We don't require Assertions to be signed. We validate their integrity by requiring the whole response to be signed. | -| Check SAML Request Signature | No | GitLab does not sign SAML requests, but does check the signature on the SAML response. | -| Default RelayState | Optional | The URL users should end up on after signing in via a button on your Identity Provider. | -| NameID Format | `Persistent` | See [details above](#nameid-format). | -| Additional URLs | | You may need to use the `Identifier` or `Assertion consumer service URL` in other fields on some providers. | -| Single Sign Out URL | | Not supported | - -If the information you need isn't listed above you may wish to check our [troubleshooting docs below](#i-need-additional-information-to-configure-my-identity-provider). - ## User access and management > [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. @@ -231,9 +208,9 @@ When a user tries to sign in with Group SSO, GitLab attempts to find or create a To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. -1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. +1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the identity provider. 1. Select **Authorize**. -1. Enter your credentials on the Identity Provider if prompted. +1. Enter your credentials on the identity provider if prompted. 1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider. @@ -369,18 +346,6 @@ Users who are not members of any mapped SAML groups are removed from the GitLab You can prevent accidental member removal. For example, if you have a SAML group link for `Owner` level access in a top-level group, you should also set up a group link for all other members. -## Glossary - -| Term | Description | -|------|-------------| -| Identity Provider | The service which manages your user identities such as ADFS, Okta, OneLogin, or Ping Identity. | -| Service Provider | SAML considers GitLab to be a service provider. | -| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | -| SSO | Single Sign On. | -| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | -| Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | -| Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | - ## Passwords for users created via SAML SSO for Groups The [Generated passwords for users created through integrated authentication](../../../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via SAML SSO for Groups. @@ -412,7 +377,7 @@ In troubleshooting the Group SAML setup, any authenticated user can use the API Similarly, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. -This can then be compared to the [NameID](#nameid) being sent by the Identity Provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match in order to identify users. +This can then be compared to the [NameID](#nameid) being sent by the identity provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match in order to identify users. ### Users receive a 404 @@ -432,7 +397,7 @@ Here are possible causes and solutions: | Cause | Solution | |------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| You've tried to link multiple SAML identities to the same user, for a given Identity Provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](#unlinking-accounts) from this GitLab account before attempting to sign in again. | +| You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](#unlinking-accounts) from this GitLab account before attempting to sign in again. | ### Message: "SAML authentication failed: Email has already been taken" @@ -442,7 +407,7 @@ Here are possible causes and solutions: ### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" -Getting both of these errors at the same time suggests the NameID capitalization provided by the Identity Provider didn't exactly match the previous value for that user. +Getting both of these errors at the same time suggests the NameID capitalization provided by the identity provider didn't exactly match the previous value for that user. This can be prevented by configuring the [NameID](#nameid) to return a consistent value. Fixing this for an individual user involves [unlinking SAML in the GitLab account](#unlinking-accounts), although this will cause group membership and to-dos to be lost. @@ -452,8 +417,8 @@ Ensure that the user who is trying to link their GitLab account has been added a Alternatively, the SAML response may be missing the `InResponseTo` attribute in the `samlp:Response` tag, which is [expected by the SAML gem](https://github.com/onelogin/ruby-saml/blob/9f710c5028b069bfab4b9e2b66891e0549765af5/lib/onelogin/ruby-saml/response.rb#L307-L316). -The [Identity Provider](#glossary) administrator should ensure that the login is -initiated by the Service Provider (typically GitLab) and not the Identity Provider. +The identity provider administrator should ensure that the login is +initiated by the service provider and not the identity provider. ### Stuck in a login "loop" @@ -469,13 +434,15 @@ Alternatively, when users need to [link SAML to their existing GitLab.com accoun ### I need to change my SAML app -Users will need to [unlink the current SAML identity](#unlinking-accounts) and [link their identity](#user-access-and-management) to the new SAML app. +If the NameID is identical in both SAML apps, then no change is required. + +Otherwise, to change the SAML app used for sign in, users need to [unlink the current SAML identity](#unlinking-accounts) and then [link their identity](#user-access-and-management) to the new SAML app. ### I need additional information to configure my identity provider Many SAML terms can vary between providers. It is possible that the information you are looking for is listed under another name. -For more information, start with your Identity Provider's documentation. Look for their options and examples to see how they configure SAML. This can provide hints on what you'll need to configure GitLab to work with these providers. +For more information, start with your identity provider's documentation. Look for their options and examples to see how they configure SAML. This can provide hints on what you'll need to configure GitLab to work with these providers. It can also help to look at our [more detailed docs for self-managed GitLab](../../../integration/saml.md). SAML configuration for GitLab.com is mostly the same as for self-managed instances. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 35374812b37..7bf54aea60e 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -20,7 +20,6 @@ The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 prot The following actions are available: - Create users -- Update users (Azure only) - Deactivate users The following identity providers are supported: @@ -51,19 +50,13 @@ Once [Group Single Sign-On](index.md) has been configured, we can: The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) now needs to be set up for SCIM. -1. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This matches the `extern_uid` used on GitLab. - -  - 1. Set up automatic provisioning and administrative credentials by following the - [Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) section in Azure's SCIM setup documentation. + [Azure's SCIM setup documentation](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim). During this configuration, note the following: - The `Tenant URL` and `secret token` are the ones retrieved in the [previous step](#gitlab-configuration). -- Should there be any problems with the availability of GitLab or similar - errors, the notification email set gets those. - It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox. - For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled. @@ -71,42 +64,30 @@ You can then test the connection by clicking on **Test Connection**. If the conn #### Configure attribute mapping -1. Click on `Synchronize Azure Active Directory Users to AppName` to configure the attribute mapping. -1. Click **Delete** next to the `mail` mapping. -1. Map `userPrincipalName` to `emails[type eq "work"].value` and change its **Matching precedence** to `2`. -1. Map `mailNickname` to `userName`. -1. Determine how GitLab uniquely identifies users. - - - Use `objectId` unless users already have SAML linked for your group. - - If you already have users with SAML linked then use the `Name ID` value from the [SAML configuration](#azure). Using a different value may cause duplicate users and prevent users from accessing the GitLab group. - -1. Create a new mapping: - 1. Click **Add New Mapping**. - 1. Set: - - **Source attribute** to the unique identifier determined above, typically `objectId`. - - **Target attribute** to `externalId`. - - **Match objects using this attribute** to `Yes`. - - **Matching precedence** to `1`. +Follow [Azure documentation to configure the attribute mapping](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes). -1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`. +The following table below provides an attribute mapping known to work with GitLab. If +your SAML configuration differs from [the recommended SAML settings](index.md#azure-setup-notes), +modify the corresponding `customappsso` settings accordingly. If a mapping is not listed in the +table, use the Azure defaults. -1. Save your changes. For reference, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). +| Azure Active Directory Attribute | customappsso Attribute | Matching precedence | +| -------------------------------- | ---------------------- | -------------------- | +| `objectId` | `externalId` | 1 | +| `userPrincipalName` | `emails[type eq "work"].value` | | +| `mailNickname` | `userName` | | - NOTE: - If you used a unique identifier **other than** `objectId`, be sure to map it to `externalId`. +For guidance, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). 1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. - 1. Ensure the `id` is the primary and required field, and `externalId` is also required. NOTE: `username` should neither be primary nor required as we don't support that field on GitLab SCIM yet. -1. Save all the screens and, in the **Provisioning** step, set - the `Provisioning Status` to `On`. - -  +1. Save all changes. +1. In the **Provisioning** step, set the `Provisioning Status` to `On`. NOTE: You can control what is actually synced by selecting the `Scope`. For example, @@ -168,6 +149,10 @@ As the app is developed by OneLogin, please reach out to OneLogin if you encount ## User access and linking setup +During the synchronization process, all of your users get GitLab accounts, welcoming them +to their respective groups, with an invitation email. When implementing SCIM provisioning, +you may want to warn your security-conscious employees about this email. + The following diagram is a general outline on what happens when you add users to your SCIM app: ```mermaid @@ -202,10 +187,6 @@ Upon the next sync, the user is deprovisioned, which means that the user is remo NOTE: Deprovisioning does not delete the user account. -During the synchronization process, all of your users get GitLab accounts, welcoming them -to their respective groups, with an invitation email. When implementing SCIM provisioning, -you may want to warn your security-conscious employees about this email. - ```mermaid graph TD A[Remove User from SCIM app] -->|IdP sends request to GitLab| B(GitLab: Is the user part of the group?) diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 16430b49549..df0d297a82a 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -117,7 +117,7 @@ Follow the same process to create any subsequent groups. ## Membership When you add a member to a group, that member is also added to all subgroups. -Permission level is inherited from the group’s parent. This model allows access to +Permission level is inherited from the group's parent. This model allows access to subgroups if you have membership in one of its parents. Jobs for pipelines in subgroups can use [runners](../../../ci/runners/README.md) registered to the parent group(s). diff --git a/doc/user/group/value_stream_analytics/img/extended_value_stream_form_v13_10.png b/doc/user/group/value_stream_analytics/img/extended_value_stream_form_v13_10.png Binary files differindex 26508787177..e2752ad1157 100644 --- a/doc/user/group/value_stream_analytics/img/extended_value_stream_form_v13_10.png +++ b/doc/user/group/value_stream_analytics/img/extended_value_stream_form_v13_10.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_custom_stage_v13_10.png b/doc/user/group/value_stream_analytics/img/vsa_custom_stage_v13_10.png Binary files differindex 77f4a26b880..9345c4023de 100644 --- a/doc/user/group/value_stream_analytics/img/vsa_custom_stage_v13_10.png +++ b/doc/user/group/value_stream_analytics/img/vsa_custom_stage_v13_10.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_default_stage_v13_10.png b/doc/user/group/value_stream_analytics/img/vsa_default_stage_v13_10.png Binary files differindex 1adb114b025..a29689a2c18 100644 --- a/doc/user/group/value_stream_analytics/img/vsa_default_stage_v13_10.png +++ b/doc/user/group/value_stream_analytics/img/vsa_default_stage_v13_10.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_path_nav_v13_11.png b/doc/user/group/value_stream_analytics/img/vsa_path_nav_v13_11.png Binary files differnew file mode 100644 index 00000000000..5dd79d06463 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_path_nav_v13_11.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 52cf51d85a4..6a512d78696 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -76,20 +76,15 @@ GitLab provides the ability to filter analytics based on a date range. To filter 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. - -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. +- **Cycle time**: median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../../project/issues/crosslinking_issues.md#from-commit-messages).)  ## How the stages are measured -Value Stream Analytics records stage time and data based on the project issues with the -exception of the staging stage, where only data deployed to -production are measured. - -Specifically, if your CI is not set up and you have not defined a [production environment](#how-the-production-environment-is-identified), then you will not have any -data for this stage. +Value Stream Analytics measures each stage from its start event to its stop event. +For example, a stage might start when one label is added to an issue, and end when another label is added. +Value Stream Analytics excludes work in progress, meaning it ignores any items that have not reached the stop event. Each stage of Value Stream Analytics is further described in the table below. @@ -193,17 +188,37 @@ GitLab allows users to create multiple value streams, hide default stages and cr ### Stage path -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/feature_flags.md). **(FREE SELF)** + + -Stages are visually depicted as a horizontal process flow. Selecting a stage will update the -the content below the value stream. +Stages are visually depicted as a horizontal process flow. Selecting a stage updates the content +below the value stream. -This is disabled by default. If you have a self-managed instance, an +The stage time is displayed next to the name of each stage, in the following format: + +| Symbol | Description | +|--------|-------------| +| `m` | Minutes | +| `h` | Hours | +| `d` | Days | +| `w` | Weeks | +| `M` | Months | + +Hovering over a stage item displays a popover with the following information: + +- Start event description for the given stage +- End event description + +Horizontal path navigation is enabled by default. If you have a self-managed instance, an administrator can [open a Rails console](../../../administration/troubleshooting/navigating_gitlab_via_rails_console.md) -and enable it with the following command: +and disable it with the following command: ```ruby -Feature.enable(:value_stream_analytics_path_navigation) +Feature.disable(:value_stream_analytics_path_navigation) ``` ### Adding a stage @@ -299,17 +314,16 @@ To create a value stream: 1. Navigate to your group's **Analytics > Value Stream**. 1. Click the Value stream dropdown and select **Create new Value Stream** 1. Fill in a name for the new Value Stream - - You can [customize the stages](#creating-a-value-stream-with-stages) as the `value_stream_analytics_extended_form` feature flag is enabled. + - You can [customize the stages](#creating-a-value-stream-with-stages) 1. Click the **Create Value Stream** button.  #### Creating a value stream with stages -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55572) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/feature_flags.md). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50229) in GitLab 13.7. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55572) in GitLab 13.10. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294190) in GitLab 13.11. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -331,27 +345,6 @@ To create a value stream with stages:  -#### Enable or disable value stream with stages - -Value streams with stages is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -# For the instance -Feature.enable(:value_stream_analytics_extended_form) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:value_stream_analytics_extended_form) -``` - ### Deleting a value stream > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. diff --git a/doc/user/img/new_project_snippet_from_project_v12_10.png b/doc/user/img/new_project_snippet_from_project_v12_10.png Binary files differdeleted file mode 100644 index 7fa17beaae6..00000000000 --- a/doc/user/img/new_project_snippet_from_project_v12_10.png +++ /dev/null diff --git a/doc/user/img/snippet_intro_v13_11.png b/doc/user/img/snippet_intro_v13_11.png Binary files differnew file mode 100644 index 00000000000..aa2ad5fd43a --- /dev/null +++ b/doc/user/img/snippet_intro_v13_11.png diff --git a/doc/user/img/snippet_tooltip_v13_10.png b/doc/user/img/snippet_tooltip_v13_10.png Binary files differnew file mode 100644 index 00000000000..fd5961c2b08 --- /dev/null +++ b/doc/user/img/snippet_tooltip_v13_10.png diff --git a/doc/user/index.md b/doc/user/index.md index 7541e3e85f9..872dbd09c7d 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -42,7 +42,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Hosting code in repositories with version control. - Tracking proposals for new implementations, bug reports, and feedback with a - fully featured [Issue Tracker](project/issues/index.md#issues-list). + fully featured [Issue tracker](project/issues/index.md). - Organizing and prioritizing with [Issue Boards](project/issue_board.md). - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). @@ -59,7 +59,7 @@ With GitLab Enterprise Edition, you can also: - [Merge Request Approvals](project/merge_requests/merge_request_approvals.md). - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). -- Create formal relationships between issues with [Related Issues](project/issues/related_issues.md). +- Create formal relationships between issues with [linked issues](project/issues/related_issues.md). - Use [Burndown Charts](project/milestones/burndown_and_burnup_charts.md) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_search.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](../integration/kerberos.md). @@ -70,7 +70,7 @@ With GitLab Enterprise Edition, you can also: - Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). - Scan your code for vulnerabilities and [display them in merge requests](application_security/sast/index.md). -You can also [integrate](project/integrations/overview.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, Jira, and a lot more. +You can also [integrate](project/integrations/overview.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, Trello, Slack, Bamboo CI, Jira, and a lot more. ## User types diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 927552b90be..6f8b1d8d569 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -10,7 +10,7 @@ Collaborating around Infrastructure as Code (IaC) changes requires both code cha ## 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/yaml/README.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 creates, modifies, or destroys. @@ -57,7 +57,7 @@ To manually configure a GitLab Terraform Report artifact requires the following 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). + [GitLab Terraform Report artifact](../../ci/yaml/README.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. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index f935fa87d68..bc1e59e4ac2 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab Premium 13.2. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +> - Support for Composer 2.0 [added](https://gitlab.com/gitlab-org/gitlab/-/issues/259840) in GitLab Free 13.10. Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. -Only Composer 1.x is supported. Consider contributing or even adding support for -[Composer 2.0 in the Package Registry](https://gitlab.com/gitlab-org/gitlab/-/issues/259840). +For documentation of the specific API endpoints that the Composer +client uses, see the [Composer API documentation](../../../api/packages/composer.md). ## Create a Composer package @@ -268,10 +269,36 @@ To install a package: Without the `gitlab-domains` definition in `composer.json`, Composer uses the GitLab token as basic-auth, with the token as a username and a blank password. This results in a 401 error. -Output indicates that the package has been successfully installed. +1. With the `composer.json` and `auth.json` files configured, you can install the package by running: + + ```shell + composer update + ``` + + Or to install the single package: + + ```shell + composer req <package-name>:<package-version> + ``` + + If successful, you should see output indicating that the package installed successfully. + + You can also install from source (by pulling the Git repository directly) using the + `--prefer-source` option: + + ```shell + composer update --prefer-source + ``` WARNING: Never commit the `auth.json` file to your repository. To install packages from a CI/CD job, consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your personal access token stored in a [GitLab CI/CD variable](../../../ci/variables/README.md) or in [HashiCorp Vault](../../../ci/secrets/index.md). + +## Supported CLI commands + +The GitLab Composer repository supports the following Composer CLI commands: + +- `composer install`: Install Composer dependencies. +- `composer update`: Install the latest version of Composer dependencies. diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 3b8be68cff6..9df4aeb404a 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -18,6 +18,9 @@ remote and authenticate with it. Then you can run `conan` commands and publish your package to the Package Registry. +For documentation of the specific API endpoints that the Conan package manager +client uses, see the [Conan API documentation](../../../api/packages/conan.md). + ## Build a Conan package This section explains how to install Conan and build a package for your C/C++ @@ -125,7 +128,7 @@ To add the remote: For example: ```shell - conan search Hello* --all --remote=gitlab + conan search Hello* --remote=gitlab ``` ### Add a remote for your instance @@ -402,16 +405,3 @@ The GitLab Conan repository supports the following Conan CLI commands: packages you have permission to view. - `conan info`: View the information on a given package from the Package Registry. - `conan remove`: Delete the package from the Package Registry. - -## Troubleshooting Conan packages - -### `ERROR: <package> was not found in remote <remote>` - -When you attempt to install a Conan package, you might receive a `404` error -like `ERROR: <package> was not found in remote <remote>`. - -This issue occurs when you request a download from the project-level Conan API. -The resulting URL is missing is project's `/<id>` and Conan commands, like -`conan install`, fail. - -For more information, see [issue 270129](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 18c4edd61c7..bc96d3c937c 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Container Registry +# GitLab Container Registry **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) in GitLab 8.8. > - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker @@ -35,7 +35,8 @@ You can view the Container Registry for a project or group. 1. Go to your project or group. 1. Go to **Packages & Registries > Container Registry**. -You can search, sort, filter, and [delete](#delete-images-from-within-gitlab) containers on this page. +You can search, sort, filter, and [delete](#delete-images-from-within-gitlab) +containers on this page. You can share a filtered view by copying the URL from your browser. Only members of the project or group can access a private project's Container Registry. @@ -499,11 +500,11 @@ The cleanup policy: 1. Collects all tags for a given repository in a list. 1. Excludes the tag named `latest` from the list. 1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list. +1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). 1. Excludes any tags that do not have a manifest (not part of the options in the UI). 1. Orders the remaining tags by `created_date`. 1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). 1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval). -1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). 1. Finally, the remaining tags in the list are deleted from the Container Registry. WARNING: @@ -635,6 +636,14 @@ Examples: curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' "https://gitlab.example.com/api/v4/projects/2" ``` +Valid values for `cadence` when using the API are: + +- `1d` (every day) +- `7d` (every week) +- `14d` (every two weeks) +- `1month` (every month) +- `3month` (every quarter) + See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). ### Use with external container registries @@ -670,8 +679,8 @@ and stored by Docker, it is not possible for GitLab to parse this data and meet ## Limitations - Moving or renaming existing Container Registry repositories is not supported -once you have pushed images, because the images are signed, and the -signature includes the repository name. To move or rename a repository with a +once you have pushed images, because the images are stored in a path that matches +the repository path. To move or rename a repository with a Container Registry, you must delete all existing images. - Prior to GitLab 12.10, any tags that use the same image ID as the `latest` tag are not deleted by the cleanup policy. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index ad2d2ac2a8e..3dd900d2cbe 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -68,6 +68,11 @@ The requirement to authenticate is a breaking change added in 13.7. An [administ disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication) if it has disrupted your existing Dependency Proxy usage. +WARNING: +If [SSO enforcement](../../group/saml_sso/index.md#sso-enforcement) +is enabled for your Group, requests to the dependency proxy will fail. This bug is being tracked in +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/294018). + Because the Dependency Proxy is storing Docker images in a space associated with your group, you must authenticate against the Dependency Proxy. diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index b9186e99357..57d6245dd96 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -16,18 +16,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature might not be available to you. Check the **version history** note above for details. -Publish generic files, like release binaries, in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. +Publish generic files, like release binaries, in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. ## Authenticate to the Package Registry To authenticate to the Package Registry, you need either a [personal access token](../../../api/README.md#personalproject-access-tokens), -[CI job token](../../../api/README.md#gitlab-ci-job-token), or [deploy token](../../project/deploy_tokens/index.md). +[CI/CD job token](../../../api/README.md#gitlab-cicd-job-token), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package API allows authentication with HTTP Basic authentication for use with tools that do not support the other available mechanisms. The `user-id` is not checked and may be any value, and the `password` must be either a [personal access token](../../../api/README.md#personalproject-access-tokens), -a [CI job token](../../../api/README.md#gitlab-ci-job-token), or a [deploy token](../../project/deploy_tokens/index.md). +a [CI/CD job token](../../../api/README.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file @@ -47,7 +47,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?sta | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). -| `package_version` | string | yes | The package version. It can contain only numbers (`0-9`), and dots (`.`). Must be in the format of `X.Y.Z`, i.e. should match `/\A\d+\.\d+\.\d+\z/` regular expression. +| `package_version` | string | yes | The package version. The following regex validates this: `\A(\.?[\w\+-]+\.?)+\z`. You can test your version strings on [Rubular](https://rubular.com/r/aNCV0wG5K14uq8). | `file_name` | string | yes | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). | `status` | string | no | The package status. It can be `default` (default) or `hidden`. Hidden packages do not appear in the UI or [package API list endpoints](../../../api/packages.md). diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 1fdc34e820e..36348fcde18 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -16,6 +16,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). +For documentation of the specific API endpoints that the Go Proxy uses, see the +[Go Proxy API documentation](../../../api/packages/go_proxy.md). + ## Enable the Go proxy The Go proxy for GitLab is under development, and isn't ready for production use diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index b35015d0b67..74072aa95e1 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Packages & Registries +# Packages and Registries **(FREE)** The GitLab [Package Registry](package_registry/index.md) acts as a private or public registry for a variety of common package managers. You can publish and share @@ -24,6 +24,7 @@ The Package Registry supports the following formats: <tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/rubygems_registry/index.html">RubyGems</a></td><td>13.10+</td></tr> </table> </div> </div> @@ -49,7 +50,6 @@ guides you through the process. | P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | | Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | | RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | -| RubyGems | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | | SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | | Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 828eec812fa..d4dc9f0ae78 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -9,9 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab Premium 11.3. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish [Maven](https://maven.apache.org) artifacts in your project’s Package Registry. +Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. +For documentation of the specific API endpoints that the Maven package manager +client uses, see the [Maven API documentation](../../../api/packages/maven.md). + ## Build a Maven package This section explains how to install Maven and build a package. @@ -868,3 +871,11 @@ package: - 'mvn help:system' - 'mvn package' ``` + +## Supported CLI commands + +The GitLab Maven repository supports the following Maven CLI commands: + +- `mvn deploy`: Publish your package to the Package Registry. +- `mvn install`: Install packages specified in your Maven project. +- `mvn dependency:get`: Install a specific package. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index f048440e383..b6312002184 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -124,7 +124,7 @@ npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_pr # Add the token for the scoped packages URL. Replace <your_project_id> # with the project where your package is located. -npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +npm config set -- '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" ``` - `<your_project_id>` is your project ID, found on the project's home page. @@ -147,7 +147,7 @@ npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ # Add the token for the scoped packages URL. This will allow you to download # `@foo/` packages from private projects. -npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" +npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` - `<your_token>` is your personal access token or deploy token. @@ -189,8 +189,8 @@ To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpo To avoid hard-coding the `authToken` value, you may use a variable in its place: ```shell -npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" -npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set -- '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" ``` Then, you can run `npm publish` either locally or by using GitLab CI/CD. @@ -251,9 +251,6 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level npm endpoint](#use-the-gitlab-endpoint-for-npm-packages). -- Your npm package name must be in the format of [@scope/package-name](#package-naming-convention). - It must match exactly, including the case. This is different than the - npm naming convention, but it is required to work with the GitLab Package Registry. To upload an npm package to your project, run this command: @@ -263,6 +260,16 @@ npm publish To view the package, go to your project's **Packages & Registries**. +You can also define `"publishConfig"` for your project in `package.json`. For example: + +```json +{ +"publishConfig": { "@foo:registry":" https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/" } +} +``` + +This forces the package to publish only to the specified registry. + If you try to publish a package [with a name that already exists](#publishing-packages-with-the-same-name-or-version) within a given scope, you get a `403 Forbidden!` error. @@ -402,6 +409,9 @@ Due to a bug in npm 6.9.0, deleting distribution tags fails. Make sure your npm ## Troubleshooting +When troubleshooting npm issues, first run the same command with the `--verbose` flag to confirm +what registry you are hitting. + ### Error running Yarn with the Package Registry for npm registry If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get @@ -469,8 +479,9 @@ NPM_TOKEN=<your_token> npm install If you get this error, ensure that: - Your token is not expired and has appropriate permissions. -- [Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). - A package with the same name or version doesn't already exist within the given scope. +- Your NPM package name does not contain a dot `.`. This is a [known issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/10248) + in GitLab 11.9 and earlier. - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` @@ -504,4 +515,19 @@ This is usually a permissions issue with either: - The remote bucket if [object storage](../../../administration/packages/#using-object-storage) is used. -In the latter case, ensure the bucket exists and the GitLab has write access to it. +In the latter case, ensure the bucket exists and GitLab has write access to it. + +## Supported CLI commands + +The GitLab npm repository supports the following commands for the npm CLI (`npm`) and yarn CLI +(`yarn`): + +- `npm install`: Install npm packages. +- `npm publish`: Publish an npm package to the registry. +- `npm dist-tag add`: Add a dist-tag to an npm package. +- `npm dist-tag ls`: List dist-tags for a package. +- `npm dist-tag rm`: Delete a dist-tag. +- `npm ci`: Install npm packages directly from your `package-lock.json` file. +- `npm view`: Show package metadata. +- `yarn add`: Install an npm package. +- `yarn update`: Update your dependencies. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index e1b61f28818..7e59b19076a 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab Premium 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish NuGet packages in your project’s Package Registry. Then, install the +Publish NuGet packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. The Package Registry works with: @@ -18,6 +18,9 @@ The Package Registry works with: - [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/) - [Visual Studio](https://visualstudio.microsoft.com/vs/) +For documentation of the specific API endpoints that these +clients use, see the [NuGet API documentation](../../../api/packages/nuget.md). + ## Install NuGet The required minimum versions are: @@ -314,7 +317,7 @@ dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. -If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a +If you're using NuGet with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. @@ -390,3 +393,13 @@ dotnet add package <package_id> \ - `<package_id>` is the package ID. - `<package_version>` is the package version. Optional. + +## Supported CLI commands + +The GitLab NuGet repository supports the following commands for the NuGet CLI (`nuget`) and the .NET +CLI (`dotnet`): + +- `nuget push`: Upload a package to the registry. +- `dotnet nuget push`: Upload a package to the registry. +- `nuget install`: Install a package from the registry. +- `dotnet add`: Install a package from the registry. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 0e83843f3e8..f04f6f1316e 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -19,7 +19,8 @@ You can view packages for your project or group. 1. Go to the project or group. 1. Go to **Packages & Registries > Package Registry**. -You can search, sort, and filter packages on this page. +You can search, sort, and filter packages on this page. You can share your search results by copying +and pasting the URL from your browser. You can also find helpful code snippets for configuring your package manager or installing a given package. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index a6cc5cf1f07..17b51e313fa 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab Premium 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish PyPI packages in your project’s Package Registry. Then install the +Publish PyPI packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. The Package Registry works with: @@ -17,6 +17,9 @@ The Package Registry works with: - [pip](https://pypi.org/project/pip/) - [twine](https://pypi.org/project/twine/) +For documentation of the specific API endpoints that the `pip` and `twine` +clients use, see the [PyPI API documentation](../../../api/packages/pypi.md). + ## Build a PyPI package This section explains how to create a PyPI package. @@ -356,3 +359,10 @@ characters are removed. A `pip install` request for `my.package` looks for packages that match any of the three characters, such as `my-package`, `my_package`, and `my....package`. + +## Supported CLI commands + +The GitLab PyPI repository supports the following CLI commands: + +- `twine upload`: Upload a package to the registry. +- `pip install`: Install a PyPI package from the registry. diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md new file mode 100644 index 00000000000..aa50bc6c2bc --- /dev/null +++ b/doc/user/packages/rubygems_registry/index.md @@ -0,0 +1,137 @@ +--- +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/#assignments +--- + +# Ruby gems in the Package Registry **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in [GitLab Free](https://about.gitlab.com/pricing/) 13.10. + +WARNING: +The Ruby gems registry for GitLab is under development and isn't ready for production use due to +limited functionality. + +You can publish Ruby gems in your project's Package Registry, then install the packages when you +need to use them as a dependency. Although you can push gems to the registry, you cannot install +them from the registry. However, you can download `gem` files directly from the Package Registry's +UI, or by using the [API](../../../api/packages/rubygems.md#download-a-gem-file). + +For documentation of the specific API endpoints that the Ruby gems and Bundler package manager +clients use, see the [Ruby gems API documentation](../../../api/packages/rubygems.md). + +## Enable the Ruby gems registry + +The Ruby gems registry for GitLab is behind a feature flag that is disabled by default. GitLab +administrators with access to the GitLab Rails console can enable this registry for your instance. + +To enable it: + +```ruby +Feature.enable(:rubygem_packages) +``` + +To disable it: + +```ruby +Feature.disable(:rubygem_packages) +``` + +To enable or disable it for specific projects: + +```ruby +Feature.enable(:rubygem_packages, Project.find(1)) +Feature.disable(:rubygem_packages, Project.find(2)) +``` + +## Create a Ruby Gem + +If you need help creating a Ruby gem, see the [RubyGems documentation](https://guides.rubygems.org/make-your-own-gem/). + +## Authenticate to the Package Registry + +Before you can push to the Package Registry, you must authenticate. + +To do this, you can use: + +- A [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to + `read_package_registry`, `write_package_registry`, or both. +- A [CI job token](#authenticate-with-a-ci-job-token). + +### Authenticate with a personal access token or deploy token + +To authenticate with a personal access token, create or edit the `~/.gem/credentials` file and add: + +```ini +--- +https://gitlab.example.com/api/v4/projects/<project_id>/packages/rubygems: '<your token>' +``` + +- `<your token>` must be the token value of either your personal access token or deploy token. +- Your project ID is on your project's home page. + +### Authenticate with a CI job token + +To work with RubyGems commands within [GitLab CI/CD](../../../ci/README.md), +you can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. + +For example: + +```yaml +image: ruby:latest + +run: + script: +``` + +You can also use `CI_JOB_TOKEN` in a `~/.gem/credentials` file that you check in to +GitLab: + +```ini +--- +https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/rubygems: '${env.CI_JOB_TOKEN}' +``` + +## Push a Ruby gem + +Prerequisites: + +- You must [authenticate to the Package Registry](#authenticate-to-the-package-registry). +- The maximum allowed gem size is 3 GB. + +To push your gem, run a command like this one: + +```shell +gem push my_gem-0.0.1.gem --host <host> +``` + +Note that `<host>` is the URL you used when setting up authentication. For example: + +```shell +gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/1/packages/rubygems +``` + +This message indicates that the gem uploaded successfully: + +```plaintext +Pushing gem to https://gitlab.example.com/api/v4/projects/1/packages/rubygems... +{"message":"201 Created"} +``` + +To view the published gem, go to your project's **Packages & Registries** page. Gems pushed to +GitLab aren't displayed in your project's Packages UI immediately. It can take up to 10 minutes to +process a gem. + +### Pushing gems with the same name or version + +You can push a gem if a package of the same name and version already exists. +Both are visible and accessible in the UI. However, only the most recently +pushed gem is used for installs. + +## Install a Ruby gem + +The Ruby gems registry for GitLab is under development, and isn't ready for production use. You +cannot install Gems from the registry. However, you can download `.gem` files directly from the UI +or by using the [API](../../../api/packages/rubygems.md#download-a-gem-file). diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index c63c2cc9989..3e1c1e7f2ad 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Store all of your packages in one GitLab project +# Store all of your packages in one GitLab project **(FREE)** You can store all of your packages in one project's Package Registry. Rather than using a GitLab repository to store code, you can use the repository to store all your packages. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index bde589661f9..7405c3aade8 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -39,12 +39,13 @@ usernames. A GitLab administrator can configure the GitLab instance to NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. -While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, -or an instance administrator, who receives all permissions. For more information, see [projects members documentation](project/members/index.md). +The Owner permission is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. +While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, or an instance administrator, who receives all permissions. +For more information, see [projects members documentation](project/members/index.md). The following table depicts the various user permission levels in a project. -| Action | Guest | Reporter | Developer |Maintainer| Owner (*10*) | +| Action | Guest | Reporter | Developer |Maintainer| Owner | |---------------------------------------------------|---------|------------|-------------|----------|--------| | Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -65,7 +66,7 @@ The following table depicts the various user permission levels in a project. | Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | | Create new issue | ✓ | ✓ | ✓ | ✓ | ✓ | -| See related issues | ✓ | ✓ | ✓ | ✓ | ✓ | +| See linked issues | ✓ | ✓ | ✓ | ✓ | ✓ | | View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | | View requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -81,18 +82,18 @@ The following table depicts the various user permission levels in a project. | [Set issue estimate and record time spent](project/time_tracking.md) | | ✓ | ✓ | ✓ | ✓ | | Lock issue threads | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | -| Manage related issues | | ✓ | ✓ | ✓ | ✓ | +| Manage linked issues | | ✓ | ✓ | ✓ | ✓ | | Manage labels | | ✓ | ✓ | ✓ | ✓ | | Create code snippets | | ✓ | ✓ | ✓ | ✓ | | See a commit status | | ✓ | ✓ | ✓ | ✓ | | See a container registry | | ✓ | ✓ | ✓ | ✓ | | See environments | | ✓ | ✓ | ✓ | ✓ | +| See [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | View CI/CD analytics | | ✓ | ✓ | ✓ | ✓ | | View Code Review analytics **(STARTER)** | | ✓ | ✓ | ✓ | ✓ | | View Repository analytics | | ✓ | ✓ | ✓ | ✓ | | View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | -| Create new merge request | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | Archive/reopen requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | @@ -107,6 +108,8 @@ The following table depicts the various user permission levels in a project. | Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | Create/edit [releases](project/releases/index.md)| | | ✓ | ✓ | ✓ | | Delete [releases](project/releases/index.md)| | | | ✓ | ✓ | +| Manage merge approval rules (project settings) | | | | ✓ | ✓ | +| Create new merge request | | | ✓ | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | | Push to non-protected branches | | | ✓ | ✓ | ✓ | | Force push to non-protected branches | | | ✓ | ✓ | ✓ | @@ -169,12 +172,12 @@ The following table depicts the various user permission levels in a project. | Manage Terraform state | | | | ✓ | ✓ | | Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | -| Reposition comments on images (posted by any user)|✓ (*11*) | ✓ (*11*) | ✓ (*11*) | ✓ | ✓ | +| Reposition comments on images (posted by any user)|✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | | Manage Error Tracking | | | | ✓ | ✓ | | Delete wiki pages | | | | ✓ | ✓ | -| View project Audit Events | | | ✓ (*12*) | ✓ | ✓ | +| View project Audit Events | | | ✓ (*11*) | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** | | | | ✓ | ✓ | +| Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*12*) | | | | ✓ | ✓ | | View 2FA status of members | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | @@ -200,15 +203,16 @@ The following table depicts the various user permission levels in a project. 1. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) is enabled the project can't be shared with other groups. It does not affect group with group sharing. 1. For information on eligible approvers for merge requests, see [Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). -1. Owner permission is only available at the group or personal namespace level (and for instance admins) and is inherited by its projects. 1. Applies only to comments on [Design Management](project/issues/design_management.md) designs. 1. Users can only view events based on their individual actions. +1. Project access tokens are supported for self-managed instances on Free and above. They are also + supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial)). ## Project features permissions ### Wiki and issues -Project features like wiki and issues can be hidden from users depending on +Project features like [wikis](project/wiki/index.md) and issues can be hidden from users depending on which visibility level you select on project settings. - Disabled: disabled for everyone @@ -290,12 +294,14 @@ group. | View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Group DevOps Adoption **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Billing **(FREE SAAS)** | | | | | ✓ (4) | | View Usage Quotas **(FREE SAAS)** | | | | | ✓ (4) | +| Manage [group push rules](group/index.md#group-push-rules) **(PREMIUM)** | | | | ✓ | ✓ | | View 2FA status of members | | | | | ✓ | | Filter members by 2FA status | | | | | ✓ | | Administer project compliance frameworks | | | | | ✓ | @@ -329,7 +335,7 @@ project and should only have access to that project. External users: -- Cannot create projects (including forks), groups, or personal snippets. +- Can only create projects (including forks), subgroups, and snippets within the top-level group to which they belong. - 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). @@ -482,10 +488,6 @@ instance and project. In addition, all admins can use the admin interface under NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. -NOTE: -GitLab 8.12 has a completely redesigned job permissions system. -Read all about the [new model and its implications](project/new_ci_build_permissions_model.md). - This table shows granted privileges for jobs triggered by specific types of users: @@ -507,11 +509,6 @@ users: 1. Only if the user is not an external one 1. Only if the user is a member of the project -### New CI job permissions model - -GitLab 8.12 has a completely redesigned job permissions system. To learn more, -read through the documentation on the [new CI/CD permissions model](project/new_ci_build_permissions_model.md#new-ci-job-permissions-model). - ## Running pipelines on protected branches The permission to merge or push to protected branches is used to define if a user can diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index d26acd50189..23e5bf2d143 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -5,7 +5,7 @@ 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/#assignments --- -# Two-factor authentication +# Two-factor authentication **(FREE)** Two-factor authentication (2FA) provides an additional level of security to your GitLab account. After being enabled, in addition to supplying your username and diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 5bcfafa7196..4e4cdf5dc36 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -76,6 +76,9 @@ The following is hidden from your user profile page (`https://gitlab.example.com - Date when account was created - Tabs for activity, groups, contributed projects, personal projects, starred projects, snippets +NOTE: +Making your user profile page private does not hide your public resources from the REST or GraphQL APIs. + ## Add external accounts to your user profile page You can add links to certain other external accounts you might have, like Skype and Twitter. @@ -106,7 +109,8 @@ To show private contributions: ## Set your current status -> Introduced in GitLab 11.2. +> - Introduced in GitLab 11.2. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56649) in GitLab 13.10. You can provide a custom status message for your user profile along with an emoji that describes it. This may be helpful when you are out of office or otherwise not available. @@ -119,6 +123,7 @@ To set your current status: 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Set the desired emoji and status message. Status messages must be plain text and 100 characters or less. They can also contain emoji codes like, `I'm on vacation :palm_tree:`. +1. Select a value from the **Clear status after** dropdown. 1. Select **Set status**. Alternatively, you can select **Remove status** to remove your user status entirely. You can also set your current status by [using the API](../../api/users.md#user-status). diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 4f28558cca6..4d890e249e7 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -5,12 +5,15 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Notification Emails +# GitLab Notification Emails **(FREE)** GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications enabled, you can receive updates about activity in issues, merge requests, epics, and designs. Notifications are sent via email. +For the tool that enables GitLab administrators to send messages to users, read +[Email from GitLab](../../tools/email.md). + ## Receiving notifications You receive notifications for one of the following reasons: @@ -50,16 +53,16 @@ These notification settings apply only to you. They do not affect the notificati ## Global notification settings -Your **Global notification settings** are the default settings unless you select different values for a project or a group. +Your **Global notification settings** are the default settings unless you select +different values for a project or a group. -- Notification email - - This is the email address your notifications are sent to. -- Global notification level - - This is the default [notification level](#notification-levels) which applies to all your notifications. -- Receive product marketing emails - - Check this checkbox if you want to receive periodic emails related to GitLab features. -- Receive notifications about your own activity. - - Check this checkbox if you want to receive notification about your own activity. Default: Not checked. +- **Notification email**: The email address your notifications are sent to. +- **Global notification level**: The default [notification level](#notification-levels) + which applies to all your notifications. +- **Receive product marketing emails**: Select this check box to receive periodic + emails about GitLab features. +- **Receive notifications about your own activity**: Select this check box to receive + notifications about your own activity. Not selected by default. ### Notification scope @@ -67,16 +70,16 @@ You can tune the scope of your notifications by selecting different notification Notification scope is applied in order of precedence (highest to lowest): -- Project - - For each project, you can select a notification level. Your project setting overrides the group setting. -- Group - - For each group, you can select a notification level. Your group setting overrides your default setting. -- Global (default) - - Your global, or _default_, notification level applies if you have not selected a notification level for the project or group in which the activity occurred. +- **Project**: For each project, you can select a notification level. Your project + setting overrides the group setting. +- **Group**: For each group, you can select a notification level. Your group setting + overrides your default setting. +- **Global (default)**: Your global, or _default_, notification level applies if you + have not selected a notification level for the project or group in which the activity occurred. #### Project notifications -You can select a notification level for each project. This can be useful if you need to closely monitor activity in select projects. +You can select a notification level for each project to help you closely monitor activity in select projects.  diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 78900e145b7..540724f9185 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -51,7 +51,7 @@ 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 +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 @@ -124,7 +124,7 @@ You can include the following options for your default dashboard view: ### Group overview content The **Group overview content** dropdown allows you to choose what information is -displayed on a group’s home page. +displayed on a group's home page. You can choose between 2 options: @@ -134,7 +134,7 @@ You can choose between 2 options: ### Project overview content The **Project overview content** setting allows you to choose what content you want to -see on a project’s home page. +see on a project's home page. ### Tab width diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 783232ca7f9..1834bc20aee 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -15,7 +15,7 @@ points to. Examples for badges can be the [pipeline status](../../ci/pipelines/s [test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), or ways to contact the project maintainers. - + ## Project badges diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index d7e8133f9ad..76ae4cf596b 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -33,7 +33,7 @@ When bulk editing issues in a project, you can edit the following attributes: - [Epic](../group/epics/index.md) - [Milestone](milestones/index.md) - [Labels](labels.md) -- [Health status](issues/index.md#health-status) +- [Health status](issues/managing_issues.md#health-status) - Notification subscription - [Iteration](../group/iterations/index.md) diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 718c60ccf0e..1b4b4f38f4b 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -231,7 +231,7 @@ To add a Kubernetes cluster to your project, group, or instance: name: gitlab namespace: kube-system --- - apiVersion: rbac.authorization.k8s.io/v1beta1 + apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: gitlab-admin diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index aabda474043..c2d06e0a22c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -86,7 +86,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific CI/CD variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. +[environment-specific CI/CD variables](../../../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster @@ -189,7 +189,7 @@ your cluster. This can cause deployment jobs to fail. To clear the cache: -1. Navigate to your project’s **Operations > Kubernetes** page, and select your cluster. +1. Navigate to your project's **Operations > Kubernetes** page, and select your cluster. 1. Expand the **Advanced settings** section. 1. Click **Clear cluster cache**. diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 349040e0bf6..bafb7d472c6 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 7f344349984..e0b8c074fcf 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -26,7 +26,7 @@ pre-written code blocks or database queries against a given environment. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45912) in GitLab 11.4. The JupyterHub app offered via the GitLab Kubernetes integration now ships -with Nurtch’s Rubix library, providing a simple way to create DevOps +with Nurtch's Rubix library, providing a simple way to create DevOps runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it simple to create common Kubernetes and AWS workflows, you can also create them manually without Rubix. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index f78fb2ed1ef..f9423c0be2d 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -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 [Create a custom variable in the UI](../../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). +For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#custom-variables-validated-by-gitlab). The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. @@ -403,7 +403,7 @@ production: environment: production ``` -Let’s examine the configuration 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. @@ -432,7 +432,7 @@ deploys your application. If your: To test the application you deployed, please go to the build log and follow the following steps: -1. Click on “Show complete raw” on the upper right-hand corner: +1. Click on "Show complete raw" on the upper right-hand corner:  diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 0f7f5e23e59..e355b562c36 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -562,7 +562,7 @@ over `https`, you must manually obtain and install TLS certificates. The simplest way to accomplish this is to use Certbot to [manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). -Certbot is a free, open source software tool for automatically using Let’s Encrypt +Certbot is a free, open source software tool for automatically using Let's Encrypt certificates on manually-administered websites to enable HTTPS. The following instructions relate to installing and running Certbot on a Linux diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 8606ce36a82..842f167f6ec 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Deploy Tokens +# 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. @@ -23,15 +23,15 @@ Deploy tokens cannot be used with the GitLab API. If you have a key pair, you might want to use [deploy keys](../../project/deploy_keys/index.md) instead. -## Creating a Deploy Token +## Creating a Deploy token You can create as many deploy tokens as you need from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). 1. Sign in to your GitLab account. -1. Go to the project (or group) you want to create Deploy Tokens for. +1. Go to the project (or group) you want to create deploy tokens for. 1. Go to **Settings > Repository**. -1. Click on "Expand" on **Deploy Tokens** section. +1. Expand the **Deploy tokens** section. 1. Choose a name, expiry date (optional), and username (optional) for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Select **Create deploy token**. @@ -46,8 +46,8 @@ Deploy tokens expire at midnight UTC on the date you define. ## Revoking a deploy token -At any time, you can revoke any deploy token by just clicking the respective -**Revoke** button under the 'Active deploy tokens' area. +To revoke a deploy token, under the **Active deploy tokens** area, +select the respective **Revoke** button. ## Limiting scopes of a deploy token @@ -75,11 +75,11 @@ username to be used when creating the deploy token. ### Git clone a repository -To download a repository using a Deploy Token, you just need to: +To download a repository using a deploy token: -1. Create a Deploy Token with `read_repository` as a scope. +1. Create a deploy token with `read_repository` as a scope. 1. Take note of your `username` and `token`. -1. `git clone` the project using the Deploy Token: +1. `git clone` the project using the deploy token: ```shell git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git @@ -91,7 +91,7 @@ Replace `<username>` and `<deploy_token>` with the proper values. To read the container registry images, you must: -1. Create a Deploy Token with `read_registry` as a scope. +1. Create a deploy token with `read_registry` as a scope. 1. Take note of your `username` and `token`. 1. Sign in to the GitLab Container Registry using the deploy token: @@ -108,7 +108,7 @@ pull images from your Container Registry. To push the container registry images, you must: -1. Create a Deploy Token with `write_registry` as a scope. +1. Create a deploy token with `write_registry` as a scope. 1. Take note of your `username` and `token`. 1. Sign in to the GitLab Container Registry using the deploy token: @@ -125,7 +125,7 @@ push images to your Container Registry. To pull packages in the GitLab package registry, you must: -1. Create a Deploy Token with `read_package_registry` as a scope. +1. Create a deploy token with `read_package_registry` as a scope. 1. Take note of your `username` and `token`. 1. For the [package type of your choice](../../packages/index.md), follow the authentication instructions for deploy tokens. @@ -152,12 +152,12 @@ Example response: To upload packages in the GitLab package registry, you must: -1. Create a Deploy Token with `write_package_registry` as a scope. +1. Create a deploy token with `write_package_registry` as a scope. 1. Take note of your `username` and `token`. 1. For the [package type of your choice](../../packages/index.md), follow the authentication instructions for deploy tokens. -### Group Deploy Token +### Group deploy token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21765) in GitLab 12.9. @@ -167,7 +167,7 @@ belong either to the specific group or to one of its subgroups. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks). -The Group Deploy Tokens UI is now accessible under **Settings > Repository**, +The Group deploy tokens UI is now accessible under **Settings > Repository**, not **Settings > CI/CD** as indicated in the video. To use a group deploy token: @@ -179,12 +179,12 @@ To use a group deploy token: The scopes applied to a group deploy token (such as `read_repository`) apply consistently when cloning the repository of related projects. -### GitLab Deploy Token +### GitLab deploy token > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18414) in GitLab 10.8. -There's a special case when it comes to Deploy Tokens. If a user creates one -named `gitlab-deploy-token`, the username and token of the Deploy Token is +There's a special case when it comes to deploy tokens. If a user creates one +named `gitlab-deploy-token`, the username and token of the deploy token is automatically exposed to the CI/CD jobs as CI/CD variables: `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`, respectively. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 2267cb55f16..3acef242cef 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -51,8 +51,10 @@ directory in your repository. Commit and push to your default branch. To create a Markdown file: -1. Click the `+` button next to `master` and click **New file**. -1. Add the name of your issue template to the **File name** text field next to `master`. +1. In a project, go to **Repository**. +1. Next to the default branch, select the **{plus}** button. +1. Select **New file**. +1. Next to the default branch, in the **File name** field, add the name of your issue template. Make sure that your file has the `.md` extension, for example `feature_request.md` or `Feature Request.md`. 1. Commit and push to your default branch. @@ -61,9 +63,12 @@ If you don't have a `.gitlab/issue_templates` directory in your repository, you To create the `.gitlab/issue_templates` directory: -1. Click the `+` button next to `master` and select **New directory**. +1. In a project, go to **Repository**. +1. Next to the default branch, select the **{plus}** button. +1. Select **New directory**. 1. Name this new directory `.gitlab` and commit to your default branch. -1. Click the `+` button next to `master` again and select **New directory**. +1. Next to the default branch, select the **{plus}** button. +1. Select **New directory**. 1. Name your directory `issue_templates` and commit to your default branch. To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) @@ -89,32 +94,27 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat  -### Set an issue and merge request description template at group level **(PREMIUM)** +You can set description templates at various levels: -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled by default on GitLab.com. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to - [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). - -Templates can be useful because you can create a template once and use it multiple times. -To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): - -1. Go to the group's **Settings > General > Templates**. -1. From the dropdown, select your template project as the template repository at group level. +- The entire [instance](#set-instance-level-description-templates) +- A specific [group or subgroup](#set-group-level-description-templates) +- A specific [project](#set-a-default-template-for-merge-requests-and-issues) - +The templates are inherited. For example, in a project, you can also access templates set for the +instance or the project's parent groups. -### Set an issue and merge request description template at instance level **(PREMIUM ONLY)** +### Set instance-level description templates **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. > - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled by default on GitLab.com. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to - [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. +> - It's enabled by default on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** + +You can set a description template at the **instance level** for issues +and merge requests. +As a result, these templates are available in all projects within the instance. -Similar to group templates, issue and merge request templates can also be set up at the instance level. -This results in those templates being available in all projects within the instance. Only instance administrators can set instance-level templates. To set the instance-level description template repository: @@ -122,15 +122,41 @@ To set the instance-level description template repository: 1. Select the **Admin Area** icon (**{admin}**). 1. Go to **Settings > Templates**. 1. From the dropdown, select your template project as the template repository at instance level. +1. Select **Save changes**. + + Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md). - +### Set group-level description templates **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. +> - It's enabled by default on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** + +With **group-level** description templates, you can store your templates in a single repository and +configure the group file templates setting to point to that repository. +As a result, you can use the same templates in issues and merge requests in all the group's projects. + +To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): + +1. Go to the group's **Settings > General > Templates**. +1. From the dropdown, select your template project as the template repository at group level. +1. Select **Save changes**. + + ### Set a default template for merge requests and issues **(PREMIUM)** +In a project, you can choose a default description template for new issues and merge requests. +As a result, every time a new merge request or issue is created, it's pre-filled with the text you +entered in the template. + The visibility of issues or merge requests should be set to either "Everyone -with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the +with access" or "Only Project Members" in your project's +**Settings / Visibility, project features, permissions** section. Otherwise, the template text areas don't show. This is the default behavior, so in most cases you should be fine. @@ -149,9 +175,6 @@ To set a default description template for issues: Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format headings, lists, and so on. -Now, every time a new merge request or issue is created, it's pre-filled with the text you entered -in the templates. - [GitLab versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/885) provide `issues_template` and `merge_requests_template` attributes in the [Projects API](../../api/projects.md) to help you keep your templates up to date. @@ -211,9 +234,9 @@ it's very hard to read otherwise.) Setting issue and merge request description templates at group and instance levels is under development and not ready for production use. It is deployed behind a -feature flag that is **disabled by default**. +feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can disable it. To enable it: diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 4edb6fbdad9..b51a1b79a13 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -117,7 +117,7 @@ must **lock the file** before [editing it](#edit-lockable-files). ### Lock files By locking a file, you verify that no one else is editing it, and -prevent anyone else from editing the file until you’re done. On the other +prevent anyone else from editing the file until you're done. On the other hand, when you unlock a file, you communicate that you've finished editing and allow other people to edit it. diff --git a/doc/user/project/img/issue_board_iteration_lists_v13_10.png b/doc/user/project/img/issue_board_iteration_lists_v13_10.png Binary files differnew file mode 100644 index 00000000000..eb3a9524c88 --- /dev/null +++ b/doc/user/project/img/issue_board_iteration_lists_v13_10.png diff --git a/doc/user/project/img/issue_boards_blocked_icon_v13_10.png b/doc/user/project/img/issue_boards_blocked_icon_v13_10.png Binary files differnew file mode 100644 index 00000000000..466b647253d --- /dev/null +++ b/doc/user/project/img/issue_boards_blocked_icon_v13_10.png diff --git a/doc/user/project/img/issue_boards_blocked_icon_v13_6.png b/doc/user/project/img/issue_boards_blocked_icon_v13_6.png Binary files differdeleted file mode 100644 index 2dac6bb2ee3..00000000000 --- a/doc/user/project/img/issue_boards_blocked_icon_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/project_overview_badges.png b/doc/user/project/img/project_overview_badges.png Binary files differdeleted file mode 100644 index 83b9766828a..00000000000 --- a/doc/user/project/img/project_overview_badges.png +++ /dev/null diff --git a/doc/user/project/img/project_overview_badges_v13_10.png b/doc/user/project/img/project_overview_badges_v13_10.png Binary files differnew file mode 100644 index 00000000000..b5510566b1b --- /dev/null +++ b/doc/user/project/img/project_overview_badges_v13_10.png diff --git a/doc/user/project/img/project_repository_settings.png b/doc/user/project/img/project_repository_settings.png Binary files differdeleted file mode 100644 index 69d36753a58..00000000000 --- a/doc/user/project/img/project_repository_settings.png +++ /dev/null diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 85c8a3020b9..8040eb07c93 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -15,33 +15,33 @@ include a centralized, proprietary version control system similar to Git. The following list illustrates the main differences between Perforce Helix and Git: -1. In general the biggest difference is that Perforce branching is heavyweight - compared to Git's lightweight branching. When you create a branch in Perforce, - it creates an integration record in their proprietary database for every file - in the branch, regardless how many were actually changed. Whereas Git was - implemented with a different architecture so that a single SHA acts as a pointer - to the state of the whole repository after the changes, making it very easy to branch. - This is what made feature branching workflows so easy to adopt with Git. -1. Also, context switching between branches is much easier in Git. If your manager - said 'You need to stop work on that new feature and fix this security - vulnerability' you can do so very easily in Git. -1. Having a complete copy of the project and its history on your local machine - means every transaction is very fast and Git provides that. You can branch/merge - and experiment in isolation, then clean up your mess before sharing your new - cool stuff with everyone. -1. Git also made code review simple because you could share your changes without - merging them to master, whereas Perforce had to implement a Shelving feature on - the server so others could review changes before merging. +- In general, the biggest difference is that Perforce branching is heavyweight + compared to Git's lightweight branching. When you create a branch in Perforce, + it creates an integration record in their proprietary database for every file + in the branch, regardless how many were actually changed. With Git, however, + a single SHA acts as a pointer to the state of the whole repository after the + changes, which can be helpful when adopting feature branching workflows. +- Context switching between branches is less complex in Git. If your manager + says, 'You need to stop work on that new feature and fix this security + vulnerability,' Git can help you do this. +- Having a complete copy of the project and its history on your local computer + means every transaction is very fast, and Git provides that. You can branch + or merge, and experiment in isolation, and then clean up before sharing your + changes with others. +- Git makes code review less complex, because you can share your changes without + merging them to the default branch. This is compared to Perforce, which had to + implement a Shelving feature on the server so others could review changes + before merging. ## Why migrate Perforce Helix can be difficult to manage both from a user and an administrator perspective. Migrating to Git/GitLab there is: -- **No licensing costs**, Git is GPL while Perforce Helix is proprietary. -- **Shorter learning curve**, Git has a big community and a vast number of +- **No licensing costs**: Git is GPL while Perforce Helix is proprietary. +- **Shorter learning curve**: Git has a big community and a vast number of tutorials to get you started. -- **Integration with modern tools**, migrating to Git and GitLab you can have +- **Integration with modern tools**: By migrating to Git and GitLab, you can have an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 189afac1226..91fd7b8928b 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -36,13 +36,4 @@ of the project being imported into, then the user will be linked. ## Enabling this feature -While this feature is incomplete, a feature flag is required to enable it so that -we can gain early feedback before releasing it for everyone. To enable it: - -1. Run the following command in a Rails console: - - ```ruby - Feature.enable(:phabricator_import) - ``` - -1. Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area. +Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area. diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 1efb3583fbf..72897a1a26e 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -192,7 +192,7 @@ Supported values are: #### `query.issuable_state` -Filter by the state of the queried "issuable". +Filter by the current state of the queried "issuable". By default, the `opened` state filter is applied. @@ -206,10 +206,10 @@ Supported values are: #### `query.filter_labels` -Filter by labels applied to the queried "issuable". +Filter by labels currently applied to the queried "issuable". By default, no labels filter is applied. All the defined labels must be -applied to the "issuable" in order for it to be selected. +currently applied to the "issuable" in order for it to be selected. Example: @@ -262,7 +262,7 @@ Supported values are: #### `query.period_limit` -Define how far "issuables" are queried in the past. +Define how far "issuables" are queried in the past (using the `query.period_field`). The unit is related to the `query.group_by` you defined. For instance if you defined `query.group_by: 'day'` then `query.period_limit: 365` would mean @@ -303,7 +303,7 @@ you may see `created_at` in place of `merged_at`. `created_at` is used instead. You can limit where the "issuables" can be queried from: -- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group are used. +- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects currently under the group are used. - If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used. #### `projects.only` diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md new file mode 100644 index 00000000000..b9552fff110 --- /dev/null +++ b/doc/user/project/integrations/asana.md @@ -0,0 +1,44 @@ +--- +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Asana service **(FREE)** + +This service adds commit messages as comments to Asana tasks. +Once enabled, commit messages are checked for Asana task URLs (for example, +`https://app.asana.com/0/123456/987654`) or task IDs starting with `#` +(for example, `#987654`). Every task ID found gets the commit comment added to it. + +You can also close a task with a message containing: `fix #123456`. +You can use either of these words: + +- `fix` +- `fixed` +- `fixes` +- `fixing` +- `close` +- `closes` +- `closed` +- `closing` + +See also the [Asana service API documentation](../../../api/services.md#asana). + +## Setup + +In Asana, create a Personal Access Token. +[Learn about Personal Access Tokens in Asana](https://developers.asana.com/docs/personal-access-token). + +Complete these steps in GitLab: + +1. Go to the project you want to configure. +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Asana**. +1. Ensure that the **Active** toggle is enabled. +1. Paste the token you generated in Asana. +1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch** + field, separated with commas. +1. Select **Save changes** or optionally select **Test settings**. + +<!-- ## Troubleshooting --> diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 3b012ab4430..1eb8a8c60e0 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,11 +4,11 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Atlassian Bamboo CI Service **(FREE)** +# Atlassian Bamboo Service **(FREE)** GitLab provides integration with Atlassian Bamboo for continuous integration. When configured, pushes to a project trigger a build in Bamboo automatically. -Merge requests also display CI status showing whether the build is pending, +Merge requests also display CI/CD status showing whether the build is pending, failed, or completed successfully. It also provides a link to the Bamboo build page for more information. @@ -20,21 +20,21 @@ need to be configured in a Bamboo build plan before GitLab can integrate. ### Complete these steps in Bamboo -1. Navigate to a Bamboo build plan and choose 'Configure plan' from the 'Actions' +1. Navigate to a Bamboo build plan and choose **Configure plan** from the **Actions** dropdown. -1. Select the 'Triggers' tab. -1. Click 'Add trigger'. -1. Enter a description such as 'GitLab trigger' -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 +1. Select the **Triggers** tab. +1. Click **Add trigger**. +1. Enter a description such as **GitLab trigger**. +1. Choose **Repository triggers the build when changes are committed**. +1. Select the checkbox for one or more repositories. +1. Enter the GitLab IP address in the **Trigger IP addresses** box. This is a 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. -1. Select the 'Miscellaneous' tab. -1. Under 'Pattern Match Labeling' put `${bamboo.repository.revision.number}` - in the 'Labels' box. +1. Select the **Miscellaneous** tab. +1. Under **Pattern Match Labeling** put `${bamboo.repository.revision.number}` + in the **Labels** box. 1. Save Bamboo is now ready to accept triggers from GitLab. Next, set up the Bamboo @@ -44,18 +44,18 @@ service in GitLab. 1. Navigate to the project you want to configure to trigger builds. 1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click 'Atlassian Bamboo CI' +1. Click **Atlassian Bamboo**. 1. Ensure that the **Active** toggle is enabled. 1. Enter the base URL of your Bamboo server. `https://bamboo.example.com` 1. Enter the build key from your Bamboo build plan. Build keys are typically made up from the Project Key and Plan Key that are set on project/plan creation and - separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all + separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all uppercase identifier that is unique. When viewing a plan in Bamboo, the build key is also shown in the browser URL, for example `https://bamboo.example.com/browse/PROJ-PLAN`. 1. If necessary, enter username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require authentication. -1. Save or optionally click 'Test Settings'. Please note that 'Test Settings' +1. Save or optionally click **Test Settings**. Please note that **Test Settings** actually triggers a build in Bamboo. ## Troubleshooting @@ -63,7 +63,7 @@ service in GitLab. ### Builds not triggered If builds are not triggered, ensure you entered the right GitLab IP address in -Bamboo under 'Trigger IP addresses'. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. +Bamboo under **Trigger IP addresses**. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. ### Advanced Atlassian Bamboo features not available in GitLab UI diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 624c0252f23..2ec657eec22 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -10,7 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. -To send GitLab event notifications to a Discord channel, create a webhook in Discord and configure it in GitLab. +To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) +and configure it in GitLab. ## Create webhook diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 4970e20974b..3ef4a4e5004 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -18,9 +18,9 @@ The following options are available: - **Push events** - Email is triggered when a push event is received. - **Tag push events** - Email is triggered when a tag is created and pushed. -- **Send from committer** - Send notifications from the committer's email address if the domain is part of the domain GitLab is running on (e.g. `user@gitlab.com`). +- **Send from committer** - Send notifications from the committer's email address if the domain matches the domain used by your GitLab instance (such as `user@gitlab.com`). - **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. | Settings | Notification | | --- | --- | -|  |  | +|  |  | diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 1c0309cab87..4f5640d9fff 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -18,38 +18,39 @@ and is automatically configured on [GitHub import](../../../integration/github.m ## Configuration -### Complete these steps on GitHub - This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) -with `repo:status` access granted: +with `repo:status` access granted. + +Complete these steps on GitHub: -1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> -1. Click "Generate New Token" -1. Ensure that `repo:status` is checked and click "Generate token" -1. Copy the generated token to use on GitLab +1. Go to your **Personal access tokens** page at <https://github.com/settings/tokens>. +1. Select **Generate new token**. +1. Under **Note**, enter a name for the new token. +1. Ensure that `repo:status` is checked and select **Generate token**. +1. Copy the generated token to use in GitLab. -### Complete these steps on GitLab +Complete these steps in GitLab: -1. Navigate to the project you want to configure. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click "GitHub". +1. Go to the project you want to configure. +1. Go to the [Integrations page](overview.md#accessing-integrations) +1. Select **GitHub**. 1. Ensure that the **Active** toggle is enabled. -1. Paste the token you've generated on GitHub -1. Enter the path to your project on GitHub, such as `https://github.com/username/repository` -1. Optionally uncheck **Static status check names** checkbox to disable static status check names. -1. Save or optionally click "Test Settings". +1. Paste the token you generated on GitHub. +1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`. +1. (Optional) To disable static status check names, clear the **Static status check names** checkbox. +1. Select **Save changes** or optionally select **Test settings**. -Once the integration is configured, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) +After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. -#### Static / dynamic status check names +### Static / dynamic status check names > - Introduced in GitLab 11.5: using static status check names as opt-in option. > - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. -This makes it possible to mark these status checks as _Required_ on GitHub. -With **Static status check names** enabled on the integration page, your -GitLab instance host name is appended to a status check name, -whereas in case of dynamic status check names, a branch name is appended. +This makes it possible to mark these status checks as **Required** on GitHub. + +When **Static status check names** is enabled on the integration page, your +GitLab instance host name is appended to a status check name. - +When disabled, it uses dynamic status check names and appends the branch name. diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 9c0eb571f66..63772936fd4 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -1,64 +1,7 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'index.md' --- -# Atlassian HipChat (Deprecated) **(FREE)** - -As of [GitLab -13.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57434), the -HipChat integration will not send any notifications to HipChat. This -integration is also deprecated. - -GitLab provides a way to send HipChat notifications upon a number of events, -such as when a user pushes code, creates a branch or tag, adds a comment, and -creates a merge request. - -## Setup - -GitLab requires the use of a HipChat v2 API token to work. v1 tokens are -not supported at this time. Note the differences between v1 and v2 tokens: - -HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 -token is allowed to send messages to *any* room. - -HipChat v2 API has tokens that are can be created using the Integrations tab -in the Group or Room administration page. By design, these are lightweight tokens that -allow GitLab to send messages only to *one* room. - -### Complete these steps in HipChat - -1. Go to: `https://admin.hipchat.com/admin` -1. Click on "Group Admin" -> "Integrations". -1. Find "Build Your Own!" and click "Create". -1. Select the desired room, name the integration "GitLab", and click "Create". -1. In the "Send messages to this room by posting this URL" column, you should - see a URL in the format: - -```plaintext -https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token> -``` - -HipChat is now ready to accept messages from GitLab. Next, set up the HipChat -service in GitLab. - -### Complete these steps in GitLab - -1. Navigate to the project you want to configure for notifications. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click "HipChat". -1. Ensure that the **Active** toggle is enabled. -1. Insert the `token` field from the URL into the `Token` field on the Web page. -1. Insert the `room` field from the URL into the `Room` field on the Web page. -1. Save or optionally click "Test Settings". - -## Troubleshooting - -If you do not see notifications, make sure you are using a HipChat v2 API -token, not a v1 token. - -Note that the v2 token is tied to a specific room. If you want to be able to -specify arbitrary rooms, you can create an API token for a specific user in -HipChat under "Account settings" and "API access". Use the `XXX` value under -`auth_token=XXX`. +This document was moved to [another location](index.md). +<!-- This redirect file can be deleted after 2021-06-30. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/img/emails_on_push_service_v13_11.png b/doc/user/project/integrations/img/emails_on_push_service_v13_11.png Binary files differnew file mode 100644 index 00000000000..e895b4b771f --- /dev/null +++ b/doc/user/project/integrations/img/emails_on_push_service_v13_11.png diff --git a/doc/user/project/integrations/img/github_configuration.png b/doc/user/project/integrations/img/github_configuration.png Binary files differdeleted file mode 100644 index 5798b826681..00000000000 --- a/doc/user/project/integrations/img/github_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png b/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png Binary files differdeleted file mode 100644 index 0cf58433b25..00000000000 --- a/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_add_user_to_group.png b/doc/user/project/integrations/img/jira_add_user_to_group.png Binary files differdeleted file mode 100644 index b63a851a987..00000000000 --- a/doc/user/project/integrations/img/jira_add_user_to_group.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_added_user_to_group.png b/doc/user/project/integrations/img/jira_added_user_to_group.png Binary files differdeleted file mode 100644 index f5120a8d42e..00000000000 --- a/doc/user/project/integrations/img/jira_added_user_to_group.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png Binary files differdeleted file mode 100644 index d9d37713a4d..00000000000 --- a/doc/user/project/integrations/img/jira_api_token.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png Binary files differdeleted file mode 100644 index a10a59a243d..00000000000 --- a/doc/user/project/integrations/img/jira_api_token_menu.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_create_new_group.png b/doc/user/project/integrations/img/jira_create_new_group.png Binary files differdeleted file mode 100644 index 4ab7a5eae4e..00000000000 --- a/doc/user/project/integrations/img/jira_create_new_group.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_create_new_user.png b/doc/user/project/integrations/img/jira_create_new_user.png Binary files differdeleted file mode 100644 index c74933298e3..00000000000 --- a/doc/user/project/integrations/img/jira_create_new_user.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_group_access.png b/doc/user/project/integrations/img/jira_group_access.png Binary files differdeleted file mode 100644 index e33f2eed242..00000000000 --- a/doc/user/project/integrations/img/jira_group_access.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_issue_reference.png b/doc/user/project/integrations/img/jira_issue_reference.png Binary files differdeleted file mode 100644 index db8bc4f0bb9..00000000000 --- a/doc/user/project/integrations/img/jira_issue_reference.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_merge_request_close.png b/doc/user/project/integrations/img/jira_merge_request_close.png Binary files differdeleted file mode 100644 index 9a176daf5f4..00000000000 --- a/doc/user/project/integrations/img/jira_merge_request_close.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_project_settings.png b/doc/user/project/integrations/img/jira_project_settings.png Binary files differdeleted file mode 100644 index d96002b7db8..00000000000 --- a/doc/user/project/integrations/img/jira_project_settings.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_service_close_issue.png b/doc/user/project/integrations/img/jira_service_close_issue.png Binary files differdeleted file mode 100644 index 73d6498192c..00000000000 --- a/doc/user/project/integrations/img/jira_service_close_issue.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_user_management_link.png b/doc/user/project/integrations/img/jira_user_management_link.png Binary files differdeleted file mode 100644 index caecd1d71fc..00000000000 --- a/doc/user/project/integrations/img/jira_user_management_link.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_configuration_v2.png b/doc/user/project/integrations/img/mattermost_configuration_v2.png Binary files differdeleted file mode 100644 index 0470869c4f7..00000000000 --- a/doc/user/project/integrations/img/mattermost_configuration_v2.png +++ /dev/null diff --git a/doc/user/project/integrations/img/microsoft_teams_configuration.png b/doc/user/project/integrations/img/microsoft_teams_configuration.png Binary files differdeleted file mode 100644 index 22ad28e3f73..00000000000 --- a/doc/user/project/integrations/img/microsoft_teams_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/redmine_configuration.png b/doc/user/project/integrations/img/redmine_configuration.png Binary files differdeleted file mode 100644 index eb392b848b5..00000000000 --- a/doc/user/project/integrations/img/redmine_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 5628a9bc5e5..c7772ac2238 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -12,11 +12,14 @@ You can find the available integrations under your project's ## Integrations -Integrations allow you to integrate GitLab with other applications. -They are a bit like plugins in that they allow a lot of freedom in -adding functionality to GitLab. - -Learn more [about integrations](overview.md). +Like plugins, integrations allow you to integrate GitLab with other applications, adding additional features. +For more information, read the +[overview of integrations](overview.md) or learn how to manage your integrations: + +- *For GitLab 13.3 and later,* read [Project integration management](../../admin_area/settings/project_integration_management.md). +- *For GitLab 13.2 and earlier,* read [Service Templates](services_templates.md), + which are deprecated and [scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) + in GitLab 14.0. ## Project webhooks diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index e75561b3ddb..295300fb55d 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -23,7 +23,7 @@ git clone https://gitlab.com/esr/irker.git Once you have downloaded the code, you can run the Python script named `irkerd`. This script is the gateway script, it acts both as an IRC client, for sending -messages to an IRC server obviously, and as a TCP server, for receiving messages +messages to an IRC server, and as a TCP server, for receiving messages from the GitLab service. If the Irker server runs on the same machine, you are done. If not, you diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 0878e1c9386..b91a8a1fb3b 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,306 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/index.md' --- -# GitLab Jira integration **(FREE)** +This document was moved to [another location](../../../integration/jira/index.md). -You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the -process of working across these systems more efficient. - -The GitLab Jira integration, available in every GitLab project by default, allows you to connect -to any Jira instance, whether on Atlassian cloud or self-managed. - -You can also install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). -For more information about the differences between the two integrations, see -[Jira integrations](jira_integrations.md). - -After you set up this integration, you can cross-reference activity in the GitLab project with any -of your projects in Jira. This includes the ability to close or transition Jira issues when work is -completed in GitLab and: - -- Mention a Jira issue ID in a commit message or MR (merge request) and: - - GitLab links to the Jira issue. - - The Jira issue adds a comment with details and a link back to the activity in GitLab. -- Mention that a commit or MR resolves or closes a specific Jira issue and when it's merged to the default branch: - - The GitLab MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. -- Run a pipeline on an MR linked to a Jira issue: - - The Jira issue shows the current pipeline status (in the sidebar as "builds"). -- Deploy to an environment from an MR linked to a Jira issue: - - The Jira issue shows the status of the deployment (in the sidebar as "deployments"). -- Create or modify a feature flag that mentions a Jira issue in its description: - - The Jira issue shows the details of the feature-flag (in the sidebar as "feature flags"). -- View a list of Jira issues directly in GitLab. **(PREMIUM)** -- Create a Jira issue from a vulnerability. **(ULTIMATE)** - -Additional features provided by the Jira Development Panel integration include: - -- In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. -- Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. -- Showing pipeline, deployment, and feature flags in Jira issues. - -## Configuration - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). - -Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab -project can interact with _all_ Jira projects in that instance, once configured. For: - -- The [view Jira issues](#view-jira-issues) feature, you must associate a GitLab project with a - specific Jira project. -- Other features, you do not have to explicitly associate a GitLab project with any single Jira - project. - -If you have one Jira instance, you can pre-fill the settings. For more information, see the -documentation for: - -- [Project integration management](../../admin_area/settings/project_integration_management.md). -- [Services Templates](services_templates.md). - -To enable the Jira service in GitLab, you must: - -1. Configure the project in Jira. -1. Enter the correct values in GitLab. - -### Configure Jira - -The process for configuring Jira depends on whether you host Jira on your own server or on -[Atlassian cloud](https://www.atlassian.com/cloud). - -#### Jira Server - -Jira Server supports basic authentication. When connecting, a **username and password** are -required. Connecting to Jira Server via CAS is not possible. For more information, see -[set up a user in Jira Server](jira_server_configuration.md). - -#### Jira on Atlassian cloud - -Jira on Atlassian cloud supports authentication through an API token. When connecting to Jira on -Atlassian cloud, an **email and API token** are required. For more information, see -[set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). - -### Configure GitLab - -> **Notes:** -> -> - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - In order to support Oracle's Access Manager, GitLab sends additional cookies -> to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with -> a value of `fromDialog`. - -To enable the Jira integration in a project: - -1. Go to the project's [Integrations page](overview.md#accessing-integrations) and select the - **Jira** service. - -1. Select **Enable integration**. - -1. Select **Trigger** actions. - This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, - should link the Jira issue back to that source commit/MR and transition the Jira issue, if - indicated. - -1. To include a comment on the Jira issue when the above reference is made in GitLab, select - **Enable comments**. - - 1. Select the **Comment detail**: **Standard** or **All details**. - -1. Enter the further details on the page as described in the following table. - - | Field | Description | - | ----- | ----------- | - | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | - | `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | - | `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | - | `Password/API token` | Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | - | `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | - -1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and - enter a Jira project key. **(PREMIUM)** - - You can only display issues from a single Jira project within a given GitLab project. - - WARNING: - If you enable Jira issues with the setting above, all users that have access to this GitLab project - are able to view all issues from the specified Jira project. - -1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. - - 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. - -1. To verify the Jira connection is working, select **Test settings**. - -1. Select **Save changes**. - -Your GitLab project can now interact with all Jira projects in your instance and the project now -displays a Jira link that opens the Jira project. - -#### Obtaining a transition ID - -In the most recent Jira user interface, you can no longer see transition IDs in the workflow -administration UI. You can get the ID you need in either of the following ways: - -1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` - using an issue that is in the appropriate "open" state -1. By mousing over the link for the transition you want and looking for the - "action" parameter in the URL - -Note that the transition ID may vary between workflows (for example, bug vs. story), -even if the status you are changing to is the same. - -#### Disabling comments on Jira issues - -You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. - -See the [Configure GitLab](#configure-gitlab) section and uncheck the **Enable comments** setting. - -## Jira issues - -By now you should have [configured Jira](#configure-jira) and enabled the -[Jira service in GitLab](#configure-gitlab). If everything is set up correctly -you should be able to reference and close Jira issues by just mentioning their -ID in GitLab commits and merge requests. - -Jira issue IDs must be formatted in uppercase for the integration to work. - -### Reference Jira issues - -When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issues in GitLab automatically adds a comment in Jira issue with the -link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the -format: - -```plaintext -USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: -ENTITY_TITLE -``` - -- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. -- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. -- `PROJECT_NAME` GitLab project name. -- `ENTITY_TITLE` Merge request title or commit message first line. - - - -For example, the following commit references the Jira issue with `PROJECT-1` as its ID: - -```shell -git commit -m "PROJECT-1 Fix spelling and grammar" -``` - -### Close Jira issues - -Jira issues can be closed directly from GitLab by using trigger words in -commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab -adds a comment in the mentioned Jira issue and immediately closes it (provided -the transition ID was set up correctly). - -There are currently three trigger words, and you can use either one to achieve -the same goal: - -- `Resolves PROJECT-1` -- `Closes PROJECT-1` -- `Fixes PROJECT-1` - -where `PROJECT-1` is the ID of the Jira issue. - -Note the following: - -- Only commits and merges into the project's default branch (usually `master`) - close an issue in Jira. You can change your project's default branch under - [project settings](img/jira_project_settings.png). -- The Jira issue is not transitioned if it has a resolution. - -Let's consider the following example: - -1. For the project named `PROJECT` in Jira, we implemented a new feature - and created a merge request in GitLab. -1. This feature was requested in Jira issue `PROJECT-7` and the merge request - in GitLab contains the improvement -1. In the merge request description we use the issue closing trigger - `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue is automatically closed - with a comment and an associated link to the commit that resolved the issue. - -In the following screenshot you can see what the link references to the Jira -issue look like. - - - -Once this merge request is merged, the Jira issue is automatically closed -with a link to the commit that resolved the issue. - - - -### View Jira issues **(PREMIUM)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configure-gitlab) in GitLab by an administrator. - - - -From the **Jira Issues** menu, click **Issues List**. The issue list defaults to sort by **Created date**, with the newest issues listed at the top. You can change this to **Last updated**. - -Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html). - -- The **Open** tab displays all issues with a Jira status in any category other than Done. -- The **Closed** tab displays all issues with a Jira status categorized as Done. -- The **All** tab displays all issues of any status. - -Click an issue title to open its original Jira issue page for full details. - -#### Search and filter the issues list - -To refine the list of issues, use the search bar to search for any text -contained in an issue summary (title) or description. - -You can also filter by labels, status, reporter, and assignee using URL parameters. -Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). - -- To filter issues by `labels`, specify one or more labels as part of the `labels[]` -parameter in the URL. When using multiple labels, only issues that contain all specified -labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` - -- To filter issues by `status`, specify the `status` parameter in the URL. -`/-/integrations/jira/issues?status=In Progress` - -- To filter issues by `reporter`, specify a reporter's Jira display name for the -`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith` - -- To filter issues by `assignee`, specify their Jira display name for the -`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith` - -## Troubleshooting - -If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. - -### GitLab is unable to comment on a Jira issue - -Make sure that the Jira user you set up for the integration has the -correct access permission to post comments on a Jira issue and also to transition -the issue, if you'd like GitLab to also be able to do so. -Jira issue references and update comments do not work if the GitLab issue tracker is disabled. - -### GitLab is unable to close a Jira issue - -Make sure the `Transition ID` you set within the Jira settings matches the one -your project needs to close an issue. - -Make sure that the Jira issue is not already marked as resolved; that is, -the Jira issue resolution field is not set. (It should not be struck through in -Jira lists.) - -### CAPTCHA - -CAPTCHA may be triggered after several consecutive failed login attempts -which may lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you can't use Jira's REST API to -authenticate with the Jira site. You need to log in to your Jira instance -and complete the CAPTCHA. +<!-- This redirect file can be deleted after 2021-07-07. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 8e25af3f884..b3091275835 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,27 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/jira_cloud_configuration.md' --- -# Create an API token in Jira on Atlassian cloud **(FREE)** +This document was moved to [another location](../../../integration/jira/jira_cloud_configuration.md). -For [integrations with Jira](jira.md), an API token is needed when integrating with Jira -on Atlassian cloud. To create an API token: - -1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. - - NOTE: - It is important that the user associated with this email address has *write* access - to projects in Jira. - -1. Click **Create API token**. - -  - -1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configure-gitlab). - -  - -The Jira configuration is complete. You need the newly created token, and the associated email -address, when [configuring GitLab](jira.md#configure-gitlab). +<!-- This redirect file can be deleted after <2021-06-18>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 6b938238320..485b48df01b 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,56 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/index.md' --- -# Jira integrations **(FREE)** +This document was moved to [another location](../../../integration/jira/index.md). -GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira). - -[Issues](../issues/index.md) are a tool for discussing ideas, and planning and tracking work. -However, your organization may already use Jira for these purposes, with extensive, established data -and business processes they rely on. - -Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work -exclusively in GitLab, you can also continue to use Jira by using the GitLab Jira integrations. - -## Integration types - -There are two different Jira integrations that allow different types of cross-referencing between -GitLab activity and Jira issues, with additional features: - -- [Jira integration](jira.md), built in to GitLab. In a given GitLab project, it can be configured - to connect to any Jira instance, either hosted by you or hosted in - [Atlassian cloud](https://www.atlassian.com/cloud). -- [Jira development panel integration](../../../integration/jira_development_panel.md). Connects all - GitLab projects under a specified group or personal namespace. - -Jira development panel integration configuration depends on whether: - -- You're using GitLab.com or a self-managed GitLab instance. -- You're using Jira on [Atlassian cloud](https://www.atlassian.com/cloud) or on your own server. - -| You use Jira on: | For the Jira development panel integration, GitLab.com customers need: | For the Jira development panel integration, GitLab self-managed customers need: | -|:-------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Atlassian cloud | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See a [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/268278) for more information. | -| Your own server | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | - -NOTE: -DVCS means distributed version control system. - -## Feature comparison - -The integration to use depends on the capabilities your require. You can install both at the same -time. - -| Capability | Jira integration | Jira Development Panel integration | -|:----------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| -| Mention of Jira issue ID in GitLab is automatically linked to that issue | Yes | No | -| Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel | -| Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab. | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | -| Mention of Jira issue ID in GitLab branch names is reflected in Jira issue | No | Yes, in the issue’s Development panel | -| Record Jira time tracking information against an issue | No | Yes. Time can be specified via Jira Smart Commits. | -| Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | -| Display a list of Jira issues | Yes **(PREMIUM)** | No | -| Create a Jira issue from a vulnerability or finding **(ULTIMATE)** | Yes | No | +<!-- This redirect file can be deleted after <2021-07-13>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index b1ab2076dc0..191b8f207a1 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,68 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/jira_server_configuration.md' --- -# Create Jira Server username and password **(FREE)** +This document was moved to [another location](../../../integration/jira/jira_server_configuration.md). -For [integrations with Jira](jira.md), you must create a user account in Jira to have access to -all projects that need to integrate with GitLab. - -The Jira user account created for the integration must have write access to -your Jira projects. - -As an example, the following process creates a user named `gitlab` and that's a -member of a new group named `gitlab-developers`: - -1. Sign in to your Jira instance as an administrator, and - then go to the gear icon and select **User Management**. - -  - -1. Create a new user account (for example, `gitlab`) with write access to - projects in Jira. Enter the user account's name and a valid e-mail address, - because Jira sends a verification email to set up the password. - - Jira creates the username by using the email prefix. You can change the - username later, if needed. The GitLab integration doesn't support SSO (such - as SAML). You need to create an HTTP basic authentication password. You can - do this by visiting the user profile, looking up the username, and setting a - password. - -  - -1. From the sidebar, select **Groups**. - -  - -1. In the **Add group** section, enter a **Name** for the group (for example, - `gitlab-developers`), and then select **Add group**. - -1. Add the `gitlab` user to the `gitlab-developers` group by selecting **Edit members**. - The `gitlab-developers` group should be listed in the leftmost box as a - selected group. In the **Add members to selected group(s)** area, enter `gitlab`. - -  - - Select **Add selected users**, and `gitlab` should appear in the **Group member(s)** - area. This membership is saved automatically. - -  - -1. To give the newly-created group 'write' access, you must create a permission - scheme. To do this, in the admin menu, go to the gear icon and select **Issues**. - -1. From the sidebar, select **Permission Schemes**. - -1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a - **Description**, and then select **Add**. - -1. In the permissions scheme list, locate your new permissions scheme, and - select **Permissions**. Next to **Administer Projects**, select **Edit**. In - the **Group** list, select `gitlab-developers`. - -  - -The Jira configuration is complete. Write down the new Jira username and its -password, as you need them when [configuring GitLab](jira.md#configure-gitlab). +<!-- This redirect file can be deleted after <2021-06-18>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 6a93fc0fb06..0a32119d572 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,18 +4,23 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Mattermost Notifications Service **(FREE)** +# Mattermost notifications service **(FREE)** -The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab. +Use the Mattermost notifications service to send notifications for GitLab events +(for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications) +and [GitLab](#configure-gitlab-to-send-notifications-to-mattermost). -You can also use Mattermost slash commands to control GitLab inside Mattermost. This is the separately configured [Mattermost slash commands](mattermost_slash_commands.md). +You can also use [Mattermost slash commands](mattermost_slash_commands.md) to control +GitLab inside Mattermost. -## On Mattermost +## Configure Mattermost to receive GitLab notifications -To enable Mattermost integration you must create an incoming webhook integration: +To use the Mattermost integration you must create an incoming webhook integration +in Mattermost: 1. Sign in to your Mattermost instance. -1. Visit incoming webhooks, that is something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. [Enable incoming webhooks](https://docs.mattermost.com/developer/webhooks-incoming.html#enabling-incoming-webhooks). +1. [Add an incoming webhook](https://docs.mattermost.com/developer/webhooks-incoming.html#creating-integrations-using-incoming-webhooks). 1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it and copy the **Webhook URL** because we need this later for GitLab. @@ -29,36 +34,24 @@ to enable it on: Display name override is not enabled by default, you need to ask your administrator to enable it on that same section. -## On GitLab +## Configure GitLab to send notifications to Mattermost -After you set up Mattermost, it's time to set up GitLab. +After the Mattermost instance has an incoming webhook set up, you can set up GitLab +to send the notifications. Navigate to the [Integrations page](overview.md#accessing-integrations) -and select the **Mattermost notifications** service to configure it. -There, you see a checkbox with the following events that can be triggered: +and select the **Mattermost notifications** service. Select the GitLab events +you want to generate notifications for. -- Push -- Issue -- Confidential issue -- Merge request -- Note -- Confidential note -- Tag push -- Pipeline -- Wiki page -- Deployment +For each event you select, input the Mattermost channel you want to receive the +notification. You do not need to add the hash sign (`#`). -Below each of these event checkboxes, you have an input field to enter -which Mattermost channel you want to send that event message. Enter your preferred channel handle (the hash sign `#` is optional). - -At the end, fill in your Mattermost details: +Then fill in the integration configuration: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | -| **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | -| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | -| **Branches to be notified** | Select which types of branches to send notifications for. | -| **Labels to be notified** | Optional labels that the issue or merge request must have in order to trigger a notification. Leave blank to get all notifications. | - - +| **Webhook** | The incoming webhook URL on Mattermost, similar to: `http://mattermost.example/hooks/5xo…`. | +| **Username** | (Optional) The username to show on messages sent to Mattermost. Fill this in to change the username of the bot. | +| **Notify only broken pipelines** | If you enable the **Pipeline** event and you want to be notified about failed pipelines only. | +| **Branches to be notified** | Select which branches to send notifications for. | +| **Labels to be notified** | (Optional) Labels that the issue or merge request must have to trigger a notification. Leave blank to get notifications for all issues and merge requests. | diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 41e0938fc3b..795ead573f2 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -6,49 +6,55 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Microsoft Teams service **(FREE)** -## On Microsoft Teams +You can integrate Microsoft Teams with GitLab, and display notifications about GitLab projects +in Microsoft Teams. To integrate the services, you must: -To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft -Teams by following the steps below: +1. [Configure Microsoft Teams](#configure-microsoft-teams) to enable a webhook + to listen for changes. +1. [Configure your GitLab project](#configure-your-gitlab-project) to push notifications + to the Microsoft Teams webhook. -1. Search for "incoming webhook" on the search bar in Microsoft Teams and select the - **Incoming Webhook** item. +## Configure Microsoft Teams + +To configure Microsoft Teams to listen for notifications from GitLab: + +1. In Microsoft Teams, search for "incoming webhook" in the search bar, and select the + **Incoming Webhook** item:  -1. Click the **Add to a team** button. +1. Select **Add to a team**. 1. Select the team and channel you want to add the integration to. 1. Add a name for the webhook. The name is displayed next to every message that comes in through the webhook. -1. Copy the webhook URL for the next steps. - -Learn more about -[setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). - -## On GitLab - -After you set up Microsoft Teams, it's time to set up GitLab. - -Navigate to the [Integrations page](overview.md#accessing-integrations) -and select the **Microsoft Teams Notification** service to configure it. -There, you see a checkbox with the following events that can be triggered: - -- Push -- Issue -- Confidential issue -- Merge request -- Note -- Tag push -- Pipeline -- Wiki page - -At the end fill in your Microsoft Teams details: - -| Field | Description | -| ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Microsoft Teams. | -| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | - -After you are all done, click **Save changes** for the changes to take effect. - - +1. Copy the webhook URL, as you need it to configure GitLab. + +## Configure your GitLab project + +After you configure Microsoft Teams to receive notifications, you must configure +GitLab to send the notifications: + +1. Sign in to GitLab as a user with [Administrator](../../permissions.md) and go + to your project's page. +1. Go to **Settings > Integrations** and select **Microsoft Teams Notification**. +1. Select **Active** to enable the integration. +1. Select the check box next to each **Trigger** to enable: + - Push + - Issue + - Confidential issue + - Merge request + - Note + - Confidential note + - Tag push + - Pipeline - If you enable this trigger, you can also select **Notify only broken pipelines** to be notified only about failed pipelines. + - Wiki page +1. In **Webhook**, paste the URL you copied when you + [configured Microsoft Teams](#configure-microsoft-teams). +1. (Optional) If you enabled the pipeline trigger, you can select the + **Notify only broken pipelines** check box to push notifications only when pipelines break. +1. Select the branches you want to send notifications for. +1. Click **Save changes**. + +## Resources + +- [Setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index f6590b6ba2f..ef1f492bfbf 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -24,45 +24,43 @@ want to configure. Click on the service links to see further configuration instructions and details. -| Service | Description | Service Hooks | -| ------- | ----------- | ------------- | -| Asana | Asana - Teamwork without email | No | -| Assembla | Project Management Software (Source Commits Endpoint) | No | -| [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | Yes | -| Buildkite | Continuous integration and deployments | Yes | -| [Bugzilla](bugzilla.md) | Bugzilla issue tracker | No | -| Campfire | Simple web-based real-time group chat | No | -| [Confluence](../../../api/services.md#confluence-service) | Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace | No | -| Custom Issue Tracker | Custom issue tracker | No | -| [Discord Notifications](discord_notifications.md) | Receive event notifications in Discord | No | -| Drone CI | Continuous Integration platform built on Docker, written in Go | Yes | -| [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | -| External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | -| Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](../../../operations/incident_management/integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | -| [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | -| [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | -| [HipChat](hipchat.md) | Private group chat and IM | No | -| [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | No | -| [Jira](jira.md) | Jira issue tracker | No | -| [Jenkins](../../../integration/jenkins.md) **(STARTER)** | An extendable open source continuous integration server | Yes | -| JetBrains TeamCity CI | A continuous integration and build server | Yes | -| [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | No | -| [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | No | -| [Microsoft teams](microsoft_teams.md) | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | No | -| Packagist | Update your projects on Packagist, the main Composer repository | Yes | -| Pipelines emails | Email the pipeline status to a list of recipients | No | -| [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | -| [Slack slash commands](slack_slash_commands.md) **(FREE SELF)** | Use slash commands in Slack to control GitLab | No | -| [GitLab Slack application](gitlab_slack_application.md) **(FREE SAAS)** | Use Slack's official application | No | -| PivotalTracker | Project Management Software (Source Commits Endpoint) | No | -| [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | No | -| Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | No | -| [Redmine](redmine.md) | Redmine issue tracker | No | -| [EWM](ewm.md) | EWM work item tracker | No | -| [Unify Circuit](unify_circuit.md) | Receive events notifications in Unify Circuit | No | -| [Webex Teams](webex_teams.md) | Receive events notifications in Webex Teams | No | -| [YouTrack](youtrack.md) | YouTrack issue tracker | No | +| Service | Description | Service hooks | +| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| [Asana](asana.md) | Add commit messages as comments to Asana tasks. | **{dotted-circle}** No | +| Assembla | Manage projects. | **{dotted-circle}** No | +| [Atlassian Bamboo CI](bamboo.md) | Run CI/CD pipelines with Atlassian Bamboo. | **{check-circle}** Yes | +| [Bugzilla](bugzilla.md) | Use Bugzilla as the issue tracker. | **{dotted-circle}** No | +| Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes | +| Campfire | Connect to chat. | **{dotted-circle}** No | +| [Confluence Workspace](../../../api/services.md#confluence-service) | Replace the link to the internal wiki with a link to a Confluence Cloud Workspace. | **{dotted-circle}** No | +| [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | +| [Discord Notifications](discord_notifications.md) | Send notifications about project events to a Discord channel. | **{dotted-circle}** No | +| Drone CI | Run CI/CD pipelines with Drone. | **{check-circle}** Yes | +| [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | +| [EWM](ewm.md) | Use IBM Engineering Workflow Management as the issue tracker. | **{dotted-circle}** No | +| [External wiki](../wiki/index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No | +| Flowdock | Use Flowdock with GitLab. | **{dotted-circle}** No | +| [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | +| [Hangouts Chat](hangouts_chat.md) | Receive events notifications. | **{dotted-circle}** No | +| [Irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | +| [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | +| JetBrains TeamCity CI | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | +| [Jira](jira.md) | Use Jira as the issue tracker. | **{dotted-circle}** No | +| [Mattermost notifications](mattermost.md) | Send notifications about project events to Mattermost channels. | **{dotted-circle}** No | +| [Mattermost slash commands](mattermost_slash_commands.md) | Perform common tasks with slash commands. | **{dotted-circle}** No | +| [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications. | **{dotted-circle}** No | +| Packagist | Update your projects. | **{check-circle}** Yes | +| Pipelines emails | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | +| PivotalTracker | Use PivotalTracker as the issue tracker. | **{dotted-circle}** No | +| [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | +| Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | +| [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | +| [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | +| [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | +| [Slack slash commands](slack_slash_commands.md) | Enable slash commands in workspace. | **{dotted-circle}** No | +| [Unify Circuit](unify_circuit.md) | Receive events notifications. | **{dotted-circle}** No | +| [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | +| [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit @@ -74,13 +72,6 @@ supported by `push_hooks` and `tag_push_hooks` events aren't executed. The number of branches or tags supported can be changed via [`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). -## Service templates - -Service templates are a way to set predefined values for a project integration across -all new projects on the instance. - -Read more about [Service templates](services_templates.md). - ## Project integration management Project integration management lets you control integration settings across all projects @@ -89,6 +80,19 @@ instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). +### Service templates + +[Service templates](services_templates.md) were a way to set predefined values for +a project integration across all new projects on the instance. They are deprecated and +[scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +in GitLab 14.0. + +GitLab recommends you use [project integration management](../../admin_area/settings/project_integration_management.md) +instead of service templates. GitLab versions 13.3 and later provide +[instance-level integrations](../../admin_area/settings/project_integration_management.md#project-integration-management) +you can use. +instead. + ## Troubleshooting integrations Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. GitLab stores details of service hook requests made within the last 2 days. To view details of the requests, go to that integration's configuration page. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index c307fd8d628..4922c8d9b62 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -31,6 +31,10 @@ Once enabled, GitLab detects metrics from known services in the > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. +**Deprecated:** Managed Prometheus on Kubernetes is deprecated, and +scheduled for removal in [GitLab +14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). + GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 04abb922175..0eaa9cae7c0 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 290313ac1af..11b74c35a74 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 998300e255f..584c0898fec 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 2a6bc810f71..e14c1c0f6fd 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index dcaef1e2ae6..3f888a89b1b 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index f7e6b6e76d6..8846aadd420 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 0c86c4921b3..4752fec976c 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 256ffe84ee2..77e6eb75b9f 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,37 +4,52 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Redmine Service **(FREE)** +# Redmine service **(FREE)** -1. To enable the Redmine integration in a project, navigate to the - [Integrations page](overview.md#accessing-integrations), click - the **Redmine** service, and fill in the required details on the page as described - in the table below. +Use [Redmine](https://www.redmine.org/) as the issue tracker. - | Field | Description | - | ----- | ----------- | - | `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | - | `issues_url` | The URL to the issue in Redmine 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. | - | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and is planned be removed in a future release.** | +To enable the Redmine integration in a project: - Once you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Redmine**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: - As an example, below is a configuration for a project named `gitlab-ci`. + - **Project URL**: The URL to the Redmine project to link to this GitLab project. + - **Issue URL**: The URL to the Redmine project issue to link to this GitLab project. + The URL must contain `:id`. GitLab replaces this ID with the issue number. + - **New issue URL**: The URL to use to create a new issue in the Redmine project linked to + this GitLab project. + <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 --> + **This URL is not used and removal is planned in a future release.** + For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). -  +1. Select **Save changes** or optionally select **Test settings**. -1. To disable the internal issue tracking system in a project, navigate to the General page, expand the [permissions](../settings/index.md#sharing-and-permissions) section and switch the **Issues** toggle to disabled. +After you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages, +which takes you to your Redmine project. -## Referencing issues in Redmine +For example, this is a configuration for a project named `gitlab-ci`: -Issues in Redmine can be referenced in two alternative ways: +- Project URL: `https://redmine.example.com/projects/gitlab-ci` +- Issue URL: `https://redmine.example.com/issues/:id` +- New issue URL: `https://redmine.example.com/projects/gitlab-ci/issues/new` -- `#<ID>` where `<ID>` is a number (example `#143`). -- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is - then followed by capital letters, numbers or underscores, and `<ID>` is - a number (example `API_32-143`). +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +Learn more about the steps and consequences of disabling GitLab issues in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. +## Reference Redmine issues in GitLab -Please note that `<PROJECT>` part is ignored and links always point to the -address specified in `issues_url`. +You can reference your Redmine issues using: + +- `#<ID>`, where `<ID>` is a number (example `#143`). +- `<PROJECT>-<ID>`, for example `API_32-143`, where: + - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores. + - `<ID>` is a number. + +In links, the `<PROJECT>` part is ignored, and they always point to the address specified in **Issue URL**. + +We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 66810d8a01b..93ce74eb735 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -36,10 +36,11 @@ does not provide central administration of integration settings. ## Central administration of project integrations A new set of features is being introduced in GitLab to provide more control over -how integrations are configured at the instance, group, and project level. +how integrations are configured at the instance, group, and project level. For +more information, read more about: -[Read more about setting up project integration management](../../admin_area/settings/project_integration_management.md) -(introduced in GitLab 13.3) and [our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). +- [Setting up project integration management](../../admin_area/settings/project_integration_management.md) (introduced in GitLab 13.3) +- [Our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Enable a service template diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index bf289c9707c..56a339e02d2 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1297,6 +1297,7 @@ X-Gitlab-Event: Job Hook "build_name": "test", "build_stage": "test", "build_status": "created", + "build_created_at": "2021-02-23T02:41:37.886Z", "build_started_at": null, "build_finished_at": null, "build_duration": null, @@ -1310,7 +1311,6 @@ X-Gitlab-Event: Job Hook "name": "User", "email": "user@gitlab.com", "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "admin@example.com" }, "commit": { "id": 2366, diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index a537972dff7..5ddf98d4560 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -14,7 +14,7 @@ It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) It pairs issue tracking and project management, keeping everything together, so that you don't need to jump between different platforms to organize your workflow. -Issue boards build on the existing [issue tracking functionality](issues/index.md#issues-list) and +Issue boards build on the existing [issue tracking functionality](issues/index.md) and [labels](labels.md). Your issues appear as cards in vertical lists, organized by their assigned labels, [milestones](#milestone-lists), or [assignees](#assignee-lists). @@ -88,7 +88,7 @@ You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. For examples of using issue boards along with [epics](../group/epics/index.md), -[issue health status](issues/index.md#health-status), and +[issue health status](issues/managing_issues.md#health-status), and [scoped labels](labels.md#scoped-labels) for various Agile frameworks, check: - The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) @@ -280,6 +280,7 @@ group-level objects are available. #### GraphQL-based sidebar for group issue boards **(PREMIUM)** <!-- When the feature flag is removed, integrate this section into the above ("Group issue boards"). --> +<!-- This anchor is linked from #blocked-issues as well. --> > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. > - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. @@ -339,6 +340,33 @@ As in other list types, click the trash icon to remove a list.  +### Iteration lists **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. +> - [Deployed behind the `board_new_lists` and `iteration_board_lists` feature flags](../feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57439) in GitLab 13.11. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_lists`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** + +There can be +[risks when disabling released features](../feature_flags.md#risks-when-disabling-released-features). +Refer to this feature's version history for more details. + +You're also able to create lists of an iteration. +These are lists that filter issues by the assigned +iteration. To add an iteration list: + +1. Select **Create list**. +1. Select the **Iteration**. +1. In the dropdown, select an iteration. +1. Select **Add to board**. + +Like the milestone lists, you're able to [drag issues](#drag-issues-between-lists) +to and from a iteration list to manipulate the iteration of the dragged issues. + + + ### Group issues in swimlanes **(PREMIUM)** > - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. @@ -407,18 +435,23 @@ 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. +> - [View blocking issues when hovering over blocked icon](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10. If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked status. - +When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. + +To enable this in group issue boards, enable the [GraphQL-based sidebar](#graphql-based-sidebar-for-group-issue-boards). +The feature is enabled by default when you use group issue boards with epic swimlanes. + + ## Actions you can take on an issue board - [Create a new list](#create-a-new-list). - [Remove an existing list](#remove-a-list). -- [Add issues to a list](#add-issues-to-a-list). - [Remove an issue from a list](#remove-an-issue-from-a-list). - [Filter issues](#filter-issues) that appear across your issue board. - [Create workflows](#create-workflows). @@ -457,31 +490,19 @@ To remove a list from an issue board: 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. -### Add issues to a list **(FREE SELF)** +### Add issues to a list -> - Feature flag [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47898) in GitLab 13.7. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(FREE SELF)** +> The **Add issues** button was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57329) in GitLab 13.11. -You can add issues to a list in a project issue board by clicking the **Add issues** button -in the top right corner of the issue board. This opens up a modal -window where you can see all the issues that do not belong to any list. +If your board is scoped to one or more attributes, go to the issues you want to add and apply the +same attributes as your board scope. -Select one or more issues by clicking the cards and then click **Add issues** -to add them to the selected list. You can limit the issues you want to add to -the list by filtering by the following: +For example, to add an issue to a list scoped to the `Doing` label, in a group issue board: -- Assignee -- Author -- Epic -- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) -- Label -- Milestone -- My Reaction -- Release -- Weight +1. Go to an issue in the group or one of the subgroups or projects. +1. Add the `Doing` label. + +The issue should now show in the `Doing` list on your issue board. ### Remove an issue from a list @@ -542,7 +563,7 @@ worked on by the designers. Then, when they're done, all they have to do is drag it to the next list, **Backend**. Then, a backend developer can -eventually pick it up. When they’re done, they move it to **Done**, to close the +eventually pick it up. When they're done, they move it to **Done**, to close the issue. This process can be seen clearly when visiting an issue. With every move @@ -625,20 +646,43 @@ To disable it: Feature.disable(:graphql_board_lists) ``` -## Enable or disable adding issues to the list **(FREE SELF)** +### Enable or disable new add list form **(FREE SELF)** -Adding issues to the list is deployed behind a feature flag that is **disabled by default**. +The new form for adding lists is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can disable it. + +To enable it: + +```ruby +Feature.enable(:board_new_list) +``` + +To disable it: + +```ruby +Feature.disable(:board_new_list) +``` + +### Enable or disable iteration lists in boards **(PREMIUM SELF)** + +NOTE: +When disabling iteration lists in boards, you also need to disable the [new add list form](#enable-or-disable-new-add-list-form). + +The iteration list is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can disable it. To enable it: ```ruby -Feature.enable(:add_issues_button) +Feature.enable(:iteration_board_lists) ``` To disable it: ```ruby -Feature.disable(:add_issues_button) +Feature.disable(:iteration_board_lists) ``` diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index e1918b68ddc..25357a1db0b 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -19,7 +19,7 @@ You can make an issue confidential during issue creation or by editing an existing one. When you create a new issue, a checkbox right below the text area is available -to mark the issue as confidential. Check that box and hit the **Submit issue** +to mark the issue as confidential. Check that box and hit the **Create issue** button to create the issue. For existing issues, edit them, check the confidential checkbox and hit **Save changes**. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 250fa618dd8..63b38520c98 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -4,18 +4,21 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Crosslinking Issues +# Crosslinking issues -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. +There are several ways to mention an issue or make issues appear in each other's +[Linked issues](related_issues.md) section. -## From Commit Messages +For more information on GitLab Issues, read the [issues documentation](index.md). + +## From commit messages Every time you mention an issue in your commit message, you're creating a relationship between the two stages of the development workflow: the issue itself and the first commit related to that issue. If the issue and the code you're committing are both in the same project, -you simply add `#xxx` to the commit message, where `xxx` is the issue number. +add `#xxx` to the commit message, where `xxx` is the issue number. If they are not in the same project, you can add the full URL to the issue (`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). @@ -36,11 +39,10 @@ for tracking your process with [GitLab Value Stream Analytics](https://about.git It measures the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. -## From Related Issues +## From linked issues -Mentioning related issues in merge requests and other issues is useful -for your team members and collaborators to know that there are opened -issues regarding the same topic. +Mentioning linked issues in merge requests and other issues helps your team members and +collaborators know that there are opened issues regarding the same topic. You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages). @@ -50,13 +52,13 @@ display in both issues. The same is valid when mentioning issues in [merge reque  -## From Merge Requests +## From merge requests Mentioning issues in merge request comments works exactly the same way as -they do for [related issues](#from-related-issues). +they do for [linked issues](#from-linked-issues). When you mention an issue in a merge request description, it -[links the issue and merge request together](#from-related-issues). Additionally, +[links the issue and merge request together](#from-linked-issues). Additionally, you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically) as soon as the merge request is merged. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 2757642e458..de7a36a4886 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -52,9 +52,12 @@ When importing issues from a CSV file, it must be formatted in a certain way: - **data rows:** After the header row, succeeding rows must follow the same column order. The issue title is required while the description is optional. +If you have special characters _within_ a field, (such as `\n` or `,`), +wrap the characters in double quotes. + Sample CSV data: -```csv +```plaintext title,description My Issue Title,My Issue Description Another Title,"A description, with a comma" diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 909a20f0e2f..a82823947dc 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -37,7 +37,7 @@ The last way to set a due date is by using [quick actions](../quick_actions.md), ## Making use of due dates -You can see issues with their due dates in the [issues list](index.md#issues-list). +You can see issues with their due dates in the issues list. Overdue issues have their icon and date colored red. To sort issues by their due dates, select **Due date** from the dropdown menu on the right. Issues are then sorted from the earliest due date to the latest. diff --git a/doc/user/project/issues/img/issue_health_status_dropdown_v12_10.png b/doc/user/project/issues/img/issue_health_status_dropdown_v12_10.png Binary files differdeleted file mode 100644 index f8517de4e12..00000000000 --- a/doc/user/project/issues/img/issue_health_status_dropdown_v12_10.png +++ /dev/null diff --git a/doc/user/project/issues/img/issues_main_view.png b/doc/user/project/issues/img/issues_main_view.png Binary files differdeleted file mode 100644 index a929916c682..00000000000 --- a/doc/user/project/issues/img/issues_main_view.png +++ /dev/null diff --git a/doc/user/project/issues/img/project_issues_list_view.png b/doc/user/project/issues/img/project_issues_list_view.png Binary files differdeleted file mode 100644 index c80bd58f5c9..00000000000 --- a/doc/user/project/issues/img/project_issues_list_view.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 7c8ba4edd6b..ec0cdc116d6 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -6,209 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issues **(FREE)** -Issues are the fundamental mechanism in GitLab to collaborate on ideas, solve -problems, and plan work. - -Using issues, you can share and discuss proposals (both before and during their -implementation) between you and your team, and outside collaborators. +Use issues to collaborate on ideas, solve problems, and plan work. +Share and discuss proposals with your team and with outside collaborators. You can use issues for many purposes, customized to your needs and workflow. -Common use cases include: -- Discussing the implementation of a new idea. -- Tracking tasks and work status. -- Accepting feature proposals, questions, support requests, or bug reports. -- Elaborating on new code implementations. +- Discuss the implementation of an idea. +- Track tasks and work status. +- Accept feature proposals, questions, support requests, or bug reports. +- Elaborate on code implementations. -For more information about using issues, see the -[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/) -GitLab blog post. +For more information about using issues, see the GitLab blog post: +[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). Issues are always associated with a specific project. If you have multiple -projects in a group, you can view all of the issues collectively at the group -level. +projects in a group, you can view all of the projects' issues at once. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and +To learn how the GitLab Strategic Marketing department uses GitLab issues with [labels](../labels.md) and [issue boards](../issue_board.md), see the video on [Managing Commitments with Issues](https://www.youtube.com/watch?v=cuIHNintg1o&t=3). -## Parts of an issue - -Issues have a flexible content and metadata structure. Here are some of the -elements you can provide in an issue: - -- Title -- Description and tasks -- Comments and other activity -- Author -- Assignees -- State (open or closed) -- Health status (on track, needs attention, or at risk) -- Confidentiality -- Tasks (completed vs. outstanding) -- Milestone -- Due date -- Weight -- Time tracking -- Labels -- Votes -- Reaction emoji -- Linked issues -- Assigned epic -- Unique issue number and URL - -## View and manage issues - -Key actions for issues include: - -- [Creating issues](managing_issues.md#create-a-new-issue) -- [Moving issues](managing_issues.md#moving-issues) -- [Closing issues](managing_issues.md#closing-issues) -- [Deleting issues](managing_issues.md#deleting-issues) -- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) - -Although you can view and manage details of an issue on the [issue page](#issue-page), -you can also work with several issues at a time by using these features: - -- [Issues List](#issues-list): View a list of issues in a project or group. -- [Issue Boards](../issue_board.md): Organize issues with a project management - workflow for a feature or product release. -- Issue references -- [Epics](../../group/epics/index.md): Manage your portfolio of projects by - tracking groups of issues with a shared theme. - -### Issue page - - - -On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md), -and modify them if you have the necessary [permissions](../../permissions.md). - -#### Real-time sidebar **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. - -Assignees in the sidebar are updated in real time. This feature is **disabled by default**. -To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). - -### Issues List - - - -In the Issues List, you can: - -- View all issues in a project when opening the Issues List from a project context. -- View all issues in a groups's projects when opening the Issues List from a group context. - -You can filter the Issues List with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), -including specific metadata, such as labels, assignees, status, and more. From this -view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. - -For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page -for a rundown of all the fields and information in an issue. - -You can sort a list of issues in several ways, for example by issue creation date, milestone due date. -For more information, see the [Sorting and ordering issue lists](sorting_issue_lists.md) page. - -#### Cached issue count - -> - [Introduced]([link-to-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/243753)) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use this feature in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cached-issue-count) **(FREE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In a group, the sidebar displays the total count of open issues and this value is cached if higher -than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. - -### Design Management - -With [Design Management](design_management.md), you can upload design -assets to issues and view them all together for sharing and -collaboration with your team. - -### Related issues - -You can mark two issues as related, so that when viewing one, the other is always -listed in its [Related Issues](related_issues.md) section. This can help display important -context, such as past work, dependencies, or duplicates. - -Users of [GitLab Premium](https://about.gitlab.com/pricing/) or higher can -also mark issues as blocking or blocked by another issue. - -### Crosslinking issues - -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. - -### Similar issues - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22866) in GitLab 11.6. - -To prevent duplication of issues for the same topic, GitLab searches for similar issues -when new issues are being created. - -As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions -across all issues to in the current project. Only issues you have access to are returned. -Up to five similar issues, sorted by most recently updated, are displayed below the title box. -[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature. - - - -### Health status **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10. -> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later. -> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. - -To help you track issue statuses, you can assign a status to each issue. -This marks issues as progressing as planned or needs attention to keep on schedule: - -- **On track** (green) -- **Needs attention** (amber) -- **At risk** (red) - - - -After an issue is closed, its health status can't be edited and the "Edit" button becomes disabled -until the issue is reopened. - -You can then see issue statuses in the [issue list](#issues-list) and the -[Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). - -## Other Issue actions +## Related topics +- [Create issues](managing_issues.md#create-a-new-issue) - [Create an issue from a template](../../project/description_templates.md#use-the-templates) +- [Move issues](managing_issues.md#moving-issues) +- [Close issues](managing_issues.md#closing-issues) +- [Delete issues](managing_issues.md#deleting-issues) +- [Promote issues](managing_issues.md#promote-an-issue-to-an-epic) - [Set a due date](due_dates.md) -- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues - in order to change their status, assignee, milestone, or labels in bulk. - [Import issues](csv_import.md) - [Export issues](csv_export.md) +- [Upload designs to issues](design_management.md) +- [Linked issues](related_issues.md) +- [Cross-link issues](crosslinking_issues.md) +- [Bulk edit issues](../bulk_editing.md) +- [Sort issue lists](sorting_issue_lists.md) +- [Search for issues](../../search/index.md#filtering-issue-and-merge-request-lists) +- [Epics](../../group/epics/index.md) +- [Issue Boards](../issue_board.md) - [Issues API](../../../api/issues.md) -- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) - such as Jira, Redmine, Bugzilla, or EWM. - -## Enable or disable cached issue count **(FREE SELF)** - -Cached issue count in the left sidebar is under development and not ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:cached_sidebar_open_issues_count) -``` - -To enable it: - -```ruby -Feature.enable(:cached_sidebar_open_issues_count) -``` +- [Configure an external issue tracker](../../../integration/external-issue-tracker.md) +- [Parts of an issue](issue_data_and_actions.md) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 90c918792d7..2963555869c 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -39,7 +39,7 @@ The numbers in the image correspond to the following features: - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) -- **18.** [Related Issues](#related-issues) +- **18.** [Linked Issues](#linked-issues) - **19.** [Related Merge Requests](#related-merge-requests) - **20.** [Award emoji](#award-emoji) - **21.** [Show all activity](#show-all-activity) @@ -205,10 +205,10 @@ in a different color, which allows you to quickly see which comments involve you Avoid mentioning `@all` in issues and merge requests, as it sends an email notification to all the members of that project's group. This might be interpreted as spam. -### Related Issues +### Linked Issues -Issues that were mentioned as [related issues](related_issues.md) are listed here. -You can also click the `+` to add more related issues. +Issues that were mentioned as [linked issues](related_issues.md) are listed here. +You can also click the `+` to add more linked issues. ### Related Merge Requests diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index cfb22881431..dafc0e6ba02 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -144,7 +144,7 @@ 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, 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 +## Moving issues Moving an issue copies it to the target project, and closes it in the originating project. The original issue is not deleted. A system note, which indicates @@ -154,7 +154,7 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i  -### Moving Issues in Bulk +### Moving issues in bulk **(FREE SELF)** If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script moves all issues @@ -199,7 +199,7 @@ can be closed automatically when the commit reaches the project's default branch If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), all issues referenced in the matched text are closed. This happens when the commit -is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch), +is pushed to a project's [**default** branch](../repository/branches/default.md), or when a commit or merge request is merged into it. For example, if `Closes #4, #6, Related to #5` is included in a Merge Request @@ -315,3 +315,44 @@ To add an issue to an [iteration](../../group/iterations/index.md): You can also use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a comment or description field. + +## Real-time sidebar **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. + +Assignees in the sidebar are updated in real time. This feature is **disabled by default**. +To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). + +## Similar issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22866) in GitLab 11.6. + +To prevent duplication of issues for the same topic, GitLab searches for similar issues +when new issues are being created. + +As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions +across all issues to in the current project. Only issues you have access to are returned. +Up to five similar issues, sorted by most recently updated, are displayed below the title box. +[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature. + + + +## Health status **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10. +> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later. +> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. + +To help you track issue statuses, you can assign a status to each issue. +This marks issues as progressing as planned or needs attention to keep on schedule: + +- On track (green) +- Needs attention (amber) +- At risk (red) + +After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled +until the issue is reopened. + +You can then see issue statuses in the issues list and the +[epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 91c26d49532..e4972181a5a 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,67 +4,63 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Related issues **(FREE)** +# Linked issues **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. -> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. +> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. -Related issues are a bi-directional relationship between any two issues -and appear in a block below the issue description. Issues can be across groups -and projects. +Linked issues are a bi-directional relationship between any two issues and appear in a block below +the issue description. Issues can be across groups and projects. -You can set any issue as: - -- Related to another issue -- Blocking another issue **(STARTER)** -- Blocked by another issue **(STARTER)** - -The relationship only shows up in the UI if the user can see both issues. - -When you try to close an issue that has open blockers, a warning is displayed. +The relationship only shows up in the UI if the user can see both issues. When you try to close an +issue that has open blockers, a warning is displayed. NOTE: -To manage related issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). +To manage linked issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). -## Adding a related issue +## Add a linked issue -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2035) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) to warn when attempting to close an issue that is blocked by others in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2035) in GitLab 12.8. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) to warn when attempting to close an issue that is blocked by others in GitLab 13.0. > When you try to close an issue with open blockers, you see a warning that you can dismiss. -1. Relate one issue to another by clicking the related issues "+" button -in the header of the related issue block. +1. Link one issue to another by selecting the add linked issue button (**{plus}**) in the + **Linked issues** section of an issue. -1. Input the issue reference number or paste in the full URL of the issue. +1. Select the relationship the between the two issues. Either: + - **relates to** + - **blocks** **(PREMIUM)** + - **is blocked by** **(PREMIUM)** +1. Input the issue number or paste in the full URL of the issue. -1. **(STARTER)** Select whether the current issue relates to, blocks, or is blocked by the issues being entered. +  -  + Issues of the same project can be specified just by the reference number. + Issues from a different project require additional information like the + group and the project name. For example: - Issues of the same project can be specified just by the reference number. - Issues from a different project require additional information like the - group and the project name. For example: + - The same project: `#44` + - The same group: `project#44` + - Different group: `group/project#44` - - same project: `#44` - - same group: `project#44` - - different group: `group/project#44` + Valid references are added to a temporary list that you can review. - Valid references are added to a temporary list that you can review. +1. When you have added all the linked issues, select **Add**. -1. When you have added all the related issues, click **Add** to submit. - -When you have finished adding all related issues, you can see +When you have finished adding all linked issues, you can see them categorized so their relationships can be better understood visually.  -## Removing a related issue +You can also add a linked issue from a commit message or the description in another issue or MR. +[Learn more about crosslinking issues](crosslinking_issues.md). + +## Remove a linked issue -In the related issues block, click the "x" icon on the right-side of each issue -token that you wish to remove. +In the **Linked issues** section of an issue, click the remove button (**{close}**) on the +right-side of each issue token to remove. -Due to the bi-directional relationship, it no longer appears in either issue. +Due to the bi-directional relationship, the relationship no longer appears in either issue.  -Please access our [permissions](../../permissions.md) page for more information. +Access our [permissions](../../permissions.md) page for more information. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 3a393b18579..97a790c2527 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -24,6 +24,12 @@ For sorting by issue priority, see [Label Priority](../labels.md#label-priority) In group and project issue lists, it is also possible to order issues manually, similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). +## Sorting by popularity + +When you select sorting by **Popularity**, the issue order changes to sort descending by the +number of upvotes ([awarded](../../award_emojis.md) "thumbs up" emoji) +on each issue. You can use this to identify issues that are in high demand. + ## Manual sorting > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index c0a66343a88..fd5045f2e93 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -162,7 +162,7 @@ Scoped labels allow teams to use the label feature to annotate issues, merge req and epics with mutually exclusive labels. This can enable more complicated workflows by preventing certain labels from being used together. -A label is scoped when it uses a special double-colon (`::`) syntax in the label’s +A label is scoped when it uses a special double-colon (`::`) syntax in the label's title, for example:  diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 057c2930706..2993849e0e6 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -78,7 +78,8 @@ want to add.  Select the user and the [permission level](../../permissions.md) -that you'd like to give the user. Note that you can select more than one user. +that you'd like to give the user. You can add more than one user at a time. +The Owner role can only be assigned at the group level.  @@ -108,6 +109,9 @@ had on the project you imported from are retained. ## Invite people using their e-mail address +NOTE: +In GitLab 13.11, you can [replace this form with a modal window](#add-a-member-modal-window). + If a user you want to give access to doesn't have an account on your GitLab instance, you can invite them just by typing their e-mail address in the user search field. @@ -134,6 +138,46 @@ GitLab account using the same e-mail address the invitation was sent to. NOTE: Unaccepted invites are automatically deleted after 90 days. +### Add a member modal window + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11. +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - Replaces the existing form with buttons to open a modal window. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +In GitLab 13.11, you can optionally replace the form to add a member with a modal window. +To add a member after enabling this feature: + +1. Go to your project's page. +1. In the left sidebar, go to **Members**, and then select **Invite members**. +1. Enter an email address, and select a role permission for this user. +1. (Optional) Select an **Access expiration date**. +1. Select **Invite**. + +### Enable or disable modal window **(FREE SELF)** + +The modal window for adding a member is under development and is 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. + +To enable it: + +```ruby +Feature.enable(:invite_members_group_modal) +``` + +To disable it: + +```ruby +Feature.disable(:invite_members_group_modal) +``` + ## Project membership and requesting access Project owners can : diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 8ca403783cb..8338c17f4ba 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -17,6 +17,9 @@ members. ## Sharing a project with a group of users +NOTE: +In GitLab 13.11, you can [replace this form with a modal window](#share-a-project-modal-window). + The primary mechanism to give a group of users, say 'Engineering', access to a project, say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project Acme'. But what if 'Project Acme' already belongs to another group, say 'Open Source'? @@ -48,6 +51,46 @@ Note that you can only share a project with: Administrators are able to share projects with any group in the system. +### Share a project modal window + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11. +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - Replaces the existing form with buttons to open a modal window. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +In GitLab 13.11, you can optionally replace the sharing form with a modal window. +To share a project after enabling this feature: + +1. Go to your project's page. +1. In the left sidebar, go to **Members**, and then select **Invite a group**. +1. Select a group, and select a **Max access level**. +1. (Optional) Select an **Access expiration date**. +1. Select **Invite**. + +### Enable or disable modal window **(FREE SELF)** + +The modal window for sharing a project is under development and is 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. + +To enable it: + +```ruby +Feature.enable(:invite_members_group_modal) +``` + +To disable it: + +```ruby +Feature.disable(:invite_members_group_modal) +``` + ## Maximum access level In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index c518113d3dd..09770bd447d 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -57,7 +57,7 @@ include: creates an `a11y` job in your CI/CD pipeline, runs Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each. -The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#browsing-artifacts). +The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. It includes report data for all URLs scanned. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 7a869ed071a..76913351283 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,7 +40,7 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance). +[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. @@ -88,7 +88,7 @@ The example uses a CI/CD template that is included in all GitLab installations s or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4c9a6557320..f531cd52af1 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -9,7 +9,7 @@ type: reference, concepts GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") -with introducing a **Cherry-pick** button in merge requests and commit details. +with a **Cherry-pick** button in merge requests and commit details. ## Cherry-picking a merge request @@ -60,6 +60,46 @@ mainline: git cherry-pick -m 2 7a39eb0 ``` +### Cherry-pick into a project + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cherry-picking-into-a-project). **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can use the GitLab UI to cherry-pick merge requests into a project, even if the +merge request is from a fork: + +1. In the merge request's secondary menu, click **Commits** to display the commit details page. +1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. +1. In **Pick into project** and **Pick into branch**, select the destination project and branch: +  +1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. +1. Click **Cherry-pick**. + +### Enable or disable cherry-picking into a project **(FREE SELF)** + +Cherry-picking into a project 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. + +To enable it: + +```ruby +Feature.enable(:pick_into_project) +``` + +To disable it: + +```ruby +Feature.disable(:pick_into_project) +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 42c2547a618..0fe1b9801cc 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -15,7 +15,7 @@ source code quality using GitLab Code Quality. Code Quality: -- Uses [Code Climate Engines](https://codeclimate.com), which are +- Uses [Engines](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are 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 @@ -33,7 +33,7 @@ Code Quality: Going a step further, GitLab can show the Code Quality report right in the merge request widget area if a report from the target branch is available to compare to: - + Watch a quick walkthrough of Code Quality in action: @@ -49,6 +49,26 @@ For one customer, the auditor found that having Code Quality, SAST, and Containe See also the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). +## Code Quality in diff view **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. +> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. + +Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, +an indicator is displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view. For example: + + + +To enable this feature, a GitLab administrator can run the following in a +[Rails console](../../../administration/operations/rails_console.md): + +```ruby +# For the instance +Feature.enable(:codequality_mr_diff) +# For a single project +Feature.enable(:codequality_mr_diff, Project.find(<project id>)) +``` + ## Use cases For instance, consider the following workflow: @@ -85,7 +105,7 @@ include: The above example creates a `code_quality` job in your CI/CD pipeline which scans your source code for code quality issues. The report is saved as a -[Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -242,12 +262,11 @@ to learn more about how to define one. To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable. This can be done: -- For the whole project, [in the project settings](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) - or [CI/CD configuration](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). +- For [the whole project](../../../ci/variables/README.md#custom-cicd-variables). - For a single pipeline run: 1. Go to **CI/CD > Pipelines** - 1. Click **Run Pipeline** + 1. Click **Run pipeline** 1. Add `CODE_QUALITY_DISABLED` as the variable key, with any value. ### Using with merge request pipelines @@ -309,7 +328,7 @@ do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the [Code Quality report - artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality). + artifact](../../../ci/yaml/README.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). @@ -347,7 +366,11 @@ NOTE: Although the Code Climate spec supports more properties, those are ignored by GitLab. -## Code Quality reports +## Code Quality reports **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21527) in GitLab Premium 12.9. + + After the Code Quality job completes: @@ -355,7 +378,7 @@ After the Code Quality job completes: The Code Quality widget in the merge request compares the reports from the base and head of the branch, then lists any violations that are resolved or created when the branch is merged. - The full JSON report is available as a - [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) + [downloadable artifact](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) for the `code_quality` job. - The full list of code quality violations generated by a pipeline is shown in the Code Quality tab of the Pipeline Details page. **(PREMIUM)** @@ -552,3 +575,8 @@ plugins: enabled: true channel: rubocop-0-67 ``` + +### No Code Quality appears on merge requests when using custom tool + +If your merge requests do not show any code quality changes when using a custom tool, +ensure that the line property is an `integer`. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 58e80504212..3a5a581198b 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -172,6 +172,9 @@ create a merge request from your fork to contribute back to the main project: 1. In the left menu, go to **Merge Requests**, and click **New Merge Request**. 1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. 1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. + You can set a [default target project](#set-the-default-target-project) to + change the default target branch (which can be useful when working with a + forked project). 1. After entering the credentials, click **Compare branches and continue** to compare your local changes to the upstream repository. 1. Assign a user to review your changes, and click **Submit merge request**. @@ -183,6 +186,24 @@ fork from its upstream project in the **Settings > Advanced Settings** section b For further details, [see the forking workflow documentation](../repository/forking_workflow.md). +## Set the default target project + +Merge requests have a source and a target project which are the same, unless +forking is involved. Creating a fork of the project can cause either of these +scenarios when you create a new merge request: + +- You target an upstream project (the project you forked, and the default + option). +- You target your own fork. + +If you want to have merge requests from a fork by default target your own fork +(instead of the upstream project), you can change the default by: + +1. In your project, go to **Settings > General > Merge requests**. +1. In the **Target project** section, select the option you want to use for + your default target project. +1. Select **Save changes**. + ## New merge request by email **(FREE SELF)** _This feature needs [incoming email](../../../administration/incoming_email.md) diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f4843b96c99..f973d9220f2 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -41,5 +41,5 @@ The following table shows what attributes will be present in the CSV. ## Limitations -- Export merge requests to CSV is not available at the Group’s merge request list. +- Export merge requests to CSV is not available at the Group's merge request list. - As the merge request CSV file is sent as an email attachment, the size is limited to 15MB to ensure successful delivery across a range of email providers. If you need to minimize the size of the file, you can narrow the search before export. For example, you can set up exports of open and closed merge requests in separate files. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index f25228729cf..1bb333dcb14 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -206,10 +206,10 @@ is set for deletion, the merge request widget displays the ### Branch retargeting on merge **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) on GitLab 13.10. -> - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) in GitLab 13.10. +> - Recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is @@ -230,8 +230,6 @@ GitLab retargets up to four merge requests when their target branch is merged in `master`, so you don't need to perform this operation manually. Merge requests from forks are not retargeted. -The feature today works only one a merge. Clicking the `Remove source branch` button -after the merge request was merged will not automatically retarget merge request. The feature today works only on merge. Clicking the **Remove source branch** button after the merge request was merged will not automatically retarget a merge request. This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). diff --git a/doc/user/project/merge_requests/img/cherry_pick_into_project_v13_11.png b/doc/user/project/merge_requests/img/cherry_pick_into_project_v13_11.png Binary files differnew file mode 100644 index 00000000000..ada036255f2 --- /dev/null +++ b/doc/user/project/merge_requests/img/cherry_pick_into_project_v13_11.png diff --git a/doc/user/project/merge_requests/img/code_quality.png b/doc/user/project/merge_requests/img/code_quality.png Binary files differdeleted file mode 100644 index 1e7dd64baff..00000000000 --- a/doc/user/project/merge_requests/img/code_quality.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png Binary files differnew file mode 100644 index 00000000000..0fcdc252735 --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png diff --git a/doc/user/project/merge_requests/img/code_quality_report_13_11.png b/doc/user/project/merge_requests/img/code_quality_report_13_11.png Binary files differnew file mode 100644 index 00000000000..36341548328 --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_report_13_11.png diff --git a/doc/user/project/merge_requests/img/code_quality_widget_13_11.png b/doc/user/project/merge_requests/img/code_quality_widget_13_11.png Binary files differnew file mode 100644 index 00000000000..57978a0ed96 --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_widget_13_11.png diff --git a/doc/user/project/merge_requests/img/commit_nav_v13_11.png b/doc/user/project/merge_requests/img/commit_nav_v13_11.png Binary files differnew file mode 100644 index 00000000000..a9bc8fa6bee --- /dev/null +++ b/doc/user/project/merge_requests/img/commit_nav_v13_11.png diff --git a/doc/user/project/merge_requests/img/commit_nav_v13_4.png b/doc/user/project/merge_requests/img/commit_nav_v13_4.png Binary files differdeleted file mode 100644 index 0ae6ce32693..00000000000 --- a/doc/user/project/merge_requests/img/commit_nav_v13_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_tab_position_v12_6.png b/doc/user/project/merge_requests/img/merge_request_tab_position_v12_6.png Binary files differdeleted file mode 100644 index 9284e58f456..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_tab_position_v12_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png b/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png Binary files differnew file mode 100644 index 00000000000..52c715840f1 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png Binary files differindex b1c2e147134..a6636f0bc7f 100644 --- a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png +++ b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png Binary files differindex c0cc0db600c..c5596b965ff 100644 --- a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png +++ b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 99e0193d496..1fed30dc589 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -7,12 +7,10 @@ type: index, reference # Merge requests **(FREE)** -Whenever you need to merge one branch into another branch with GitLab, you -must create a merge request (MR). +Merge requests (MRs) are the way you check source code changes into a branch. -Using merge requests, you can visualize and collaborate on proposed changes to -source code. Merge requests display information about the proposed code changes, -including: +When you open a merge request, you can visualize and collaborate on the code changes before merge. +Merge requests include: - A description of the request. - Code changes and inline code reviews. @@ -20,55 +18,50 @@ including: - A comment section for discussion threads. - The list of commits. -Based on your workflow, after review you can merge a merge request into its -target branch. - To get started, read the [introduction to merge requests](getting_started.md). -## Use cases +## Merge request workflows -A. Consider you're a software developer working in a team: +For a software developer working in a team: -1. You checkout a new branch, and submit your changes through a merge request -1. You gather feedback from your team -1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) -1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD -1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md) **(ULTIMATE)** -1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** +1. You checkout a new branch, and submit your changes through a merge request. +1. You gather feedback from your team. +1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md). +1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD. +1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). +1. You request the [approval](merge_request_approvals.md) from your manager. 1. Your manager: - 1. Pushes a commit with their final review - 1. [Approves the merge request](merge_request_approvals.md) **(STARTER)** - 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md) -1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD -1. Your implementations were successfully shipped to your customer - -B. Consider you're a web developer writing a webpage for your company's website: - -1. You checkout a new branch, and submit a new page through a merge request -1. You gather feedback from your reviewers -1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md) -1. You request your web designers for their implementation -1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** -1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) -1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production + 1. Pushes a commit with their final review. + 1. [Approves the merge request](merge_request_approvals.md). + 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). +1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD. +1. Your implementations were successfully shipped to your customer. + +For a web developer writing a webpage for your company's website: + +1. You checkout a new branch and submit a new page through a merge request. +1. You gather feedback from your reviewers. +1. You preview your changes with [Review Apps](../../../ci/review_apps/index.md). +1. You request your web designers for their implementation. +1. You request the [approval](merge_request_approvals.md) from your manager. +1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). +1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. ## Merge request navigation tabs at the top > [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 +In GitLab 12.5 and earlier, navigation tabs in merge requests (**Discussion**, +**Commits**, **Pipelines**, and **Changes**) were located after the merge request widget. -To facilitate this navigation without having to scroll up and down through the page -to find these tabs, based on user feedback, we're experimenting with a new positioning -of these tabs. They are now located at the top of the merge request, with a new -**Overview** tab, containing the description of the merge request followed by the -widget. Next to **Overview**, you can find **Pipelines**, **Commits**, and **Changes**. +To facilitate navigation without scrolling, and based on user feedback, the tabs are +now located at the top of the merge request tab. A new **Overview** tab was added, +and next to **Overview** are **Commits**, **Pipelines**, and **Changes**. - + -Please note this change is currently behind a feature flag which is enabled by default. For +This change is behind a feature flag that is enabled by default. For self-managed instances, it can be disabled through the Rails console by a GitLab administrator with the following command: @@ -76,23 +69,9 @@ administrator with the following command: Feature.disable(:mr_tabs_position) ``` -## Creating merge requests - -Learn [how to create a merge request](creating_merge_requests.md). - -## Reviewing and managing merge requests - -See the features at your disposal to [review and manage merge requests](reviewing_and_managing_merge_requests.md). - -## Testing and reports in merge requests - -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 - -There are two main ways to have a merge request flow with GitLab: - -1. Working with [protected branches](../protected_branches.md) in a single repository -1. Working with forks of an authoritative project +## Related topics -[Learn more about the authorization for merge requests.](authorization_for_merge_requests.md) +- [Create a merge request](creating_merge_requests.md) +- [Review and manage merge requests](reviewing_and_managing_merge_requests.md) +- [Authorization for merge requests](authorization_for_merge_requests.md) +- [Testing and reports](testing_and_reports_in_merge_requests.md) diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index e8062fadcfe..865a18a6a05 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance). +[Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance). +as a [Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 3d3e04842f8..835350ade44 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -13,6 +13,7 @@ type: reference, concepts Code review is an essential practice of every successful project. Approving a merge request is an important part of the review process, as it clearly communicates the ability to merge the change. +A [merge request approvals API](../../../api/merge_request_approvals.md) is also available. ## Optional Approvals @@ -23,6 +24,39 @@ This provides a consistent mechanism for reviewers to approve merge requests, an maintainers know a change is ready to merge. Approvals in Free are optional, and do not prevent a merge request from being merged when there is no approval. +## External approvals **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. +> - It's [deployed behind a feature flag](../../feature_flags.md), 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](../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +When you create an external approval rule, the following merge request actions sends information +about a merge request to a third party service: + +- Create +- Change +- Close + +This action enables use-cases such as: + +- Integration with 3rd party workflow tools, such as [ServiceNow](https://www.servicenow.co.uk/). +- Integration with custom tools designed to approve merge requests from outside of GitLab. + +You can find more information about use-cases, development timelines and the feature discovery in +the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +The intention for this feature is to allow those 3rd party tools to approve a merge request similarly to how users current do. + +NOTE: +The lack of an external approval does not block the merging of a merge request. + +You can modify external approval rules through the [REST API](../../../api/merge_request_approvals.md#external-project-level-mr-approvals). + ## Required Approvals **(PREMIUM)** > - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. @@ -53,7 +87,7 @@ be merged, and optionally which users should do the approving. Approvals can be If no approval rules are defined, any user can approve a merge request. However, the default minimum number of required approvers can still be set in the -[project settings for merge request approvals](#merge-request-approvals-project-settings). +[settings for merge request approvals](#approval-settings). You can opt to define one single rule to approve a merge request among the available rules or choose more than one with [multiple approval rules](#multiple-approval-rules). @@ -114,7 +148,7 @@ or higher [permissions](../../permissions.md). To enable this merge request approval rule: 1. Navigate to your project's **Settings > General** and expand - **Merge request approvals**. + **Merge request (MR) approvals**. 1. Locate **Any eligible user** and choose the number of approvals required.  @@ -145,7 +179,7 @@ To enable this access: 1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), based on the Reporter role. 1. Navigate to your project's **Settings > General**, and in the - **Merge request approvals** section, click **Expand**. + **Merge request (MR) approvals** section, click **Expand**. 1. Select **Add approval rule** or **Update approval rule**. 1. [Add the group](../../group/index.md#create-a-group) to the permission list. @@ -155,7 +189,7 @@ To enable this access: To add or edit the default merge request approval rule: -1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Navigate to your project's **Settings > General** and expand **Merge request (MR) approvals**. 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. @@ -235,14 +269,14 @@ reduces the number of approvals left for all rules that the approver belongs to. Approval rules are often only relevant to specific branches, like `master`. When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule) these can be scoped to all the protected branches at once by navigating to your project's -**Settings**, expanding **Merge request approvals**, and selecting **Any branch** from +**Settings**, expanding **Merge request (MR) approvals**, and selecting **Any branch** from the **Target branch** dropdown. Alternatively, you can select a very specific protected branch from the **Target branch** dropdown:  -To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). +To enable this configuration, see [Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). ### Adding or removing an approval @@ -278,10 +312,10 @@ else blocking it. Note that the merge request could still be blocked by other co such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). -### Merge request approvals project settings +### Approval settings -The project settings for Merge request approvals are found by going to -**Settings > General** and expanding **Merge request approvals**. +The settings for Merge Request Approvals are found by going to +**Settings > General** and expanding **Merge request (MR) approvals**. #### Prevent overriding default approvals @@ -289,7 +323,7 @@ Regardless of the approval rules you choose for your project, users can edit the request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). To prevent that from happening: -1. Uncheck the **Allow overrides to approval lists per merge request (MR).** checkbox. +1. Select the **Prevent users from modifying MR approval rules in merge requests.** checkbox. 1. Click **Save changes**. #### Resetting approvals on push @@ -314,7 +348,7 @@ from the UI. However, approvals are reset if the target branch is changed. By default, projects are configured to prevent merge requests from being approved by their own authors. To change this setting: -1. Go to your project's **Settings > General**, expand **Merge request approvals**. +1. Go to your project's **Settings > General**, expand **Merge request (MR) approvals**. 1. Uncheck the **Prevent MR approval by the author.** checkbox. 1. Click **Save changes**. diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 2d7ba853258..fc5cc4d958b 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -17,9 +17,9 @@ then it cannot be merged until its dependency is itself merged. NOTE: Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **FREE** or -**STARTER** project can be a dependency of a **PREMIUM** merge request, but not -vice-versa. +only enforced for the dependent merge request. A merge request in a **FREE** +project can be a dependency of a **PREMIUM** merge request, but not +the other way around. ## Use cases 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 406a79217d0..aba75403a2a 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 @@ -28,6 +28,39 @@ You can [search and filter the results](../../search/index.md#filtering-issue-an  +## Cached merge request count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +In a group, the sidebar displays the total count of open merge requests and this value is cached if higher +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +### Enable or disable cached merge request count **(FREE SELF)** + +Cached merge request count in the left sidebar is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it. + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_merge_requests_count) +``` + +To enable it: + +```ruby +Feature.enable(:cached_sidebar_merge_requests_count) +``` + ## Semi-linear history merge requests A merge commit is created for every merge, but the branch is only merged if @@ -112,10 +145,10 @@ To seamlessly navigate among commits in a merge request: 1. Select a commit to open it in the single-commit view. 1. Navigate through the commits by either: - - Selecting **Prev** and **Next** buttons on the top-right of the page. + - Selecting **Prev** and **Next** buttons below the tab buttons. - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - + ### Incrementally expand merge request diffs @@ -235,7 +268,7 @@ the **Merge** button is colored red. When a merge request is merged, you can see the post-merge pipeline status of the branch the merge request was merged into. For example, when a merge request -is merged into the `master` branch and then triggers a deployment to the staging +is merged into the [default branch](../repository/branches/default.md) and then triggers a deployment to the staging environment. Ongoing deployments are shown, and the state (deploying or deployed) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index f500c18a32e..4315e5a0305 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -7,8 +7,7 @@ type: reference, concepts # Squash and merge **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)to GitLab Free in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) to GitLab Free in 11.0. With squash and merge you can combine all your merge request's commits into one and retain a clean history. @@ -31,10 +30,7 @@ NOTE: The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. -The squashed commit's commit message is either: - -- Taken from the first multi-line commit message in the merge. -- The merge request's title if no multi-line commit message is found. +The squashed commit's default commit message is taken from the merge request title. NOTE: This only takes effect if there are at least 2 commits. As there is nothing to squash, the commit message does not change if there is only 1 commit. @@ -105,11 +101,11 @@ squashing can itself be considered equivalent to rebasing. ## Squash Commits Options > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. -> - It was deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) on GitLab 13.3. -> - It's enabled on GitLab.com. -> - It can be enabled per project. -> - It's recommended for production use. +> - Deployed behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. +> - Enabled on GitLab.com. +> - Can be enabled per project. +> - Recommended for production use. With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 02b557e22b9..147171e8488 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -21,14 +21,14 @@ MR is merged. ## How test coverage visualization works Collecting the coverage information is done via GitLab CI/CD's -[artifacts reports feature](../../../ci/pipelines/job_artifacts.md#artifactsreports). +[artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab will then take the coverage information in all the files and combine it together. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/pipelines/job_artifacts.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/README.md#artifactsreportscobertura). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -55,6 +55,11 @@ NOTE: A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds 100 nodes, there can be mismatches or no matches in the Merge Request diff view. +### Artifact expiration + +By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used +to draw the visualization on the Merge Request expires **one week** after creation. + ### Automatic class path correction > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. 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 index 9661a02a767..cc0be389891 100644 --- 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 @@ -19,7 +19,7 @@ or link to useful information directly from merge requests: | [Code Quality](code_quality.md) | 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. | -| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit 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. | +| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit 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. | diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 585d97c74c2..f7e8d3d140c 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,256 +1,8 @@ --- -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/#assignments -type: reference +redirect_to: '../../ci/README.md' --- -# New CI job permissions model +This document is deprecated. See the latest [GitLab CI/CD documentation](../../ci/README.md). -> 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). - -Jobs permissions should be tightly integrated with the permissions of a user -who is triggering a job. - -The reasons to do it like that are: - -- We already have a permissions system in place: group and project membership - of users. -- We already fully know who is triggering a job (using `git push`, using the - web UI, executing triggers). -- We already know what user is allowed to do. -- We use the user permissions for jobs that are triggered by the user. -- It opens a lot of possibilities to further enforce user permissions, like - allowing only specific users to access runners or use secure variables and - environments. -- It is simple and convenient that your job can access everything that you - as a user have access to. -- Short living unique tokens are now used, granting access for time of the job - and maximizing security. - -With the new behavior, any job that is triggered by the user, is also marked -with their read permissions. When a user does a `git push` or changes files through -the web UI, a new pipeline is usually created. This pipeline is marked -as created by the pusher (local push or via the UI) and any job created in this -pipeline has the read permissions of the pusher but not write permissions. - -This allows us to make it really easy to evaluate the access for all projects -that have [Git submodules](../../ci/git_submodules.md) or are using container images that the pusher -would have access too. **The permission is granted only for the time that the job -is running. The access is revoked after the job is finished.** - -## Types of users - -It is important to note that we have a few types of users: - -- **Administrators**: CI jobs created by Administrators don't have access - to all GitLab projects, but only to projects and container images of projects - that the administrator is a member of. That means that if a project is either - public or internal users have access anyway, but if a project is private, the - Administrator has to be a member of it in order to have access to it - via another project's job. - -- **External users**: CI jobs created by [external users](../permissions.md#external-users) have - access only to projects to which the user has at least Reporter access. This - rules out accessing all internal projects by default. - -This allows us to make the CI and permission system more trustworthy. -Let's consider the following scenario: - -1. You are an employee of a company. Your company has a number of internal tools - hosted in private repositories and you have multiple CI jobs that make use - of these repositories. - -1. You invite a new [external user](../permissions.md#external-users). CI jobs created by that user do not - have access to internal repositories, because the user also doesn't have the - access from within GitLab. You as an employee have to grant explicit access - for this user. This allows us to prevent from accidental data leakage. - -## Job token - -When a pipeline job is about to run, GitLab generates a unique token and injects it as the -[`CI_JOB_TOKEN` predefined variable](../../ci/variables/predefined_variables.md). -This token can authenticate [API requests](../../api/README.md) -from the job script (Runner) that needs to access the project's resources (for example, when -fetching a job artifact). - -Once the token is authenticated, GitLab identifies the user who triggered the job and uses this user -to authorize access to the resource. Therefore, this user must be assigned to -[a role that has the required privileges](../permissions.md). - -The job token has these limitations: - -- Not all APIs allow job tokens for authentication. See [this list](../../api/README.md#gitlab-ci-job-token) - for available endpoints. -- The token is valid only while the pipeline job runs. Once the job finishes, the token can't be - used for authentication. - -Although a job token is handy to quickly access a project's resources without any configuration, it -sometimes gives extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) -to redesign the feature for more strategic control of the access permissions. - -If you need your CI pipeline to push to the Package Registry, consider using [deploy tokens](deploy_tokens/index.md). - -We try to make sure that this token doesn't leak by: - -1. Securing all API endpoints to not expose the job token. -1. Masking the job token from job logs. -1. Granting permissions to the job token **only** when the job is running. - -However, this brings up a question about the runner's security. To make sure that -this token doesn't leak, you should also make sure that you configure -your runners in the most possible secure way, by avoiding the following: - -1. Any usage of Docker's `privileged` mode is risky if the machines are re-used. -1. Using the `shell` executor since jobs run on the same machine. - -By using an insecure GitLab Runner configuration, you allow the rogue developers -to steal the tokens of other jobs. - -## Before GitLab 8.12 - -In versions before GitLab 8.12, all CI jobs would use the runner's token -to checkout project sources. - -The project's runner token was a token that you could find under the -project's **Settings > Pipelines** and was limited to access only that -project. -It could be used for registering new specific runners assigned to the project -and to checkout project sources. -It could also be used with the GitLab Container Registry for that project, -allowing pulling and pushing Docker images from within the CI job. - -GitLab would create a special checkout URL like: - -```plaintext -https://gitlab-ci-token:<project-runners-token>/gitlab.com/gitlab-org/gitlab-foss.git -``` - -And then the users could also use it in their CI jobs all Docker related -commands to interact with GitLab Container Registry. For example: - -```shell -docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com -``` - -Using single token had multiple security implications: - -- The token would be readable to anyone who had Developer access to a project - that could run CI jobs, allowing the developer to register any specific - runner for that project. -- The token would allow to access only the project's sources, forbidding from - accessing any other projects. -- The token was not expiring and was multi-purpose: used for checking out sources, - for registering specific runners and for accessing a project's container - registry with read-write permissions. - -All the above led to a new permission model for jobs that was introduced -with GitLab 8.12. - -## Making use of the new CI job permissions model - -With the new job permissions model, there is now an easy way to access all -dependent source code in a project. That way, we can: - -1. Access a project's dependent repositories -1. Access a project's [Git submodules](../../ci/git_submodules.md) -1. Access private container images -1. Access project's and submodule LFS objects - -Below you can see the prerequisites needed to make use of the new permissions -model and how that works with Git submodules and private Docker images hosted on -the container registry. - -### Prerequisites to use the new permissions model - -With the new permissions model in place, there may be times that your job -fails. This is most likely because your project tries to access other project's -sources, and you don't have the appropriate permissions. In the job log look -for information about 403 or forbidden access messages. - -In short here's what you need to do should you encounter any issues. - -As an administrator: - -- **500 errors**: You need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at - least 0.8.2. This is done automatically for Omnibus installations, you need to - [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 - 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 - to clone all sources. - -As a user: - -- Make sure you are a member of the group or project you're trying to have - access to. As an Administrator, you can verify that by impersonating the user - and retry the failing job in order to verify that everything is correct. - -### Dependent repositories - -The [CI/CD variable](../../ci/variables/README.md#predefined-cicd-variables) `CI_JOB_TOKEN` can be used to -authenticate any clones of dependent repositories. For example: - -```shell -git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependentrepo>.git -``` - -It can also be used for system-wide authentication -(only do this in a Docker container, it overwrites `~/.netrc`): - -```shell -echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc -``` - -### Git submodules - -To properly configure submodules with GitLab CI/CD, read the -[Git submodules documentation](../../ci/git_submodules.md). - -### Container Registry - -With the update permission model we also extended the support for accessing -Container Registries for private projects. - -GitLab Runner versions prior to 1.8 don't incorporate the introduced changes -for permissions. This makes the `image:` directive not work with private -projects automatically and it needs to be configured manually on the GitLab Runner host -with a predefined account (for example administrator's personal account with -access token created explicitly for this purpose). This issue is resolved with -latest changes in GitLab Runner 1.8 which receives GitLab credentials with -build data. - -Starting from GitLab 8.12, if you have [2FA](../profile/account/two_factor_authentication.md) enabled in your account, you need -to pass a [personal access token](../profile/personal_access_tokens.md) instead of your password in order to -login to the Container Registry. - -Your jobs can access all container images that you would normally have access -to. The only implication is that you can push to the Container Registry of the -project for which the job is triggered. - -This is how an example usage can look like: - -```yaml -test: - script: - - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - - docker pull $CI_REGISTRY/group/other-project:latest - - docker run $CI_REGISTRY/group/other-project:latest -``` - -### Pipeline triggers - -Since 9.0 [pipeline triggers](../../ci/triggers/README.md#ci-job-token) do support the new permission model. -The new triggers do impersonate their associated user including their access -to projects and their project permissions. - -### API - -GitLab API can be used via `CI_JOB_TOKEN`, see [the relevant documentation](../../api/README.md#gitlab-ci-job-token). +<!-- This redirect file can be deleted after <2021-06-01>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index d9f57253396..f79c60a933a 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -36,7 +36,7 @@ with financial transactions. Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): <!-- vale gitlab.rulename = YES --> -> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ +> _We've since come to realize that HTTPS is important for almost all websites. It's important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn't want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We've also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ Therefore, the reason why certificates are so important is that they encrypt the connection between the **client** (you, me, your visitors) diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index eec8349abe6..36371573fd9 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create a Pages website from a new project template +# Create a Pages website from a template > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index dee021b8225..9eb80e3287c 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -81,7 +81,7 @@ To understand Pages domains clearly, read the examples below. ## URLs and base URLs NOTE: -The `baseurl` option might be called named differently in some static site generators. +The `baseurl` option might be named differently in some static site generators. Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 2a0e1207bf5..2ff91292b1b 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -46,10 +46,10 @@ To create a GitLab Pages website: | Document | Description | | -------- | ----------- | -| [Use a new project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a new project template. | +| [Create a `gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | | [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | | [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | -| [Create a `gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | +| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | To update a GitLab Pages website: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index fbc86abbe66..3c3de26d7dd 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -281,3 +281,19 @@ No, you don't. You can create your project first and access it under ## Known issues For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). + +## Troubleshooting + +### 404 error when accessing a GitLab Pages site URL + +This problem most likely results from a missing `index.html` file in the public directory. If after deploying a Pages site +a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name +such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`. + +The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) from the latest pipeline. + +Files listed under the public directory can be accessed through the Pages URL for the project. + +A 404 can also be related to incorrect permissions. If [Pages Access Control](pages_access_control.md) is enabled, and a user +navigates to the Pages URL and receives a 404 response, it is possible that the user does not have permission to view the site. +To fix this, verify that the user is a member of the project. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index aef96ff12c9..c66f9038ed2 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -26,7 +26,7 @@ By default, a protected branch does these things: - GitLab administrators are allowed to push to the protected branches. - Users with [Developer permissions](../permissions.md) are allowed to create a project in a group, but might not be allowed to initially - push to the [default branch](repository/branches/index.md#default-branch). + push to the [default branch](repository/branches/default.md). The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). @@ -177,13 +177,12 @@ Deleting a protected branch is allowed only by using the web interface; not from This means that you can't accidentally delete a protected branch from your command line or a Git client application. -## Allow force push on protected branches **(FREE SELF)** +## Allow force push on protected branches -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-allow-force-push-on-protected-branches). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-allow-force-push-on-protected-branches). WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -253,8 +252,8 @@ for details about the pipelines security model. ## Enable or disable allow force push on protected branches **(FREE SELF)** -Allow force push on protected branches is under development and not ready for -production use. It is deployed behind a feature flag that is **disabled by default**. +Allow force push on protected branches is ready for +production use. It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 3ea0bb62c0b..260f355349d 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -23,9 +23,7 @@ anyone without Maintainer [permissions](../permissions.md) is prevented from cre To protect a tag, you need to have at least Maintainer [permissions](../permissions.md). -1. Navigate to the project's **Settings > Repository**: - -  +1. Go to the project's **Settings > Repository**. 1. From the **Tag** dropdown menu, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`: diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index c557c7718c9..3c5cc668986 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -68,6 +68,8 @@ time as pushing changes: | `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 is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | +| `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [12.9](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/XXXXX) | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [12.9](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/XXXXX) | If you use a push option that requires text with spaces in it, you need to enclose it in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 284deabb33c..e1815785fb5 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -68,7 +68,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | -| `/estimate <<W>w <DD>d <hh>h <mm>m>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | +| `/estimate <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). | | `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants`. | | `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | | `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | @@ -95,8 +95,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | 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>)>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | 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> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | | `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | | `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | diff --git a/doc/user/project/releases/img/deploy_freeze_v13_10.png b/doc/user/project/releases/img/deploy_freeze_v13_10.png Binary files differnew file mode 100644 index 00000000000..5c4b2d983dd --- /dev/null +++ b/doc/user/project/releases/img/deploy_freeze_v13_10.png diff --git a/doc/user/project/releases/img/deploy_freeze_v13_2.png b/doc/user/project/releases/img/deploy_freeze_v13_2.png Binary files differdeleted file mode 100644 index 27d3a6044a1..00000000000 --- a/doc/user/project/releases/img/deploy_freeze_v13_2.png +++ /dev/null diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 7348e17a017..06ad71713d7 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Releases +# Releases **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. @@ -217,11 +217,11 @@ To set a deploy freeze window in the UI, complete these steps: 1. Click **Add deploy freeze** to open the deploy freeze modal. 1. Enter the start time, end time, and timezone of the desired deploy freeze period. 1. Click **Add deploy freeze** in the modal. - - +1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**). +  WARNING: -To edit or delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). +To delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the complete overlapping period. @@ -416,14 +416,14 @@ Evidence collection snapshots are visible on the Releases page, along with the t > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. -When you create a release, if [job artifacts](../../../ci/pipelines/job_artifacts.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. +When you create a release, if [job artifacts](../../../ci/yaml/README.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. Although job artifacts normally expire, artifacts included in release evidence do not expire. To enable job artifact collection you need to specify both: 1. [`artifacts:paths`](../../../ci/yaml/README.md#artifactspaths) -1. [`artifacts:reports`](../../../ci/pipelines/job_artifacts.md#artifactsreports) +1. [`artifacts:reports`](../../../ci/yaml/README.md#artifactsreports) ```yaml ruby: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md new file mode 100644 index 00000000000..1363d883e76 --- /dev/null +++ b/doc/user/project/repository/branches/default.md @@ -0,0 +1,180 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: concepts, howto +--- + +# Default branch + +When you create a new [project](../../index.md), GitLab creates a default branch +in the repository. A default branch has special configuration options not shared +by other branches: + +- It's [initially protected](../../protected_branches.md#protected-branches) against + accidental deletion and forced pushes. +- When a merge request uses an + [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically) + to close an issue, the work is merged into this branch. + +The name of your [new project's](../../index.md) default branch depends on any +instance-level or group-level configuration changes made by your GitLab administrator. +GitLab checks first for specific customizations, then checks at a broader level, +using the GitLab default only if no customizations are set: + +1. A [project-specific](#change-the-default-branch-name-for-a-project) custom default branch name. +1. A [subgroup-level](#group-level-custom-initial-branch-name) custom default branch name. +1. A [group-level](#group-level-custom-initial-branch-name) custom default branch name. +1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. **(FREE SELF)** +1. If no custom default branch name is set at any level, GitLab defaults to: + - `main`: Projects created with GitLab 14.0 or later. + - `master`: Projects created before GitLab 14.0. + +In the GitLab UI, you can change the defaults at any level. GitLab also provides +the [Git commands you need](#update-the-default-branch-name-in-your-repository) to update your copy of the repository. + +## Change the default branch name for a project + +To update the default branch name for an individual [project](../../index.md): + +1. Sign in to GitLab as a user with [Administrator](../../../permissions.md) permissions. +1. In the left navigation menu, go to **Settings > Repository**. +1. Expand **Default branch**, and select a new default branch. +1. (Optional) Select the **Auto-close referenced issues on default branch** check box to close + issues when a merge request + [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). +1. Select **Save changes**. + +API users can also use the `default_branch` attribute of the +[Projects API](../../../../api/projects.md) when creating or editing a project. + +## Change the default branch name for an instance or group + +GitLab administrators can configure a new default branch name at the +[instance level](#instance-level-custom-initial-branch-name) or +[group level](#group-level-custom-initial-branch-name). + +### Instance-level custom initial branch name **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. +> - It's deployed behind a feature flag, enabled by default. +> - It cannot be enabled or disabled per-project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). + +GitLab [administrators](../../../permissions.md) of self-managed instances can +customize the initial branch for projects hosted on that instance. Individual +groups and subgroups can override this instance-wide setting for their projects. + +1. Go to **Admin Area > Settings > Repository**. +1. Expand **Default initial branch name**. +1. Change the default initial branch to a custom name of your choice. +1. Select **Save changes**. + +Projects created on this instance after you change the setting use the +custom branch name, unless a group-level or subgroup-level configuration +overrides it. + +#### Enable or disable custom initial branch name **(FREE SELF)** + +Setting the default initial branch name is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can opt to disable it for your instance. + +To disable it: + +```ruby +Feature.disable(:global_default_branch_name) +``` + +To enable it: + +```ruby +Feature.enable(:global_default_branch_name) +``` + +### Group-level custom initial branch name **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. + +Administrators of groups and subgroups can configure the default branch name for a group: + +1. Go to the group **Settings > Repository**. +1. Expand **Default initial branch name**. +1. Change the default initial branch to a custom name of your choice. +1. Select **Save changes**. + +Projects created in this group after you change the setting use the custom branch name, +unless a subgroup configuration overrides it. + +## Update the default branch name in your repository + +WARNING: +Changing the name of your default branch can potentially break tests, +CI/CD configuration, services, helper utilities, and any integrations your repository +uses. Before you change this branch name, consult with your project owners and maintainers. +Ensure they understand the scope of this change includes references to the old +branch name in related code and scripts. + +When changing the default branch name for an existing repository, you should preserve +the history of your default branch by renaming it, instead of deleting it. This example +renames a Git repository's (`example`) default branch. + +1. On your local command line, navigate to your `example` repository, and ensure + you're on the default branch: + + ```plaintext + cd example + git checkout master + ``` + +1. Rename the existing default branch to the new name (`main`). The argument `-m` + transfers all commit history to the new branch: + + ```plaintext + git branch -m master main + ``` + +1. Push the newly created `main` branch upstream, and set your local branch to track + the remote branch with the same name: + + ```plaintext + git push -u origin main + ``` + +1. If you plan to remove the old default branch, update `HEAD` to point to your new default branch, `main`: + + ```plaintext + git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main + ``` + +1. Sign in to GitLab as an [administrator](../../../permissions.md) and follow + the instructions to + [change the default branch for this project](#change-the-default-branch-name-for-a-project). + Select `main` as your new default branch. +1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). +1. (Optional) If you want to delete the old default branch: + 1. Verify that nothing is pointing to it. + 1. Delete the branch on the remote: + + ```plaintext + git push origin --delete master + ``` + + You can delete the branch at a later time, after you confirm the new default branch is working as expected. + +1. Notify your project contributors of this change, because they must also take some steps: + + - Contributors should pull the new default branch to their local copy of the repository. + - Contributors with open merge requests that target the old default branch should manually + re-point the merge requests to use `main` instead. +1. In your repository, update any references to the old branch name in your code. +1. Update references to the old branch name in related code and scripts that reside outside + your repository, such as helper utilities and integrations. + +## Resources + +- [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) + on the Git mailing list +- [March 2021 blog post: The new Git default branch name](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/) diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png Binary files differindex da7d5268b3b..fdda3858c3b 100644 --- a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png +++ b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index d049b2108ee..f2562ef89e3 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -19,12 +19,14 @@ After pushing your changes to a new branch, you can: - [Discuss](../../../discussions/index.md) your implementation with your team - Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). -With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request -[approval](../../merge_requests/merge_request_approvals.md) from your managers. +You can also request [approval](../../merge_requests/merge_request_approvals.md) +from your managers. For more information on managing branches using the GitLab UI, see: -- [Default branches](#default-branch) +- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a + default branch for the repository. You can change this setting at the project, + subgroup, group, or instance level. - [Create a branch](../web_editor.md#create-a-new-branch) - [Protected branches](../../protected_branches.md#protected-branches) - [Delete merged branches](#delete-merged-branches) @@ -41,55 +43,6 @@ See also: - [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation. - [Getting started with Git](../../../../topics/git/index.md) and GitLab. -## Default branch - -When you create a new [project](../../index.md), GitLab sets `master` as the default -branch of the repository. You can choose another branch to be your project's -default under your project's **Settings > Repository**. - -When closing issues directly from merge requests through the [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically), -the target is the project's **default branch**. - -The default branch is also initially [protected](../../protected_branches.md#protected-branches) -against accidental deletion and forced pushes. - -### Custom initial branch name **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It cannot be enabled or disabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(FREE SELF)** - -By default, when you create a new project in GitLab, the initial branch is called `master`. -For self-managed instances, a GitLab administrator can customize the initial branch name to something -else. This way, every new project created from then on starts from the custom branch name rather than `master`. To do so: - -1. Go to the **Admin Area > Settings > Repository** and expand **Default initial - branch name**. -1. Change the default initial branch to a custom name of your choice. -1. **Save Changes**. - -#### Enable or disable custom initial branch name **(FREE SELF)** - -Setting the default initial branch name is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:global_default_branch_name) -``` - -To enable it: - -```ruby -Feature.enable(:global_default_branch_name) -``` - ## Compare To compare branches in a repository: diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 3af7a5045c4..42b82f2c360 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -7,17 +7,13 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' # File finder **(FREE)** -> [Introduced](https://github.com/gitlabhq/gitlabhq/pull/9889) in GitLab 8.4. - The file finder feature allows you to search for a file in a repository using the -GitLab UI. - -You can find the **Find File** button when in the **Files** section of a -project. +GitLab UI. To use it: - +1. Go to your project's **Repository > Files**. +1. In the upper right corner, select **Find File**. -If you prefer to keep their fingers on the keyboard, use the +If you prefer to keep your fingers on the keyboard, use the [shortcut button](../../shortcuts.md), which you can invoke from anywhere in a project. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index c8922890deb..33ab5f6580d 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -18,26 +18,37 @@ submit them through a merge request to the repository you don't have access to. ## Creating a fork -Forking a project is, in most cases, a two-step process. +To fork an existing project in GitLab: -1. On the project's home page, in the top right, click the **Fork** button. +1. On the project's home page, in the top right, click **{fork}** **Fork**. -  +  -1. Click a namespace to fork to. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown. +1. Select the project to fork to: - NOTE: - The project path must be unique within the namespace. + - *(Recommended method)* Below **Select a namespace to fork the project**, identify + the project you want to fork to, and click **Select**. Only namespaces you have + Developer and higher [permissions](../../permissions.md) for are shown. + +  -  + - *(Experimental method)* If your GitLab administrator has + [enabled the experimental fork project form](#enable-or-disable-the-fork-project-form), read + [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). + Only namespaces you have Developer and higher + [permissions](../../permissions.md) for are shown. + + NOTE: + The project path must be unique in the namespace. -The fork is created. The permissions you have in the namespace are your permissions in the fork. +GitLab creates your fork, and redirects you to the project page for your new fork. +The permissions you have in the namespace are your permissions in the fork. WARNING: When a public project with the repository feature set to **Members Only** is forked, the repository is public in the fork. The owner -of the fork must manually change the visibility. This is being -fixed in [#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662). +of the fork must manually change the visibility. Issue +[#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662) exists for this issue. ## Repository mirroring @@ -71,3 +82,44 @@ changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#removing-a-fork-relationship). + +## Create a fork with the fork project form **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-fork-project-form). **(FREE SELF)** + +This experimental version of the fork project form is available only if your GitLab +administrator has [enabled it](#enable-or-disable-the-fork-project-form): + + + +To use it, follow the instructions at [Creating a fork](#creating-a-fork) and provide: + +- The project name. +- The project URL. +- The project slug. +- *(Optional)* The project description. +- The visibility level for your fork. + +### Enable or disable the fork project form **(FREE SELF)** + +The new [fork project form](#create-a-fork-with-the-fork-project-form) 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. + +To enable it: + +```ruby +Feature.enable(:fork_project_form) +``` + +To disable it: + +```ruby +Feature.disable(:fork_project_form) +``` diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 0f49932d0c6..198993e21f3 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -8,17 +8,15 @@ description: "Documentation on Git file blame." # Git file blame **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5. - [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and -commit hash. - -You can find the **Blame** button with each file in a project. +commit hash. To view it for a file: - +1. Go to your project's **Repository > Files**. +1. Select the file you want to review. +1. In the upper right corner, select **Blame**. -When you select the **Blame** button, this information is shown: +When you select **Blame**, this information is displayed:  diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 1b30a0b0f5f..356f02a4902 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -8,16 +8,13 @@ description: "Documentation on Git file history." # Git file history **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/blob/9ba1224867665844b117fa037e1465bb706b3685/app/controllers/commits_controller.rb) in GitLab 0.8.0 - Git file History provides information about the commit history associated -with a file. - -You can find the **History** button with each file in a project. +with a file. To use it: - +1. Go to your project's **Repository > Files**. +1. In the upper right corner, select **History**. -When you select the **History** button, this information displays: +When you select **History**, this information is displayed:  diff --git a/doc/user/project/repository/img/contributors_graph.png b/doc/user/project/repository/img/contributors_graph.png Binary files differindex c31da7aa1ff..83fdf1fc41f 100644 --- a/doc/user/project/repository/img/contributors_graph.png +++ b/doc/user/project/repository/img/contributors_graph.png diff --git a/doc/user/project/repository/img/download_source_code.png b/doc/user/project/repository/img/download_source_code.png Binary files differindex 56808061980..8d62d19b291 100644 --- a/doc/user/project/repository/img/download_source_code.png +++ b/doc/user/project/repository/img/download_source_code.png diff --git a/doc/user/project/repository/img/file_blame_button_v12_6.png b/doc/user/project/repository/img/file_blame_button_v12_6.png Binary files differdeleted file mode 100644 index e7aa0d1ea3f..00000000000 --- a/doc/user/project/repository/img/file_blame_button_v12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_finder_find_button_v12_10.png b/doc/user/project/repository/img/file_finder_find_button_v12_10.png Binary files differdeleted file mode 100644 index 51545f63fde..00000000000 --- a/doc/user/project/repository/img/file_finder_find_button_v12_10.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_history_button_v12_6.png b/doc/user/project/repository/img/file_history_button_v12_6.png Binary files differdeleted file mode 100644 index e7aa0d1ea3f..00000000000 --- a/doc/user/project/repository/img/file_history_button_v12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/fork_form_v13_10.png b/doc/user/project/repository/img/fork_form_v13_10.png Binary files differnew file mode 100644 index 00000000000..00c2f89a844 --- /dev/null +++ b/doc/user/project/repository/img/fork_form_v13_10.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png Binary files differnew file mode 100644 index 00000000000..74f65cb663d --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png Binary files differindex 4843cc671ae..f48cf176ba1 100644 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png diff --git a/doc/user/project/repository/img/forking_workflow_fork_button.png b/doc/user/project/repository/img/forking_workflow_fork_button.png Binary files differdeleted file mode 100644 index eea62892232..00000000000 --- a/doc/user/project/repository/img/forking_workflow_fork_button.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png b/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png Binary files differnew file mode 100644 index 00000000000..376beb803a7 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png diff --git a/doc/user/project/repository/img/repo_graph.png b/doc/user/project/repository/img/repo_graph.png Binary files differindex 28da8ad9589..fcccedbc436 100644 --- a/doc/user/project/repository/img/repo_graph.png +++ b/doc/user/project/repository/img/repo_graph.png diff --git a/doc/user/project/repository/img/web_editor_line_link_v13_10.png b/doc/user/project/repository/img/web_editor_line_link_v13_10.png Binary files differnew file mode 100644 index 00000000000..36347afcbe8 --- /dev/null +++ b/doc/user/project/repository/img/web_editor_line_link_v13_10.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index b9145364e3b..70c5ef63dd4 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -257,7 +257,7 @@ prompted to open XCode. ### Clone and open in Visual Studio Code -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. All projects can be cloned into Visual Studio Code. To do that: diff --git a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png Binary files differindex 52c5c5aea32..a12fabcdd2a 100644 --- a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png +++ b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index e4a3e6d6ef1..4b649bab4d9 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -13,7 +13,7 @@ interactive computing in many fields and contain a complete record of the user's sessions and include code, narrative text, equations, and rich output. When added to a repository, Jupyter Notebooks with a `.ipynb` extension are -rendered to HTML when viewed. +rendered to HTML when viewed:  @@ -26,4 +26,4 @@ You can deploy [Jupyter Hub as a GitLab managed app](../../../clusters/applicati ## Jupyter Git integration -Find out how to [leverage JupyterLab’s Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). +Find out how to [leverage JupyterLab's Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). 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 7847930366a..323a2efce76 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 @@ -143,10 +143,10 @@ To clean up a repository: 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. - If your `commit-map` file is larger than 10MB, the file can be split and uploaded piece by piece: + If your `commit-map` file is larger than about 250KB or 3000 lines, the file can be split and uploaded piece by piece: ```shell - split -l 100000 filter-repo/commit-map filter-repo/commit-map- + split -l 3000 filter-repo/commit-map filter-repo/commit-map- ``` 1. Click **Start cleanup**. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index efa35c1ceac..b6bde46b26a 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -56,6 +56,24 @@ NOTE: The **Set up CI/CD** button does not appear on an empty repository. For the button to display, add a file to your repository. +## Highlight lines + +Web Editor enables you to highlight a single line by adding specially formatted +hash information to the URL's file path segment. For example, the file path segment +`MY_FILE.js#L3` instructs the Web Editor to highlight line 3. + +The Web Editor also enables you to highlight multiple lines using a similar pattern. In +this case, the file path segment `MY_FILE.js#L3-10` instructs the Web Editor to +highlight lines 3 to 10 of the file. + +You don't need to construct these lines manually. Instead, you can: + +1. Hover over the number of a line you want to be highlighted when sharing. +1. Right-click the number with your mouse. +1. Click **Copy Link Address** in the context menu. + +  + ## Upload a file The ability to create a file is great when the content is text. However, this diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index bd37acafd22..d7fbff23e5e 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -122,8 +122,7 @@ You can also sort the requirements list by: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. -GitLab supports [requirements test -reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements) now. +GitLab supports [requirements test reports](../../../ci/yaml/README.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing requirements as Satisfied (you may manually satisfy a requirement in the edit form [edit a requirement](#edit-a-requirement)). diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 383b4df9612..dd646a54b43 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -160,7 +160,7 @@ To edit the custom email display name: 1. Enter a new name in **Email display name**. 1. Select **Save Changes**. -### Using custom email address +### Using custom email address **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab Premium 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. @@ -183,7 +183,7 @@ always use separate mailboxes. This is important, because emails picked from `service_desk_email` mailbox are processed by a different worker and it would not recognize `incoming_email` emails. -To configure a custom email address for Service Desk, add the following snippets to your configuration file: +To configure a custom email address for Service Desk with IMAP, add the following snippets to your configuration file: - Example for installations from source: @@ -236,6 +236,38 @@ As a result, a new Service Desk issue is created from this email in the `mygroup The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). +#### Microsoft Graph + +> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) + +Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft +Graph API instead of IMAP. Follow the [documentation in the incoming e-mail section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). + +- Example for Omnibus GitLab installations: + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + + gitlab_rails['service_desk_inbox_method'] = 'microsoft_graph' + + gitlab_rails['service_desk_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details. + ## Using Service Desk You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). diff --git a/doc/user/project/settings/img/general_settings.png b/doc/user/project/settings/img/general_settings.png Binary files differdeleted file mode 100644 index f88a158d2be..00000000000 --- a/doc/user/project/settings/img/general_settings.png +++ /dev/null diff --git a/doc/user/project/settings/img/general_settings_v13_11.png b/doc/user/project/settings/img/general_settings_v13_11.png Binary files differnew file mode 100644 index 00000000000..9da5acdf82e --- /dev/null +++ b/doc/user/project/settings/img/general_settings_v13_11.png diff --git a/doc/user/project/settings/img/merge_requests_settings.png b/doc/user/project/settings/img/merge_requests_settings.png Binary files differdeleted file mode 100644 index b1f2dfa7376..00000000000 --- a/doc/user/project/settings/img/merge_requests_settings.png +++ /dev/null diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 7b5a0cbb377..6fa1b0aa368 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -39,8 +39,8 @@ Note the following: The Importing GitLab version must be greater than or equal to the Exporting GitLab version. - Imports will fail unless the import and export GitLab instances are compatible as described in the [Version history](#version-history). -- Exports are stored in a temporary [shared directory](../../../development/shared_files.md) - and are deleted every 24 hours by a specific worker. +- Exports are generated in your configured `shared_path`, a temporary [shared directory](../../../development/shared_files.md) + and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. - Group members are exported as project members, as long as the user has maintainer or administrator access to the group where the exported project lives. - Project members with owner access will be imported as maintainers. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 785618a862a..6d37d26f6e8 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -9,10 +9,15 @@ type: reference, index, howto NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) -to access a project settings. +to access project settings. -You can adjust your [project](../index.md) settings by navigating -to your project's homepage and clicking **Settings**. +The **Settings** page in GitLab provides a centralized home for your +[project](../index.md) configuration options. To access it, go to your project's homepage +and, in the left navigation menu, clicking **Settings**. To reduce complexity, settings are +grouped by topic into sections. To display all settings in a section, click **Expand**. + +In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epics/4842), +GitLab displays a search box to help you find the settings you want to view. ## General settings @@ -21,9 +26,9 @@ functionality of a project. ### General project settings -Adjust your project's name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and topics: +Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics: - + The project description also partially supports [standard Markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. @@ -43,11 +48,10 @@ Compliance framework labels do not affect your project settings. #### Custom compliance frameworks > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It can be enabled or disabled for a single group -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-compliance-frameworks). **(PREMIUM)** +> - [Deployed behind a feature flag](../../feature_flags.md). +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.11. +> - Enabled on GitLab.com. +> - Recommended for production use. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -61,6 +65,71 @@ can now create their own. New compliance framework labels can be created and updated using GraphQL. +#### Compliance pipeline configuration **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9. +> - [Deployed behind a feature flag](../../feature_flags.md). +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. +> - Enabled on GitLab.com. +> - Recommended for production use. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +Group owners can use the compliance pipeline configuration to define compliance requirements +such as scans or tests, and enforce them in individual projects. + +The [custom compliance framework](#custom-compliance-frameworks) feature allows group owners to specify the location +of a compliance pipeline configuration stored and managed in a dedicated project, distinct from a developer's project. + +When you set up the compliance pipeline configuration field, use the +`file@group/project` format. For example, you can configure +`.compliance-gitlab-ci.yml@compliance-group/compliance-project`. +This field is inherited by projects where the compliance framework label is applied. The result +forces the project to run the compliance configurations. + +When a project with a custom label executes a pipeline, it begins by evaluating the compliance pipeline configuration. +The custom pipeline configuration can then execute any included individual project configuration. + +The user running the pipeline in the project should at least have Reporter access to the compliance project. + +Example `.compliance-gitlab-ci.yml` + +```yaml +stages: # Allows compliance team to control the ordering and interweaving of stages/jobs +- pre-compliance +- build +- test +- pre-deploy-compliance +- deploy +- post-compliance + +variables: # can be overriden by a developer's local .gitlab-ci.yml + FOO: sast + +sast: # none of these attributes can be overriden by a developer's local .gitlab-ci.yml + variables: + FOO: sast + stage: pre-compliance + script: + - echo "running $FOO" + +sanity check: + stage: pre-deploy-compliance + script: + - echo "running $FOO" + + +audit trail: + stage: post-compliance + script: + - echo "running $FOO" + +include: # Execute individual project's configuration + project: '$CI_PROJECT_PATH' + file: '$CI_PROJECT_CONFIG_PATH' +``` + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -145,8 +214,7 @@ Set up your project's merge request settings: - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch) - Configure [suggested changes commit messages](../../discussions/index.md#configure-the-commit-message-for-applied-suggestions) - - +- Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cda39508835..d37e6144ab3 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -78,3 +78,9 @@ 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 token creation + +You may enable or disable project access token creation for all projects in a group in **Group > Settings > General > Permissions, LFS, 2FA > Allow project access token creation**. +Even when creation is disabled, you can still use and revoke existing project access tokens. +This setting is available only on top-level groups. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index d1e9fe155b4..78e7ded9784 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -30,11 +30,9 @@ below. ## How to enter data -Time Tracking uses two [quick actions](quick_actions.md) -that GitLab introduced with this new feature: `/spend` and `/estimate`. +Time Tracking uses two [quick actions](quick_actions.md): `/spend` and `/estimate`. -Quick actions can be used in the body of an issue or a merge request, but also -in a comment in both an issue or a merge request. +If you use either quick action more than once in a single comment, only the last occurrence is applied. Below is an example of how you can use those new quick actions inside a comment. @@ -46,9 +44,9 @@ with [Reporter and higher permission levels](../permissions.md). ### Estimates To enter an estimate, write `/estimate`, followed by the time. For example, if -you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write -`/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of -this help page. +you need to enter an estimate of 1 month, 2 weeks, 3 days, 4 hours and 5 minutes, +write `/estimate 1mo 2w 3d 4h 5m`. +Check the [time units you can use](#configuration). Every time you enter a new time estimate, any previous time estimates are overridden by this new value. There should only be one valid estimate in an @@ -58,7 +56,9 @@ To remove an estimation entirely, use `/remove_estimate`. ### Time spent -To enter a time spent, use `/spend 3d 5h 10m`. +To enter time spent, write `/spend`, followed by the time. For example, if you need +to log 1 month, 2 weeks, 3 days, 4 hours and 5 minutes, you would write `/spend 1mo 2w 3d 4h 5m`. +Time units that we support are listed at the bottom of this help page. Every new time spent entry is added to the current total time spent for the issue or the merge request. @@ -68,6 +68,11 @@ days from the total time spent. You can't go below 0 minutes of time spent, so GitLab automatically resets the time spent if you remove a larger amount of time compared to the time that was entered already. +You can log time in the past by providing a date after the time. +For example, if you want to log 1 hour of time spent on the 31 January 2021, +you would write `/spend 1h 2021-01-31`. If you supply a date in the future, the +command fails and no time is logged. + To remove all the time spent at once, use `/remove_time_spent`. ## Configuration diff --git a/doc/user/project/web_ide/img/commit_changes_v12_9.png b/doc/user/project/web_ide/img/commit_changes_v12_9.png Binary files differdeleted file mode 100644 index 9a8bb214b3d..00000000000 --- a/doc/user/project/web_ide/img/commit_changes_v12_9.png +++ /dev/null diff --git a/doc/user/project/web_ide/img/commit_changes_v13_11.png b/doc/user/project/web_ide/img/commit_changes_v13_11.png Binary files differnew file mode 100644 index 00000000000..6cd270a6112 --- /dev/null +++ b/doc/user/project/web_ide/img/commit_changes_v13_11.png diff --git a/doc/user/project/web_ide/img/live_preview_v13_0.png b/doc/user/project/web_ide/img/live_preview_v13_0.png Binary files differindex bd04d3d644b..f701e137a6b 100644 --- a/doc/user/project/web_ide/img/live_preview_v13_0.png +++ b/doc/user/project/web_ide/img/live_preview_v13_0.png diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 57b79875909..73aed1244db 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -66,9 +66,6 @@ Monaco uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html If you are missing Syntax Highlighting support for any language, we prepared a short guide on how to [add support for a missing language Syntax Highlighting.](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/ide/lib/languages/README.md) -NOTE: -Single file editing is based on the [Ace Editor](https://ace.c9.io). - ### Themes > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab 13.0. @@ -82,6 +79,12 @@ You can pick a theme from your [profile preferences](../../profile/preferences.m |-------------------------------------------------------------|-----------------------------------------| |  |  | +## Highlight lines + +WebIDE is built with the [Web Editor](../repository/web_editor.md). This enables WebIDE to share the +same core features for highlighting and linking to particular lines in the edited files +[described for the Web Editor](../repository/web_editor.md#highlight-lines). + ## Schema based validation > - Support for validation based on predefined schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. @@ -187,7 +190,7 @@ To discard a change in a particular file, click the **Discard changes** button o file in the changes tab. To discard all the changes, click the trash icon on the top-right corner of the changes sidebar. - + ## Reviewing changes @@ -341,7 +344,7 @@ terminal: # This can be any image that has the necessary runtime environment for your project. image: node:10-alpine before_script: - - apt-get update + - apk update script: sleep 60 variables: RAILS_ENV: "test" diff --git a/doc/user/project/wiki/img/wiki_create_home_page.png b/doc/user/project/wiki/img/wiki_create_home_page.png Binary files differdeleted file mode 100644 index 658af33d76e..00000000000 --- a/doc/user/project/wiki/img/wiki_create_home_page.png +++ /dev/null diff --git a/doc/user/project/wiki/img/wiki_create_new_page.png b/doc/user/project/wiki/img/wiki_create_new_page.png Binary files differdeleted file mode 100644 index 8954ec0d3a8..00000000000 --- a/doc/user/project/wiki/img/wiki_create_new_page.png +++ /dev/null diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index eb8270b8740..a69141ac04d 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -7,68 +7,76 @@ type: reference, how-to # Wiki **(FREE)** -A separate system for documentation called Wiki, is built right into each -GitLab project. It is enabled by default on all new projects and you can find -it under **Wiki** in your project. +If you don't want to keep your documentation in your repository, but you do want +to keep it in the same project as your code, you can use the wiki GitLab provides +in each GitLab project. Every wiki is a separate Git repository, so you can create +wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). + +To access the wiki for a project or group, go to the page for your project or group +and, in the left sidebar, select **Wiki**. If **Wiki** is not listed in the +left sidebar, a project administrator has [disabled it](#enable-or-disable-a-project-wiki). + +GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. +Wiki pages written in Markdown support all [Markdown features](../../markdown.md), +and also provide some [wiki-specific behavior](../../markdown.md#wiki-specific-markdown) +for links. + +In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/17673/), +wiki pages display a sidebar, which you [can customize](#customize-sidebar). This +sidebar contains a partial list of pages in the wiki, displayed as a nested tree, +with sibling pages listed in alphabetical order. To view a list of all pages, select +**View All Pages** in the sidebar: -Wikis are very convenient if you don't want to keep your documentation in your -repository, but you do want to keep it in the same project where your code -resides. - -You can create Wiki pages in the web interface or -[locally using Git](#adding-and-editing-wiki-pages-locally) since every Wiki is -a separate Git repository. - -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, -**group wikis** became available. Their usage is similar to project wikis, with a few [limitations](../../group/index.md#group-wikis). - -## First time creating the Home page - -The first time you visit a Wiki, you are directed to create the Home page. -The Home page is necessary to be created because it serves as the landing page -when viewing a Wiki. Complete the **Content** section, and then select -**Create page**. You can always edit it later, so go ahead and write a welcome -message. - - - -## Creating a new wiki page - -NOTE: -Requires Developer [permissions](../../permissions.md). - -Create a new page by selecting the **New page** button that can be found -in all wiki pages. - -Enter a title for your new wiki page. - -You can specify a full path for the wiki page by using '/' in the -title to indicate subdirectories. Any missing directories are created -automatically. For example, a title of `docs/my-page` creates a wiki -page with a path `/wikis/docs/my-page`. - -After you enter the page name, it's time to fill in its content. GitLab wikis -support Markdown, RDoc, AsciiDoc, and Org. For Markdown based pages, all the -[Markdown features](../../markdown.md) are supported and for links there is -some [wiki specific](../../markdown.md#wiki-specific-markdown) behavior. - -In the web interface the commit message is optional, but the GitLab Wiki is -based on Git and needs a commit message, so one is created for you if you -don't enter one. - -When you're ready, select **Create page** and the new page is created. - - - -### Attachment storage + -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. +## Create the wiki home page + +When a wiki is created, it is empty. On your first visit, create the landing page +users see when viewing the wiki: + +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, then **Create your first page**. +1. Select a **Format** for styling your text. +1. Add a welcome message in the **Content** section. You can always edit it later. +1. Add a **Commit message**. Git requires a commit message, so GitLab creates one + if you don't enter one yourself. +1. Select **Create page**. + +## Create a new wiki page + +Users with Developer [permissions](../../permissions.md) can create new wiki pages: + +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**. +1. Select **New page** on this page, or any other wiki page. +1. Select a content format. +1. Add a title for your new page. Page titles use + [special characters](#special-characters-in-page-titles) for subdirectories and formatting, + and have [length restrictions](#length-restrictions-for-file-and-directory-names). +1. Add content to your wiki page. +1. (Optional) Attach a file, and GitLab stores it according to your installed version of GitLab: + - *Files added in [GitLab 11.3 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475):* + Files are stored in the wiki's Git repository. + - *Files added GitLab 11.2 and earlier:* Files are stored in GitLab itself. To add + the file to the wiki's Git repository, you must re-upload the file. +1. Add a **Commit message**. Git requires a commit message, so GitLab creates one + if you don't enter one yourself. +1. Select **Create page**. + +### Create or edit wiki pages locally + +Wikis are based on Git repositories, so you can clone them locally and edit +them like you would do with every other Git repository. To clone a wiki repository +locally, select **Clone repository** from the right-hand sidebar of any wiki page, +and follow the on-screen instructions. + +Files you add to your wiki locally must use one of the following +supported extensions, depending on the markup language you wish to use. +Files with unsupported extensions don't display when pushed to GitLab: -Any file uploaded to the wiki with the GitLab -interface is stored in the wiki Git repository, and is available -if you clone the wiki repository locally. All uploaded files prior to GitLab -11.3 are stored in GitLab itself. If you want them to be part of the wiki's Git -repository, you must upload them again. +- Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. +- AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. +- Other markup extensions: `.textile`, `.rdoc`, `.org`, `.creole`, `.wiki`, `.mediawiki`, `.rst`. ### Special characters in page titles @@ -76,141 +84,118 @@ Wiki pages are stored as files in a Git repository, so certain characters have a - Spaces are converted into hyphens when storing a page. - Hyphens (`-`) are converted back into spaces when displaying a page. -- Slashes (`/`) can't be used, because they're used as path separator. +- Slashes (`/`) are used as path separators, and can't be displayed in titles. If you + create a title containing `/` characters, GitLab creates all the subdirectories + needed to build that path. For example, a title of `docs/my-page` creates a wiki + page with a path `/wikis/docs/my-page`. ### Length restrictions for file and directory names > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. -Many common file systems have a [limit of 255 bytes for file and directory names](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits), and while Git and GitLab both support paths exceeding those limits, the presence of them makes it impossible for users on those file systems to checkout a wiki repository locally. - -To avoid this situation, these limits are enforced when editing pages through the GitLab web interface and API: +Many common file systems have a [limit of 255 bytes](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits) +for file and directory names. Git and GitLab both support paths exceeding +those limits. However, if your file system enforces these limits, you cannot check out a +local copy of a wiki that contains filenames exceeding this limit. To prevent this +problem, the GitLab web interface and API enforce these limits: - 245 bytes for page titles (reserving 10 bytes for the file extension). - 255 bytes for directory names. -Please note that: +Non-ASCII characters take up more than one byte. -- Non-ASCII characters take up more than one byte. -- It's still possible to create files and directories exceeding those limits locally through Git, but this might break on other people's machines. +While you can still create files locally that exceed these limits, your teammates +may not be able to check out the wiki locally afterward. -## Editing a wiki page +## Edit a wiki page -You need Developer [permissions](../../permissions.md) or higher to edit a wiki page. -To do so: +You need Developer [permissions](../../permissions.md) or higher to edit a wiki page: +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the page you want to edit. 1. Select the edit icon (**{pencil}**). 1. Edit the content. 1. Select **Save changes**. -### Adding a table of contents +### Create a table of contents -To generate a table of contents from the headings in a Wiki page, use the `[[_TOC_]]` tag. -For an example, see [Table of contents](../../markdown.md#table-of-contents). +To generate a table of contents from a wiki page's subheadings, use the `[[_TOC_]]` tag. +For an example, read [Table of contents](../../markdown.md#table-of-contents). -## Deleting a wiki page +## Delete a wiki page -You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page. -To do so: +You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page: -1. Open the page you want to delete. +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the page you want to delete. 1. Select **Delete page**. 1. Confirm the deletion. -## Moving a wiki page +## Move a wiki page -You need Developer [permissions](../../permissions.md) or higher to move a wiki page. -To do so: +You need Developer [permissions](../../permissions.md) or higher to move a wiki page: +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the page you want to move. 1. Select the edit icon (**{pencil}**). -1. Add the new path to the **Title** field. +1. Add the new path to the **Title** field. For example, if you have a wiki page + called `about` under `company` and you want to move it to the wiki's root, + change the **Title** from `about` to `/about`. 1. Select **Save changes**. -For example, if you have a wiki page called `about` under `company` and you want to -move it to the wiki's root: - -1. Select the edit icon (**{pencil}**). -1. Change the **Title** from `about` to `/about`. -1. Select **Save changes**. - -If you want to do the opposite: - -1. Select the edit icon (**{pencil}**). -1. Change the **Title** from `about` to `company/about`. -1. Select **Save changes**. +## View history of a wiki page -## Viewing a list of all created wiki pages +The changes of a wiki page over time are recorded in the wiki's Git repository. +To view the changes for a wiki page, select **Page history**. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17673/) in GitLab 13.5, wiki pages are displayed as a nested tree in the sidebar and pages overview. - -Every wiki has a sidebar from which a short list of the created pages can be -found. The list is ordered alphabetically. - - - -If you have many pages, not all are listed in the sidebar. Select -**View All Pages** to see all of them. - -## Viewing the history of a wiki page - -The changes of a wiki page over time are recorded in the wiki's Git repository, -and you can view them by selecting **Page history**. - -From the history page you can see the revision of the page (Git commit SHA), its -author, the commit message, and when it was last updated. -To see how a previous version of the page looked like, select a revision -number in the **Page version** column. +From the history page you can see:  -### Viewing the changes between page versions +- The revision (Git commit SHA) of the page. +- The page author. +- The commit message. +- The last update. +- Previous revisions, by selecting a revision number in the **Page version** column. + +### View changes between page versions > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. -Similar to versioned diff file views, you can see the changes made in a given Wiki page version: +You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. Navigate to the Wiki page you're interested in. +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in.  -## Wiki activity records +## Track wiki events > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** > - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** -Wiki events (creation, deletion, and updates) are tracked by GitLab and -displayed on the [user profile](../../profile/index.md#access-your-user-profile), +GitLab tracks wiki creation, deletion, and update events. These events are displayed on the +[user profile](../../profile/index.md#access-your-user-profile), [group](../../group/index.md#view-group-activity), and [project](../working_with_projects.md#project-activity) activity pages. -## Adding and editing wiki pages locally - -Since wikis are based on Git repositories, you can clone them locally and edit -them like you would do with every other Git repository. - -In the right sidebar, select **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 don't 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 +## Customize sidebar > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -To customize the Wiki's navigation sidebar, you need Developer permissions to the project. +You need Developer [permissions](../../permissions.md) or higher to customize the wiki +navigation sidebar. This process creates a wiki page named `_sidebar` which fully +replaces the default sidebar navigation: -In the top-right, select **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**. +1. In the top right corner of the page, select **Edit sidebar**. +1. When complete, select **Save changes**. -Example for `_sidebar` (using Markdown format): +A `_sidebar` example, formatted with Markdown: ```markdown ### [Home](home) @@ -225,3 +210,79 @@ Example for `_sidebar` (using Markdown format): ``` Support for displaying a generated table of contents with a custom side navigation is planned. + +## Enable or disable a project wiki + +Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) +can enable or disable the project wiki by following the instructions in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). + +Administrators for self-managed GitLab installs can +[configure additional wiki settings](../../../administration/wikis/index.md). + +## Group wikis **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. + +Group wikis work the same way as project wikis. Their usage is similar to project +wikis, with a few limitations: + +- Git LFS is not supported. +- Group wikis are not included in global search. +- Changes to group wikis don't show up in the group's activity feed. + +For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). + +Group wikis can be edited by members with [Developer permissions](../../permissions.md#group-members-permissions) +and above. Group wiki repositories can be moved using the +[Group repository storage moves API](../../../api/group_repository_storage_moves.md). + +## Link an external wiki + +To add a link to an external wiki from a project's left sidebar: + +1. In your project, go to **Settings > Integrations**. +1. Select **External wiki**. +1. Add the URL to your external wiki. +1. (Optional) Select **Test settings** to verify the connection. +1. Select **Save changes**. + +You can now see the **External wiki** option from your project's +left sidebar. + +When you enable this integration, the link to the external +wiki won't replace the link to the internal wiki. +To hide the internal wiki from the sidebar, [disable the project's wiki](#disable-the-projects-wiki). + +To hide the link to an external wiki: + +1. In your project, go to **Settings > Integrations**. +1. Select **External wiki**. +1. Unselect **Enable integration**. +1. Select **Save changes**. + +## Disable the project's wiki + +To disable a project's internal wiki: + +1. In your project, go to **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Scroll down to find **Wiki** and toggle it off (in gray). +1. Select **Save changes**. + +The internal wiki is now disabled, and users and project members: + +- Cannot find the link to the wiki from the project's sidebar. +- Cannot add, delete, or edit wiki pages. +- Cannot view any wiki page. + +Previously added wiki pages are preserved in case you +want to re-enable the wiki. To re-enable it, repeat the process +to disable the wiki but toggle it on (in blue). + +## Resources + +- [Wiki settings for administrators](../../../administration/wikis/index.md) +- [Project wikis API](../../../api/wikis.md) +- [Group repository storage moves API](../../../api/group_repository_storage_moves.md) +- [Group wikis API](../../../api/group_wikis.md) diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index d11f02addea..1c4423fb7b0 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -91,7 +91,7 @@ Examples: ### Excluding filters -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31684) in GitLab Starter 13.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31684) in GitLab 13.3. Filters can be inverted to **filter out** results from the result set, by prefixing the filter name with a `-` (hyphen) character, such as: diff --git a/doc/user/search/img/basic_search.png b/doc/user/search/img/basic_search.png Binary files differindex 234805d5a4f..86aab68f1f0 100644 --- a/doc/user/search/img/basic_search.png +++ b/doc/user/search/img/basic_search.png diff --git a/doc/user/search/img/dashboard_links.png b/doc/user/search/img/dashboard_links.png Binary files differdeleted file mode 100644 index d784ba8018e..00000000000 --- a/doc/user/search/img/dashboard_links.png +++ /dev/null diff --git a/doc/user/search/img/dashboard_links_v13_11.png b/doc/user/search/img/dashboard_links_v13_11.png Binary files differnew file mode 100644 index 00000000000..5f2e61eee1e --- /dev/null +++ b/doc/user/search/img/dashboard_links_v13_11.png diff --git a/doc/user/search/img/issues_mrs_shortcut.png b/doc/user/search/img/issues_mrs_shortcut.png Binary files differindex 2fe1350c806..5be8079030a 100644 --- a/doc/user/search/img/issues_mrs_shortcut.png +++ b/doc/user/search/img/issues_mrs_shortcut.png diff --git a/doc/user/search/img/project_search_dropdown.png b/doc/user/search/img/project_search_dropdown.png Binary files differdeleted file mode 100644 index e0b922a186b..00000000000 --- a/doc/user/search/img/project_search_dropdown.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index f327288ea0a..db89dddaf14 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -12,9 +12,14 @@ type: index, reference, howto To search through issues and merge requests in multiple projects, use the **Issues** or **Merge Requests** links in the top-right part of your screen. These instructions are valid for both. -The number displayed on their right represents the number of issues and merge requests assigned to you: +The numbers in the right-hand side of the top menu indicate how many issues, merge requests, +and to-do items are assigned to you: - + + +- **(issues)** **Issues**: The open issues assigned to you. +- **(merge-request-open)** **Merge requests**: The [merge requests](../project/merge_requests/index.md) assigned to you. +- **(todo-done)** **To-do items**: The [to-do items](../todos.md) assigned to you. When you click **Issues**, GitLab shows the opened issues assigned to you: @@ -282,7 +287,6 @@ search, or choose a specific group or project. To search through code or other documents in a single project, you can use the search field on the top-right of your screen while the project page is open. -  ### SHA search @@ -302,37 +306,12 @@ GitLab instance. ## Search settings -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8. -> - [Added to Group, Admin, and User settings](https://gitlab.com/groups/gitlab-org/-/epics/4842) in GitLab 13.9 -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-search-settings). **(FREE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8 behind a feature flag, disabled by default. +> - [Added to Group, Admin, and User settings](https://gitlab.com/groups/gitlab-org/-/epics/4842) in GitLab 13.9. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. -You can search inside a Project, Group, Admin, or User’s settings by entering +You can search inside a Project, Group, Admin, or User's settings by entering a search term in the search box located at the top of the page. The search results appear highlighted in the sections that match the search term.  - -### Enable or disable Search settings **(FREE SELF)** - -Search settings 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. - -To enable it: - -```ruby -Feature.enable(:search_settings_in_page) -``` - -To disable it: - -```ruby -Feature.disable(:search_settings_in_page) -``` diff --git a/doc/user/snippets.md b/doc/user/snippets.md index c087e68f000..45751e14cb8 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -14,6 +14,8 @@ You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and [syntax highlighting](#filenames), [embedding](#embed-snippets), [downloading](#download-snippets), and you can maintain your snippets with the [snippets API](../api/snippets.md). + + GitLab provides two types of snippets: - **Personal snippets**: Created independent of any project. @@ -57,7 +59,7 @@ To discover all snippets visible to you in GitLab, you can: - **View all snippets visible to you**: In the top navigation bar of your GitLab instance, go to **More > Snippets** to view your snippets dashboard. -- **Visit [GitLab snippets](http://snippets.gitlab.com/)** for your snippets on GitLab.com. +- **Visit [GitLab snippets](https://gitlab.com/dashboard/snippets)** for your snippets on GitLab.com. - **Explore all public snippets**: In the top navigation bar of your GitLab instance, go to **More > Snippets** and select **Explore snippets** to view [all public snippets](https://gitlab.com/explore/snippets). @@ -123,7 +125,16 @@ A single snippet can support up to 10 files, which helps keep related files toge - A `gulpfile.js` file and a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. -You can manage these by using Git (because they're [versioned](#versioned-snippets) +If you need more than 10 files for your snippet, we recommend you create a +[wiki](project/wiki/index.md) instead. Wikis are available for projects at all +subscription levels, and [groups](project/wiki/index.md#group-wikis) for +[GitLab Premium](https://about.gitlab.com/pricing). + +Snippets with multiple files display a file count in the [snippet list](http://snippets.gitlab.com/): + + + +You can manage snippets with Git (because they're [versioned](#versioned-snippets) by a Git repository), through the [Snippets API](../api/snippets.md), and in the GitLab UI. To add a new file to your snippet through the GitLab UI: diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 16ba2582101..07a5eda8cfb 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -5,7 +5,7 @@ group: Utilization info: 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 --- -# Storage usage quota +# Storage usage quota **(FREE SAAS)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in GitLab 12.0. > - Moved to GitLab Free. |
