diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-04-20 10:00:54 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-04-20 10:00:54 +0000 |
| commit | 3cccd102ba543e02725d247893729e5c73b38295 (patch) | |
| tree | f36a04ec38517f5deaaacb5acc7d949688d1e187 /doc/user | |
| parent | 205943281328046ef7b4528031b90fbda70c75ac (diff) | |
| download | gitlab-ce-3cccd102ba543e02725d247893729e5c73b38295.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-10-stable-eev14.10.0-rc42
Diffstat (limited to 'doc/user')
220 files changed, 4060 insertions, 2139 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index 2ad18d5f70e..077718863e7 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -1,73 +1,9 @@ --- -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 +redirect_to: 'dev_ops_reports.md' +remove_date: '2022-06-16' --- -# DevOps Reports **(FREE SELF)** +This document was moved to [another location](dev_ops_reports.md). -DevOps Reports give you an overview of your entire instance's adoption of -[Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) -from planning to monitoring. - -To see DevOps Reports: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Analytics > DevOps Reports**. - -## DevOps Score - -> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) from Conversational Development Index in GitLab 12.6. - -NOTE: -To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. - -You can use the DevOps score to compare your DevOps status to other organizations. - -The DevOps Score tab displays usage of major GitLab features on your instance over -the last 30 days, averaged over the number of billable users in that time period. -You can also see the Leader usage score, calculated from top-performing instances based on -[Service Ping data](../settings/usage_statistics.md#service-ping) that GitLab has collected. -Your score is compared to the lead score of each feature and then expressed -as a percentage at the bottom of said feature. Your overall **DevOps Score** is an average of your -feature scores. - -Service Ping data is aggregated on GitLab servers for analysis. Your usage -information is **not sent** to any other GitLab instances. -If you have just started using GitLab, it might take a few weeks for data to be collected before this -feature is available. - -## DevOps Adoption **(ULTIMATE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/alpha-beta-support.md#beta-features). -> - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. -> - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. -> - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. -> - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. -> - Multi-select [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. -> - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. - -DevOps Adoption shows feature adoption for development, security, and operations. - -| Category | Feature | -| --- | --- | -| Development | Approvals<br>Code owners<br>Issues<br>Merge requests | -| Security | DAST<br>Dependency Scanning<br>Fuzz Testing<br>SAST | -| Operations | Deployments<br>Pipelines<br>Runners | - -You can use Group DevOps Adoption to: - -- Identify specific subgroups that are lagging in their adoption of GitLab features, so you can guide them on -their DevOps journey. -- Find subgroups that have adopted certain features, and provide guidance to other subgroups on -how to use those features. -- Verify if you are getting the return on investment that you expected from GitLab. - -## Add or remove a group - -To add or remove a subgroup from the DevOps Adoption report: - -1. Select **Add or remove groups**. -1. Select the subgroup you want to add or remove and select **Save changes**. - - +<!-- This redirect file can be deleted after <2022-06-16>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md new file mode 100644 index 00000000000..2ad18d5f70e --- /dev/null +++ b/doc/user/admin_area/analytics/dev_ops_reports.md @@ -0,0 +1,73 @@ +--- +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 +--- + +# DevOps Reports **(FREE SELF)** + +DevOps Reports give you an overview of your entire instance's adoption of +[Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) +from planning to monitoring. + +To see DevOps Reports: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Analytics > DevOps Reports**. + +## DevOps Score + +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) from Conversational Development Index in GitLab 12.6. + +NOTE: +To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. + +You can use the DevOps score to compare your DevOps status to other organizations. + +The DevOps Score tab displays usage of major GitLab features on your instance over +the last 30 days, averaged over the number of billable users in that time period. +You can also see the Leader usage score, calculated from top-performing instances based on +[Service Ping data](../settings/usage_statistics.md#service-ping) that GitLab has collected. +Your score is compared to the lead score of each feature and then expressed +as a percentage at the bottom of said feature. Your overall **DevOps Score** is an average of your +feature scores. + +Service Ping data is aggregated on GitLab servers for analysis. Your usage +information is **not sent** to any other GitLab instances. +If you have just started using GitLab, it might take a few weeks for data to be collected before this +feature is available. + +## DevOps Adoption **(ULTIMATE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/alpha-beta-support.md#beta-features). +> - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. +> - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. +> - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. +> - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. +> - Multi-select [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. +> - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. + +DevOps Adoption shows feature adoption for development, security, and operations. + +| Category | Feature | +| --- | --- | +| Development | Approvals<br>Code owners<br>Issues<br>Merge requests | +| Security | DAST<br>Dependency Scanning<br>Fuzz Testing<br>SAST | +| Operations | Deployments<br>Pipelines<br>Runners | + +You can use Group DevOps Adoption to: + +- Identify specific subgroups that are lagging in their adoption of GitLab features, so you can guide them on +their DevOps journey. +- Find subgroups that have adopted certain features, and provide guidance to other subgroups on +how to use those features. +- Verify if you are getting the return on investment that you expected from GitLab. + +## Add or remove a group + +To add or remove a subgroup from the DevOps Adoption report: + +1. Select **Add or remove groups**. +1. Select the subgroup you want to add or remove and select **Save changes**. + + diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index cd505e154c6..9315b926acc 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -15,5 +15,5 @@ Administrators have access to instance-wide analytics: There are several kinds of statistics: -- [DevOps Reports](dev_ops_report.md): Provides an overview of your entire instance's feature usage. +- [DevOps Reports](dev_ops_reports.md): Provides an overview of your entire instance's feature usage. - [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. diff --git a/doc/user/admin_area/email_from_gitlab.md b/doc/user/admin_area/email_from_gitlab.md new file mode 100644 index 00000000000..52f27ed48e0 --- /dev/null +++ b/doc/user/admin_area/email_from_gitlab.md @@ -0,0 +1,60 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: howto, reference +--- + +# Email from GitLab **(PREMIUM SELF)** + +GitLab provides a tool to administrators for emailing all users, or users of +a chosen group or project, right from the Admin Area. Users receive the email +at their primary email address. + +For information about email notifications originating from GitLab, read +[GitLab notification emails](../profile/notifications.md). + +## Use-cases + +- Notify your users about a new project, a new feature, or a new product launch. +- Notify your users about a new deployment, or that downtime is expected + for a particular reason. + +## Sending emails to users from GitLab + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select **Send email to users**. + +  + +1. Compose an email and choose where to send it (all users or users of a + chosen group or project). The email body only supports plain text messages. + HTML, Markdown, and other rich text formats are not supported, and is + sent as plain text to users. + +  + +NOTE: +[Starting with GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/31509), email notifications can be sent only once every 10 minutes. This helps minimize performance issues. + +## Unsubscribing from emails + +Users can choose to unsubscribe from receiving emails from GitLab by following +the unsubscribe link in the email. Unsubscribing is unauthenticated in order +to keep this feature simple. + +On unsubscribe, users receive an email notification that unsubscribe happened. +The endpoint that provides the unsubscribe option is rate-limited. + +<!-- ## 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/admin_area/img/email1.png b/doc/user/admin_area/img/email1.png Binary files differnew file mode 100644 index 00000000000..e79ccc3e9a9 --- /dev/null +++ b/doc/user/admin_area/img/email1.png diff --git a/doc/user/admin_area/img/email2.png b/doc/user/admin_area/img/email2.png Binary files differnew file mode 100644 index 00000000000..d073c0e42da --- /dev/null +++ b/doc/user/admin_area/img/email2.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 4a334c28496..f57672d3d36 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -27,7 +27,7 @@ The Admin Area is made up of the following sections: | **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-area-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [topics](#administering-topics), [jobs](#administering-jobs), [runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | | **{monitor}** Monitoring | View GitLab [system information](#system-information), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit events](#audit-events). | | **{messages}** Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | -| **{hook}** System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | +| **{hook}** System Hooks | Configure [system hooks](../../administration/system_hooks.md) for many events. | | **{applications}** Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | | **{slight-frown}** Abuse Reports | Manage [abuse reports](review_abuse_reports.md) submitted by your users. | | **{license}** License | Add, display, and remove [licenses](license.md). | @@ -79,28 +79,29 @@ To access the Projects page: By default, all projects are listed, in reverse order of when they were last updated. For each project, the following information is listed: -- Name. -- Namespace. -- Description. -- Size, updated every 15 minutes at most. +- Name +- Namespace +- Description +- Size, updated every 15 minutes at most Projects can be edited or deleted. The list of projects can be sorted by: -- Name. -- Last created. -- Oldest created. -- Last updated. -- Oldest updated. -- Owner. +- Updated date +- Last created +- Name +- Most stars +- Oldest created +- Oldest updated +- Largest repository A user can choose to hide or show archived projects in the list. In the **Filter by name** field, type the project name you want to find, and GitLab filters them as you type. -Select from the **Namespace** dropdown to filter only projects in that namespace. +To filter only projects in that namespace, select from the **Namespace** dropdown list. You can combine the filter options. For example, to list only public projects with `score` in their name: diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index bee784e850b..773f91d3076 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -1,6 +1,6 @@ --- stage: Fulfillment -group: License +group: Provision info: 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 --- @@ -36,7 +36,7 @@ To activate your instance with an activation code: The subscription is activated. -If you have an offline or airgapped environment, +If you have an offline or air gapped environment, [activate GitLab EE with a license file or key](license_file.md) instead. If you have questions or need assistance activating your instance, @@ -51,7 +51,19 @@ To verify the edition, sign in to GitLab and select **Help** (**{question-o}**) > **Help**. The GitLab edition and version are listed at the top of the page. -If you are running GitLab Community Edition (CE), you can upgrade your installation to GitLab +If you are running GitLab Community Edition, you can upgrade your installation to GitLab EE. For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). -If you have questions or need assistance upgrading from GitLab CE to EE, +If you have questions or need assistance upgrading from GitLab Community Edition (CE) to EE, [contact GitLab Support](https://about.gitlab.com/support/#contact-support). + +## Troubleshooting + +### Cannot activate instance due to connectivity error + +This error occurs when you use an activation code to activate your instance, but your instance is unable to connect to the GitLab servers. + +You may have connectivity issues due to the following reasons: + +- **You have an offline or air gapped environment**: Configure your setup to allow connection to GitLab servers. If connection to GitLab servers is not possible, contact [GitLab support](https://about.gitlab.com/support/#contact-support) to request a license key. +- **Firewall settings**: Enable an encrypted HTTPS connection from your GitLab instance to `customers.gitlab.com` (with IP addresses 104.18.26.123 and 104.18.27.123) on port 443. +- **Customers Portal is not operational**: To check for performance or service disruptions, check the Customers Portal [status](https://status.gitlab.com/). diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md index e0332e70681..5999e774d26 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/license_file.md @@ -1,6 +1,6 @@ --- stage: Fulfillment -group: License +group: Provision info: 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 --- @@ -23,7 +23,7 @@ Otherwise, to add your license: 1. Select the **Terms of Service** checkbox. 1. Select **Add license**. -## Add your license during installation +## Add your license file during installation You can import a license file when you install GitLab. diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 0ecf76902e1..ed7fdfe2111 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -38,4 +38,4 @@ Merge request approval settings that can be set at an instance level are: See also the following, which are affected by instance-level rules: - [Project merge request approval rules](../project/merge_requests/approvals/index.md). -- [Group merge request approval rules](../group/index.md#group-approval-rules) available in GitLab 13.9 and later. +- [Group merge request approval settings](../group/index.md#group-approval-settings) available in GitLab 13.9 and later. diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index 260a8515a1a..726827054da 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -185,3 +185,12 @@ The results from the query can be plugged into the command: ```shell sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,events,id,'[["id"]\, ["id_convert_to_bigint"]]'] ``` + +### The `BackfillNamespaceIdForNamespaceRoute` batched migration job fails + +In GitLab 14.8, the `BackfillNamespaceIdForNamespaceRoute` batched background migration job +may fail to complete. When retried, a `500 Server Error` is returned. This issue was +[resolved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82387) in GitLab 14.9. + +To resolve this issue, [upgrade GitLab](../../../update/index.md) from 14.8 to 14.9. +You can ignore the failed batch migration until after you update to GitLab 14.9. diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 2f30298644a..e6d8107ed9b 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -199,7 +199,7 @@ To set a limit on how long these sessions are valid: > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.7. [Feature flag ff_limit_ssh_key_lifetime](https://gitlab.com/gitlab-org/gitlab/-/issues/347408) removed. Users can optionally specify a lifetime for -[SSH keys](../../../ssh/index.md). +[SSH keys](../../ssh.md). This lifetime is not a requirement, and can be set to any arbitrary number of days. SSH keys are user credentials to access GitLab. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 0330d89aedc..683c07460ee 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -28,7 +28,18 @@ From now on, every existing project and newly created ones that don't have a If you want to disable it for a specific project, you can do so in [its settings](../../../topics/autodevops/index.md#enable-or-disable-auto-devops). -## Shared runner details +## Enable shared runners for new projects + +You can set all new projects to have the instance's shared runners available by default. + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Continuous Integration and Deployment**. +1. Select the **Enable shared runners for new projects** checkbox. + +Any time a new project is created, the shared runners are available. + +## Add a message for shared runners To display details about the instance's shared runners in all projects' runner settings: @@ -36,16 +47,17 @@ runner settings: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. -1. Enter your shared runner details in the **Shared runner details** field. +1. Enter text, including Markdown if you want, in the **Shared runner details** field. For example: + +  -You can use [Markdown](../../markdown.md) for improved formatting. To see the rendered -details: +To view the rendered details: 1. On the top bar, select **Menu > Project** and select any group or project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runners**. - + ## Maximum artifacts size @@ -137,8 +149,8 @@ As an administrator you can set either a global or namespace-specific limit on t ## Archive jobs -Archiving jobs is useful for reducing the CI/CD footprint on the system by -removing some of the capabilities of the jobs (metadata needed to run the job), +Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some +of the capabilities of the jobs (metadata stored in the database needed to run the job), but persisting the traces and artifacts for auditing purposes. To set the duration for which the jobs are considered as old and expired: @@ -149,7 +161,7 @@ To set the duration for which the jobs are considered as old and expired: 1. Set the value of **Archive jobs**. 1. Hit **Save changes** for the changes to take effect. -After that time passes, the jobs are archived and no longer able to be +After that time passes, the jobs are archived in the background and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. @@ -178,6 +190,26 @@ of your GitLab instance (`.gitlab-ci.yml` if not set): It is also possible to specify a [custom CI/CD configuration file for a specific project](../../../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file). +## Set CI/CD limits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352175) in GitLab 14.10. + +You can configure some [CI/CD limits](../../../administration/instance_limits.md#cicd-limits) +from the Admin Area: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand the **Continuous Integration and Deployment** section. +1. In the **CI/CD limits** section, you can set the following limits: + - **Maximum number of jobs in a single pipeline** + - **Total number of jobs in currently active pipelines** + - **Maximum number of active pipelines per project** + - **Maximum number of pipeline subscriptions to and from a project** + - **Maximum number of pipeline schedules** + - **Maximum number of DAG dependencies that a job can have** + - **Maximum number of runners registered per group** + - **Maximum number of runners registered per project** + ## Enable or disable the pipeline suggestion banner By default, a banner displays in merge requests with no pipeline suggesting a @@ -196,7 +228,7 @@ To enable or disable the banner: WARNING: Required pipeline configurations is in its end-of-life process for Premium users. It's -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) for use in GitLab 14.8, +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) in GitLab 14.8, and planned to be unavailable for Premium users in GitLab 15.0. This feature is planned to continue to be available for Ultimate users. Ultimate users are not impacted by this deprecation and removal. diff --git a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_input_v14_10.png b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_input_v14_10.png Binary files differnew file mode 100644 index 00000000000..08451f36962 --- /dev/null +++ b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_input_v14_10.png diff --git a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_0.png b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_0.png Binary files differdeleted file mode 100644 index d8bc3deccd4..00000000000 --- a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_0.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_10.png b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_10.png Binary files differnew file mode 100644 index 00000000000..64bd9cf6911 --- /dev/null +++ b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_10.png diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 2165dc54899..3eae0d0ff90 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -87,7 +87,7 @@ Alternatively, projects that are marked for removal can be deleted immediately. ## Configure project visibility defaults -To set the default [visibility levels for new projects](../../../public_access/public_access.md): +To set the default [visibility levels for new projects](../../public_access.md): 1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. @@ -112,7 +112,7 @@ To set the default visibility levels for new [snippets](../../snippets.md): 1. Select **Save changes**. For more details on snippet visibility, read -[Project visibility](../../../public_access/public_access.md). +[Project visibility](../../public_access.md). ## Configure group visibility defaults @@ -146,7 +146,7 @@ To restrict visibility levels for projects, snippets, and selected pages: 1. Select **Save changes**. For more details on project visibility, see -[Project visibility](../../../public_access/public_access.md). +[Project visibility](../../public_access.md). ## Configure allowed import sources @@ -162,7 +162,7 @@ You can specify from which hosting sites users can [import their projects](../.. ## Enable project export To enable the export of -[projects and their data](../../../user/project/settings/import_export.md#export-a-project-and-its-data): +[projects and their data](../../project/settings/import_export.md#export-a-project-and-its-data): 1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 8e231d18f41..f0de1e58891 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -34,34 +34,6 @@ To view CI/CD analytics: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > CI/CD Analytics**. -## DevOps Research and Assessment (DORA) key metrics **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. -> - [Added support](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) for lead time for changes in GitLab 13.10. - -The DevOps Research and Assessment ([DORA](https://cloud.google.com/blog/products/devops-sre/the-2019-accelerate-state-of-devops-elite-performance-productivity-and-scaling)) -team developed several key metrics that you can use as performance indicators for software development -teams: - -- Deployment frequency: How often an organization successfully releases to production. -- Lead time for changes: The amount of time it takes for code to reach production. -- Change failure rate: The percentage of deployments that cause a failure in production. -- Time to restore service: How long it takes for an organization to recover from a failure in - production. - -### 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+](#view-deployment-frequency-chart) | The [old API endpoint](../../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) | [13.12+](#view-deployment-frequency-chart) | | -| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | [13.11+](#view-lead-time-for-changes-chart) | Unit in seconds. Aggregation method is median. | -| `lead_time_for_changes` | Group-level | [13.10+](../../api/dora/metrics.md) | [14.0+](#view-lead-time-for-changes-chart) | 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 | | - ## View deployment frequency chart **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 01ee9857060..704476cdc90 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -54,52 +54,81 @@ The following analytics features are available for users to create personalized Be sure to review the documentation page for this feature for GitLab tier requirements. +## DevOps Research and Assessment (DORA) key metrics **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. +> - [Added support](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) for lead time for changes in GitLab 13.10. + +The [DevOps Research and Assessment (DORA)](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance) +team developed several key metrics that you can use as performance indicators for software development +teams. + +### Deployment frequency + +Deployment frequency is the frequency of successful deployments to production (hourly, daily, weekly, monthly, or yearly). +This measures how often you deliver value to end users. A higher deployment frequency means you can +get feedback sooner and iterate faster to deliver improvements and features. GitLab measures this as the number of +deployments to a production environment in the given time period. + +Deployment frequency displays in several charts: + +- [Group-level value stream analytics](../group/value_stream_analytics/index.md) +- [Project-level value stream analytics](value_stream_analytics.md) +- [CI/CD analytics](ci_cd_analytics.md) + +### Lead time for changes + +Lead time for changes measures the time to deliver a feature once it has been developed, +as described in [Measuring DevOps Performance](https://devops.com/measuring-devops-performance/). + +Lead time for changes displays in several charts: + +- [Group-level value stream analytics](../group/value_stream_analytics/index.md) +- [Project-level value stream analytics](value_stream_analytics.md) +- [CI/CD analytics](ci_cd_analytics.md) + +### Time to restore service + +Time to restore service measures how long it takes an organization to recover from a failure in production. +GitLab measures this as the average time required to close the incidents +in the given time period. This assumes: + +- All incidents are related to a production environment. +- Incidents and deployments have a strictly one-to-one relationship. An incident is related to only +one production deployment, and any production deployment is related to no more than one incident). + +To retrieve metrics for time to restore service, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs. + +### Change failure rate + +Change failure rate measures the percentage of deployments that cause a failure in production. GitLab measures this as the number +of incidents divided by the number of deployments to a +production environment in the given time period. This assumes: + +- All incidents are related to a production environment. +- Incidents and deployments have a strictly one-to-one relationship. An incident is related to only +one production deployment, and any production deployment is related to no +more than one incident. + +To retrieve metrics for change failure rate, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs. + +### Supported DORA metrics in GitLab + +| Metric | Level | API | UI chart | Comments | +|---------------------------|-------------------------|-------------------------------------|---------------------------------------|-------------------------------| +| `deployment_frequency` | Project | [GitLab 13.7 and later](../../api/dora/metrics.md) | GitLab 14.8 and later | The [previous API endpoint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | +| `deployment_frequency` | Group | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 13.12 and later | | +| `lead_time_for_changes` | Project | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 13.11 and later | Unit in seconds. Aggregation method is median. | +| `lead_time_for_changes` | Group | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 14.0 and later | Unit in seconds. Aggregation method is median. | +| `time_to_restore_service` | Project and group | [GitLab 14.9 and later](../../api/dora/metrics.md) | Not supported | | +| `change_failure_rate` | Project and group | [GitLab 14.10 and later](../../api/dora/metrics.md) | Not supported | | + ## Definitions We use the following terms to describe GitLab analytics: - **Cycle time:** The duration of only the execution work. Cycle time is often displayed in combination with the lead time, which is longer than the cycle time. GitLab measures cycle time from the earliest commit of a [linked issue's merge request](../project/issues/crosslinking_issues.md) to when that issue is closed. The cycle time approach underestimates the lead time because merge request creation is always later than commit time. GitLab displays cycle time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](../analytics/value_stream_analytics.md). - **Deploys:** The total number of successful deployments to production in the given time frame (across all applicable projects). GitLab displays deploys in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). -- **DORA (DevOps Research and Assessment)** ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): - - **Speed/Velocity** - - - **Deployment frequency:** The relative frequency of successful deployments to production - (hourly, daily, weekly, monthly, or yearly). - This measures how often you are delivering value to end users. A higher deployment - frequency means you are able to get feedback and iterate faster to deliver - improvements and features. GitLab measures this as the number of deployments to a - [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in - the given time period. - GitLab displays deployment frequency in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). - - **Lead Time for Changes:** The time it takes for a commit to get into production. GitLab - measures this as the median duration between merge request merge and deployment to a - [production environment](../../ci/environments/index.md#deployment-tier-of-environments) for - all MRs deployed in the given time period. This measure under estimates lead time because - merge time is always later than commit time. The - [standard definition](https://github.com/GoogleCloudPlatform/fourkeys/blob/main/METRICS.md#lead-time-for-changes) uses median commit time. - [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/328459) to start - measuring from "issue first commit" as a better proxy, although still imperfect. - - - **Stability** - - **Change Failure Rate:** The percentage of deployments causing a failure in production. - GitLab measures this as the number of [incidents](../../operations/incident_management/incidents.md) - divided by the number of deployments to a - [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in - the given time period. This assumes: - - - All incidents are related to a production environment. - - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is - related to only one production deployment, and any production deployment is related to no - more than one incident). - - - **Time to Restore Service:** How long it takes an organization to recover from a failure in - production. GitLab measures this as the average time required to close the - [incidents](../../operations/incident_management/incidents.md) in the given time period. - This assumes: - - - All incidents are related to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). - - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is related to only one production deployment, and any production deployment is related to no more than one incident). - - **Lead time:** The duration of your value stream, from start to finish. Different to [Lead time for changes](#lead-time-for-changes). Often displayed in combination with "cycle time," which is shorter. GitLab measures lead time from issue creation to issue close. GitLab displays lead @@ -121,8 +150,3 @@ with "plan" and ends with "monitor". GitLab helps you track your value stream us - **Velocity:** The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points or weight of issues closed in a given period of time. - -## Lead time for changes - -"Lead Time for Changes" differs from "Lead Time" because it "focuses on measuring only the time to -deliver a feature once it has been developed", as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 5413c28912a..ed94686b7a3 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -91,20 +91,25 @@ The API fuzzing configuration form helps you create or modify your project's API configuration. The form lets you choose values for the most common API fuzzing options and builds a YAML snippet that you can paste in your GitLab CI/CD configuration. -#### Configure Web API fuzzing with the configuration form +#### Configure Web API fuzzing in the UI To generate an API Fuzzing configuration snippet: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. -1. In the **API Fuzzing** row, select **Configure**. -1. Complete the form as needed. Read below for more information on available configuration options. +1. In the **API Fuzzing** row, select **Enable API Fuzzing**. +1. Complete the fields. For details see [Available CI/CD variables](#available-cicd-variables). 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you've selected in the form. -1. Choose one of the following actions: - 1. To copy the snippet to your clipboard and be redirected to your project's `.gitlab-ci.yml` file, - where you can paste the YAML configuration, select **Copy code and open `.gitlab-ci.yml` file**. - 1. To copy the snippet to your clipboard and close the modal, select **Copy code only**. +1. Do one of the following: + 1. To copy the snippet to your clipboard, select **Copy code only**. + 1. To add the snippet to your project's `.gitlab-ci.yml` file, select + **Copy code and open `.gitlab-ci.yml` file**. The Pipeline Editor opens. + 1. Paste the snippet into the `.gitlab-ci.yml` file. + 1. Select the **Lint** tab to confirm the edited `.gitlab-ci.yml` file is valid. + 1. Select the **Edit** tab, then select **Commit changes**. + +When the snippet is committed to the `.gitlab-ci.yml` file, pipelines include an API Fuzzing job. ### OpenAPI Specification @@ -112,6 +117,7 @@ To generate an API Fuzzing configuration snippet: > - Support for OpenAPI Specification using YAML format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. > - Support for OpenAPI Specification v3.1 was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.2. > - Support to generate media type `application/xml` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.8. +> - Support to select media types was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. @@ -125,6 +131,25 @@ the body generation is limited to these body types: - `application/json` - `application/xml` +### OpenAPI and media types + +A media type (formerly known as MIME type) is an identifier for file formats and format contents transmitted. A OpenAPI document lets you specify that a given operation can accept different media types, hence a given request can send data using different file content. As for example, a `PUT /user` operation to update user data could accept data in either XML (media type `application/xml`) or JSON (media type `application/json`) format. +OpenAPI 2.x lets you specify the accepted media types globally or per operation, and OpenAPI 3.x lets you specify the accepted media types per operation. API Fuzzing checks the listed media types and tries to produce sample data for each supported media type. + +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), the default behavior is to select one of the supported media types to use. The first supported media type is chosen from the list. This behavior is configurable. +- In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, `application/json` and `application/xml`), tests are performed using JSON, and then the same tests using XML. + +Testing the same operation (for example, `POST /user`) using different media types (for example, `application/json` and `application/xml`) is not always desirable. +For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. + +The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing will try to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type. + +Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. + +Multiple media types in `FUZZAPI_OPENAPI_MEDIA_TYPES` must separated by a colon (`:`). For example, to limit request generation to the media types `application/x-www-form-urlencoded` and `multipart/form-data`, set the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` to `application/x-www-form-urlencoded:multipart/form-data`. Only supported media types in this list are included when creating requests, though unsupported media types are always skipped. A media type text may contain different sections. For example, `application/vnd.api+json; charset=UTF-8` is a compound of `type "/" [tree "."] subtype ["+" suffix]* [";" parameter]`. Parameters are not taken into account when filtering media types on request generation. + +The environment variables `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` and `FUZZAPI_OPENAPI_MEDIA_TYPES` allow you to decide how to handle media types. These settings are mutually exclusive. If both are enabled, API Fuzzing reports an error. + #### Configure Web API fuzzing with an OpenAPI Specification To configure API fuzzing in GitLab with an OpenAPI Specification: @@ -345,8 +370,8 @@ By default, the API fuzzer uses the Postman file to resolve Postman variable val is set in a GitLab CI/CD variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`, then the JSON file takes precedence to get Postman variable values. -Although Postman can export environment variables into a JSON file, the format is not compatible -with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. +WARNING: +Although Postman can export environment variables into a JSON file, the format is not compatible with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: @@ -561,13 +586,19 @@ profile increases as the number of tests increases. | CI/CD variable | Description | |-------------------------------------------------------------|-------------| | `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | -| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `1`. | +| `FUZZAPI_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | | `FUZZAPI_TARGET_URL` | Base URL of API testing target. | | `FUZZAPI_CONFIG` | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/276395) in GitLab 13.12, replaced with default `.gitlab/gitlab-api-fuzzing-config.yml`. API Fuzzing configuration file. | |[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | |[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | +|[`FUZZAPI_EXCLUDE_URLS`](#exclude-urls) | Exclude API URL from testing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. | +|[`FUZZAPI_EXCLUDE_PARAMETER_ENV`](#exclude-parameters) | JSON string containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | +|[`FUZZAPI_EXCLUDE_PARAMETER_FILE`](#exclude-parameters) | Path to a JSON file containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | |[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`FUZZAPI_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | +|[`FUZZAPI_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. | @@ -891,7 +922,7 @@ def get_auth_response(): # In our example, access token is retrieved from a given endpoint try: - # Performs a http request, response sample: + # Performs a http request, response sample: # { "Token" : "b5638ae7-6e77-4585-b035-7d9de2e3f6b3" } response = get_auth_response() @@ -921,7 +952,7 @@ except Exception as e: logging.error(f'Error, unknown error while retrieving access token. Error message: {e}') raise -# computes object that holds overrides file content. +# computes object that holds overrides file content. # It uses data fetched from request overrides_data = { "headers": { @@ -1036,6 +1067,294 @@ variables: FUZZAPI_EXCLUDE_PATHS=/auth*;/v1/* ``` +### Exclude parameters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. + +While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters you can use one of the following variables: `FUZZAPI_EXCLUDE_PARAMETER_ENV` or `FUZZAPI_EXCLUDE_PARAMETER_FILE`. + +The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre script using `FUZZAPI_PRE_SCRIPT`. + +#### Exclude parameters using a JSON document + +The JSON document contains a JSON object which uses specific properties to identify which parameter should be excluded. +You can provide the following properties to exclude specific parameters during the scanning process: + +- `headers`: Use this property to exclude specific headers. The property's value is an array of header names to be excluded. Names are case-insensitive. +- `cookies`: Use this property's value to exclude specific cookies. The property's value is an array of cookie names to be excluded. Names are case-sensitive. +- `query`: Use this property to exclude specific fields from the query string. The property's value is an array of field names from the query string to be excluded. Names are case-sensitive. +- `body-form`: Use this property to exclude specific fields from a request that uses the media type `application/x-www-form-urlencoded`. The property's value is an array of the field names from the body to be excluded. Names are case-sensitive. +- `body-json`: Use this property to exclude specific JSON nodes from a request that uses the media type `application/json`. The property's value is an array, each entry of the array is a [JSON Path](https://goessner.net/articles/JsonPath/) expression. +- `body-xml`: Use this property to exclude specific XML nodes from a request that uses media type `application/xml`. The property's value is an array, each entry of the array is a [XPath v2](https://www.w3.org/TR/xpath20/) expression. + +The following JSON document is an example of the expected structure to exclude parameters. + +```json +{ + "headers": [ + "header1", + "header2" + ], + "cookies": [ + "cookie1", + "cookie2" + ], + "query": [ + "query-string1", + "query-string2" + ], + "body-form": [ + "form-param1", + "form-param2" + ], + "body-json": [ + "json-path-expression-1", + "json-path-expression-2" + ], + "body-xml" : [ + "xpath-expression-1", + "xpath-expression-2" + ] +} +``` + +#### Examples + +##### Excluding a single header + +To exclude the header `Upgrade-Insecure-Requests`, set the `header` property's value to an array with the header name: `[ "Upgrade-Insecure-Requests" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Upgrade-Insecure-Requests" ] +} +``` + +Header names are case-insensitive, thus the header name `UPGRADE-INSECURE-REQUESTS` is equivalent to `Upgrade-Insecure-Requests`. + +##### Excluding both a header and two cookies + +To exclude the header `Authorization` and the cookies `PHPSESSID` and `csrftoken`, set the `headers` property's value to an array with header name `[ "Authorization" ]` and the `cookies` property's value to an array with the cookies' names `[ "PHPSESSID", "csrftoken" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Authorization" ], + "cookies": [ "PHPSESSID", "csrftoken" ] +} +``` + +##### Excluding a `body-form` parameter + +To exclude the `password` field in a request that uses `application/x-www-form-urlencoded`, set the `body-form` property's value to an array with the field name `[ "password" ]`. For instance, the JSON document looks like this: + +```json +{ + "body-form": [ "password" ] +} +``` + +The exclude parameters uses `body-form` when the request uses a content type `application/x-www-form-urlencoded`. + +##### Excluding a specific JSON nodes using JSON Path + +To exclude the `schema` property in the root object, set the `body-json` property's value to an array with the JSON Path expression `[ "$.schema" ]`. + +The JSON Path expression uses special syntax to identify JSON nodes: `$` refers to the root of the JSON document, `.` refers to the current object (in our case the root object), and the text `schema` refers to a property name. Thus, the JSON path expression `$.schema` refers to a property `schema` in the root object. +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.schema" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path, characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding multiple JSON nodes using JSON Path + +To exclude the property `password` on each entry of an array of `users` at the root level, set the `body-json` property's value to an array with the JSON Path expression `[ "$.users[*].paswword" ]`. + +The JSON Path expression starts with `$` to refer to the root node and uses `.` to refer to the current node. Then, it uses `users` to refer to a property and the characters `[` and `]` to enclose the index in the array you want to use, instead of providing a number as an index you use `*` to specify any index. After the index reference, we find `.` which now refers to any given selected index in the array, preceded by a property name `password`. + +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.users[*].paswword" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding an XML attribute + +To exclude an attribute named `isEnabled` located in the root element `credentials`, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/@isEnabled" ]`. + +The XPath expression `/credentials/@isEnabled`, starts with `/` to indicate the root of the XML document, then it is followed by the word `credentials` which indicates the name of the element to match. It uses a `/` to refer to a node of the previous XML element, and the character `@` to indicate that the name `isEnable` is an attribute. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/@isEnabled" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be an [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions, characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML element's text + +To exclude the text of the `username` element contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username/text()" ]`. + +In the XPath expression `/credentials/username/text()`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. Last part has a `/` that refers to the current element, and uses a XPath function called `text()` which identifies the text of the current element. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username/text()" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML element + +To exclude the element `username` contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username" ]`. + +In the XPath expression `/credentials/username`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML node with namespaces + +To exclude a XML element `login` which is defined in namespace `s`, and contained in `credentials` root node, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/s:login" ]`. + +In the XPath expression `/credentials/s:login`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `s:login`. Notice that name contains the character `:`, this character separates the namespace from the node name. + +The namespace name should have been defined in the XML document which is part of the body request. You may check the namespace in the specification document HAR, OpenAPI, or Postman Collection file. + +```json +{ + "body-xml": [ + "/credentials/s:login" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +#### Using a JSON string + +To provide the exclusion JSON document set the variable `FUZZAPI_EXCLUDE_PARAMETER_ENV` with the JSON string. In the following example, the `.gitlab-ci.yml`, the `FUZZAPI_EXCLUDE_PARAMETER_ENV` variable is set to a JSON string: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_EXCLUDE_PARAMETER_ENV: '{ "headers": [ "Upgrade-Insecure-Requests" ] }' +``` + +#### Using a file + +To provide the exclusion JSON document, set the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE` with the JSON file path. The file path is relative to the job current working directory. In the following example `.gitlab-ci.yml` file, the `FUZZAPI_EXCLUDE_PARAMETER_FILE` variable is set to a JSON file path: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_EXCLUDE_PARAMETER_FILE: api-fuzzing-exclude-parameters.json +``` + +The `api-fuzzing-exclude-parameters.json` is a JSON document that follows the structure of [exclude parameters document](#exclude-parameters-using-a-json-document). + +### Exclude URLS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. + +As an alternative to excluding by paths, you can filter by any other component in the URL by using the `FUZZAPI_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry such as `.*` excludes all URLs because it is a regular expression that matches everything. + +In your job output you can check if any URLs matched any provided regular expression from `FUZZAPI_EXCLUDE_URLS`. Matching operations are listed in the **Excluded Operations** section. Operations listed in the **Excluded Operations** should not be listed in the **Tested Operations** section. For example the following portion of a job output: + +```plaintext +2021-05-27 21:51:08 [INF] API Security: --[ Tested Operations ]------------------------- +2021-05-27 21:51:08 [INF] API Security: 201 POST http://target:7777/api/users CREATED +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +2021-05-27 21:51:08 [INF] API Security: --[ Excluded Operations ]----------------------- +2021-05-27 21:51:08 [INF] API Security: GET http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: POST http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +``` + +NOTE: +Each value in `FUZZAPI_EXCLUDE_URLS` is a regular expression. Characters such as `.` , `*` and `$` among many others have special meanings in [regular expressions](https://en.wikipedia.org/wiki/Regular_expression#Standards). + +#### Examples + +##### Excluding a URL and child resources + +The following example excludes the URL `http://target/api/auth` and its child resources. + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: http://target/api/auth +``` + +##### Excluding two URLs and allow their child resources + +To exclude the URLs `http://target/api/buy` and `http://target/api/sell` but allowing to scan their child resources, for instance: `http://target/api/buy/toy` or `http://target/api/sell/chair`. You could use the value `http://target/api/buy/$,http://target/api/sell/$`. This value is using two regular expressions, each of them separated by a `,` character. Hence, it contains `http://target/api/buy$` and `http://target/api/sell$`. In each regular expression, the trailing `$` character points out where the matching URL should end. + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$ +``` + +##### Excluding two URLs and their child resources + +In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell +``` + +##### Excluding URL using regular expressions + +In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. + +```yaml +variables: + FUZZAPI_EXCLUDE_URLS: https://target/api/v.*/user/create$ +``` + ### Header Fuzzing Header fuzzing is disabled by default due to the high number of false positives that occur with many @@ -1495,6 +1814,19 @@ API Security can still try to consume an OpenAPI document that does not fully co FUZZAPI_OPENAPI_RELAXED_VALIDATION: On ``` +### No operation in the OpenAPI document is consuming any supported media type + +API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. + +**Error message** + +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), `Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.` + +**Solution** + +1. Review the supported media types in the [OpenAPI Specification](#openapi-specification) section. +1. Edit your OpenAPI document, allowing at least a given operation to accept any of the supported media types. Alternatively, a supported media type could be set in the OpenAPI document level and get applied to all operations. This step may require changes in your application to ensure the supported media type is accepted by the application. + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index f2d6cef669d..64566e458ee 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -186,7 +186,7 @@ The `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` CI/CD variable controls whether the findings related to programming languages. The languages supported depend on the [scanner used](#change-scanners): -- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/language/). +- [Trivy](https://aquasecurity.github.io/trivy/latest/docs/vulnerability/detection/language/). - [Grype](https://github.com/anchore/grype#features). By default, the report only includes packages managed by the Operating System (OS) package manager @@ -222,6 +222,7 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | +| `CS_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | | `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | | `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | @@ -236,22 +237,29 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u Support depends on the scanner: - [Grype](https://github.com/anchore/grype#grype) -- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/os/) (Default). +- [Trivy](https://aquasecurity.github.io/trivy/latest/docs/vulnerability/detection/os/) (Default). -#### UBI-based images +#### FIPS-enabled images > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5775) in GitLab 14.1. -GitLab also offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) -versions of the container-scanning images. You can therefore replace standard images with UBI-based -images. To configure the images, set the `CS_ANALYZER_IMAGE` variable to the standard tag plus the -`-ubi` extension. +GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the container-scanning images. You can therefore replace standard images with FIPS-enabled +images. To configure the images, set the `CS_IMAGE_SUFFIX` to `-fips` or modify the `CS_ANALYZER_IMAGE` variable to the +standard tag plus the `-fips` extension. | Scanner name | `CS_ANALYZER_IMAGE` | | --------------- | ------------------- | -| Default (Trivy) | `registry.gitlab.com/security-products/container-scanning:4-ubi` | -| Grype | `registry.gitlab.com/security-products/container-scanning/grype:4-ubi` | -| Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:4-ubi` | +| Default (Trivy) | `registry.gitlab.com/security-products/container-scanning:4-fips` | +| Grype | `registry.gitlab.com/security-products/container-scanning/grype:4-fips` | +| Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:4-fips` | + +NOTE: +Prior to GitLab 15.0, the `-ubi` image extension is also available. GitLab 15.0 and later only +support `-fips`. + +Starting with GitLab 14.10, `-fips` is automatically added to `CS_ANALYZER_IMAGE` when FIPS mode is +enabled in the GitLab instance. ### Enable Container Scanning through an automatic merge request @@ -753,7 +761,7 @@ The images include the latest advisory database available for their respective s scanner includes data from multiple sources: - [Grype](https://github.com/anchore/grype#grypes-database). -- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/data-source/). +- [Trivy](https://aquasecurity.github.io/trivy/latest/docs/vulnerability/detection/data-source/). Database update information for other analyzers is available in the [maintenance table](../index.md#vulnerability-scanner-maintenance). diff --git a/doc/user/application_security/dast/checks/598.2.md b/doc/user/application_security/dast/checks/598.2.md new file mode 100644 index 00000000000..f6c6787128d --- /dev/null +++ b/doc/user/application_security/dast/checks/598.2.md @@ -0,0 +1,30 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Use of GET request method with sensitive query strings (password) + +## Description + +The user's password was identified in the request URL. Passwords should never be sent in GET +requests as they maybe captured by proxy systems, stored in browser history, or stored in +log files. If an attacker were to get access to these logs or logging systems, they would +be able to gain access to the target account. + +## Remediation + +Passwords should never be sent in GET requests. When authenticating users or requesting users +reset their passwords, always use POST requests to transmit sensitive data. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 598.2 | true | 598 | Passive | Medium | + +## Links + +- [OWASP](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) +- [CWE](https://cwe.mitre.org/data/definitions/598.html) diff --git a/doc/user/application_security/dast/checks/598.3.md b/doc/user/application_security/dast/checks/598.3.md new file mode 100644 index 00000000000..fa6fdf43e1c --- /dev/null +++ b/doc/user/application_security/dast/checks/598.3.md @@ -0,0 +1,31 @@ +--- +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 +--- + +# Use of GET request method with sensitive query strings (Authorization header details) + +## Description + +The authorization header value was identified in the request URL. These headers typically contain +usernames and passwords or JWT tokens. These values should never be sent in GET requests as they +maybe captured by proxy systems, stored in browser history, or stored in log files. If an attacker +were to get access to these logs or logging systems, they would be able to gain access to the +target account. + +## Remediation + +Authorization header details should never be sent in GET requests. When transmitting sensitive information +such as JWT tokens, always use POST requests or headers to transmit the sensitive data. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 598.3 | true | 598 | Passive | Medium | + +## Links + +- [OWASP](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) +- [CWE](https://cwe.mitre.org/data/definitions/598.html) diff --git a/doc/user/application_security/dast/checks/829.1.md b/doc/user/application_security/dast/checks/829.1.md new file mode 100644 index 00000000000..ca3d99c2bc9 --- /dev/null +++ b/doc/user/application_security/dast/checks/829.1.md @@ -0,0 +1,48 @@ +--- +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 +--- + +# Inclusion of Functionality from Untrusted Control Sphere + +## Description + +JavaScript or CSS source files are included from third party domains without +[Sub-Resource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). +If an attacker were to compromise the sites hosting these third party resources, they could inject malicious +script or CSS data in an attempt to compromise users of your application. However, if SRI was applied and an +attacker attempted to modify the contents of the script, the browser would not load the script and your +applications users would be protected from the malicious alterations. + +## Remediation + +All identified resources should be sourced from the same domain as the target application. If this is not +possible, it is strongly recommended that all `script` tags that implement `src` values, or `link` tags +that implement the `href` values include Sub-Resource Integrity. To generate SRI integrity values the +[srihash](https://www.srihash.org/) tool can be used, or by running one of the following commands: + +- `cat FILENAME.js | openssl dgst -sha384 -binary | openssl base64 -A` +- `shasum -b -a 384 FILENAME.js | awk '{ print $1 }' | xxd -r -p | base64` + +The output of these tools must be added as additional attributes, in particular: `integrity` and either +`crossorigin=anonymous` or `crossorigin=use-credentials`. +An example of a valid SRI protected script tag can be found below: + +```html +<script src="https://example.com/example-framework.js" + integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC" + crossorigin="anonymous"></script> +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 829.1 | true | 829 | Passive | Low | + +## Links + +- [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html#subresource-integrity) +- [CWE](https://cwe.mitre.org/data/definitions/829.html) +- [MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) diff --git a/doc/user/application_security/dast/checks/829.2.md b/doc/user/application_security/dast/checks/829.2.md new file mode 100644 index 00000000000..e6fada117f8 --- /dev/null +++ b/doc/user/application_security/dast/checks/829.2.md @@ -0,0 +1,47 @@ +--- +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 +--- + +# Invalid Sub-Resource Integrity values detected + +## Description + +JavaScript or CSS source files were found to contain invalid +[Sub-Resource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) +`integrity` values or a missing `crossorigin` value. These scripts or links should be investigated to +ensure they have not been maliciously altered. If in doubt, contact the owner of the scripts or replace +them with known good versions. + +## Remediation + +All identified resources should be sourced from the same domain as the target application. If this is not +possible, it is strongly recommended that all `script` tags that implement `src` values, or `link` tags +that implement the `href` values include Sub-Resource Integrity. To generate SRI integrity values the +[srihash](https://www.srihash.org/) tool can be used, or by running one of the following commands: + +- `cat FILENAME.js | openssl dgst -sha384 -binary | openssl base64 -A` +- `shasum -b -a 384 FILENAME.js | awk '{ print $1 }' | xxd -r -p | base64` + +The output of these tools must be added as additional attributes, in particular: `integrity` and either +`crossorigin=anonymous` or `crossorigin=use-credentials`. +An example of a valid SRI protected script tag can be found below: + +```html +<script src="https://example.com/example-framework.js" + integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC" + crossorigin="anonymous"></script> +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 829.2 | true | 829 | Passive | Medium | + +## Links + +- [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html#subresource-integrity) +- [CWE](https://cwe.mitre.org/data/definitions/829.html) +- [MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 435bc28c4aa..764e3c4a839 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -20,5 +20,9 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [200.1](200.1.md) | Exposure of sensitive information to an unauthorized actor (private IP address) | Low | Passive | | [548.1](548.1.md) | Exposure of information through directory listing | Low | Passive | | [598.1](598.1.md) | Use of GET request method with sensitive query strings (session ID) | Medium | Passive | +| [598.2](598.2.md) | Use of GET request method with sensitive query strings (password) | Medium | Passive | +| [598.3](598.3.md) | Use of GET request method with sensitive query strings (Authorization header details) | Medium | Passive | | [614.1](614.1.md) | Sensitive cookie without Secure attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | +| [829.1](829.1.md) | Inclusion of Functionality from Untrusted Control Sphere | Low | Passive | +| [829.2](829.2.md) | Invalid Sub-Resource Integrity values detected | Medium | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index fd6c39ffbf1..ee57803dfc7 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -278,7 +278,8 @@ page. You can enable or configure DAST settings using the UI. The generated settings are formatted so they can be conveniently pasted into the `.gitlab-ci.yml` file. -1. From the project's home page, go to **Security & Compliance > Configuration**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Enable DAST** or **Configure DAST**. 1. Select the desired **Scanner profile**, or select **Create scanner profile** and save a @@ -288,12 +289,14 @@ can be conveniently pasted into the `.gitlab-ci.yml` file. 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you selected. 1. Do one of the following: - 1. Select **Copy code only** to copy the snippet to your clipboard. - 1. Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard. The - CI/CD Editor then opens. + 1. To copy the snippet to your clipboard, select **Copy code only**. + 1. To add the snippet to your project's `.gitlab-ci.yml` file, select + **Copy code and open `.gitlab-ci.yml` file**. The Pipeline Editor opens. 1. Paste the snippet into the `.gitlab-ci.yml` file. 1. Select the **Lint** tab to confirm the edited `.gitlab-ci.yml` file is valid. - 1. Select **Commit changes**. + 1. Select the **Edit** tab, then select **Commit changes**. + +When the snippet is committed to the `.gitlab-ci.yml` file, pipelines include a DAST job. #### Crawling web applications dependent on JavaScript @@ -1053,7 +1056,7 @@ To run an on-demand scan either at a scheduled date or frequency, read 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. -1. Select **New DAST scan**. +1. Select **New scan**. 1. Complete the **Scan name** and **Description** fields. 1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown. 1. In **Scanner profile**, select a scanner profile from the dropdown. @@ -1088,7 +1091,7 @@ To schedule a scan: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > On-demand Scans**. -1. Select **New DAST scan**. +1. Select **New scan**. 1. Complete the **Scan name** and **Description** text boxes. 1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. 1. In the **Scanner profile** section, from the dropdown list, select a scanner profile. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 839833d9d98..a4908204b60 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -7,73 +7,65 @@ type: reference, howto # DAST API **(ULTIMATE)** -You can add dynamic application security testing of web APIs to your [GitLab CI/CD](../../../ci/index.md) pipelines. -This helps you discover bugs and potential security issues that other QA processes may miss. +You can add dynamic application security testing (DAST) of web APIs to your +[GitLab CI/CD](../../../ci/index.md) pipelines. This helps you discover bugs and potential security +issues that other QA processes may miss. We recommend that you use DAST API testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run DAST API tests as part your CI/CD workflow. -## Requirements - -- One of the following web API types: - - REST API - - SOAP - - GraphQL - - Form bodies, JSON, or XML -- One of the following assets to provide APIs to test: - - OpenAPI v2 or v3 API definition - - Postman Collection v2.0 or v2.1 - - HTTP Archive (HAR) of API requests to test +WARNING: +Do not run DAST API testing against a production server. Not only can it perform *any* function that +the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting +data. Only run DAST API against a test server. -## When DAST API scans run +You can run DAST API scanning against the following web API types: -When using the `DAST-API.gitlab-ci.yml` template, the defined jobs use the `dast` stage by default. To enable your `.gitlab-ci.yml` file must include the `dast` stage in your `stages` definition. To ensure DAST API scans the latest code, your CI pipeline should deploy changes to a test environment in a stage before the `dast` stage: +- REST API +- SOAP +- GraphQL +- Form bodies, JSON, or XML -```yaml -stages: - - build - - test - - deploy - - dast -``` +## When DAST API scans run -Note that if your pipeline is configured to deploy to the same web server on each run, running a -pipeline while another is still running could cause a race condition in which one pipeline -overwrites the code from another. The API to scan should be excluded from changes for the duration -of a DAST API scan. The only changes to the API should be from the DAST API scanner. Be aware that -any changes made to the API (for example, by users, scheduled tasks, database changes, code -changes, other pipelines, or other scanners) during a scan could cause inaccurate results. +DAST API scanning runs in the `dast` stage by default. To ensure DAST API scanning examines the latest +code, ensure your CI/CD pipeline deploys changes to a test environment in a stage before the `dast` +stage. -## Enable DAST API scanning +If your pipeline is configured to deploy to the same web server on each run, running a pipeline +while another is still running could cause a race condition in which one pipeline overwrites the +code from another. The API to be scanned should be excluded from changes for the duration of a +DAST API scan. The only changes to the API should be from the DAST API scanner. Changes made to the +API (for example, by users, scheduled tasks, database changes, code changes, other pipelines, or +other scanners) during a scan could cause inaccurate results. -There are three ways to perform scans. See the configuration section for the one you wish to use: +## Example DAST API scanning configurations -- [OpenAPI v2 or v3 specification](#openapi-specification) -- [HTTP Archive (HAR)](#http-archive-har) -- [Postman Collection v2.0 or v2.1](#postman-collection) +The following projects demonstrate DAST API scanning: -Examples of various configurations can be found here: - -- [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/openapi-example) +- [Example OpenAPI v2 Specification project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/openapi-example) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/har-example) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/postman-example) - [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/graphql-example) - [Example SOAP project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/soap-example) -WARNING: -GitLab 14.0 will require that you place DAST API configuration files (for example, -`gitlab-dast-api-config.yml`) in your repository's `.gitlab` directory instead of your -repository's root. You can continue using your existing configuration files as they are, but -starting in GitLab 14.0, GitLab will not check your repository's root for configuration files. +## Targeting API for DAST scanning + +You can specify the API you want to scan by using: + +- [OpenAPI v2 or v3 Specification](#openapi-specification) +- [HTTP Archive (HAR)](#http-archive-har) +- [Postman Collection v2.0 or v2.1](#postman-collection) ### OpenAPI Specification > - Support for OpenAPI Specification using YAML format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. > - Support to generate media type `application/xml` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.8. +> - Support to media types was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. -This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. +This section shows you how to configure DAST API scanning using an OpenAPI Specification to provide information about the target API to test. OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported. DAST API uses an OpenAPI document to generate the request body. When a request body is required, @@ -84,52 +76,40 @@ the body generation is limited to these body types: - `application/json` - `application/xml` -Follow these steps to configure DAST API in GitLab with an OpenAPI specification: +### OpenAPI and media types -1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) - that's provided as part of your GitLab installation. Add the following to your - `.gitlab-ci.yml` file: +A media type (formerly known as MIME type) is an identifier for file formats and format contents transmitted. A OpenAPI document lets you specify that a given operation can accept different media types, hence a given request can send data using different file content. As for example, a `PUT /user` operation to update user data could accept data in either XML (media type `application/xml`) or JSON (media type `application/json`) format. +OpenAPI 2.x lets you specify the accepted media types globally or per operation, and OpenAPI 3.x lets you specify the accepted media types per operation. DAST API will check the listed media types, and try to produce sample data for each supported media type. - ```yaml - stages: - - dast +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), the default behavior is to select one of the supported media types to use. The first supported media type is chosen from the list. This behavior is configurable. +- In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, `application/json` and `application/xml`), testing are performed using JSON, and then the same tests using XML. - include: - - template: DAST-API.gitlab-ci.yml - ``` +Testing the same operation (for example, `POST /user`) using different media types (for example, `application/json` and `application/xml`) is not always desirable. +For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicated vulnerabilities related to the request body depending on the target app. -1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. - Testing with this profile completes faster, allowing for easier configuration validation. +The environment variable `DAST_API_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environment variable `DAST_API_OPENAPI_ALL_MEDIA_TYPES` is set to any value, DAST API tries to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type. - Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick` for the profile you choose: +Alternatively, the variable `DAST_API_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `DAST_API_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. - ```yaml - stages: - - dast +Multiple media types in `DAST_API_OPENAPI_MEDIA_TYPES` are separated by a colon (`:`). For example, to limit request generation to the media types `application/x-www-form-urlencoded` and `multipart/form-data`, set the environment variable `DAST_API_OPENAPI_MEDIA_TYPES` to `application/x-www-form-urlencoded:multipart/form-data`. Only supported media types in this list are included when creating requests, though non-supported media types are always skipped. A media type text may contain different sections. For example, `application/vnd.api+json; charset=UTF-8`, is a compound of `type "/" [tree "."] subtype ["+" suffix]* [";" parameter]`. Parameters are not taken into account when performing the filtering media types on request generation. - include: - - template: DAST-API.gitlab-ci.yml +The environment variables `DAST_API_OPENAPI_ALL_MEDIA_TYPES` and `DAST_API_OPENAPI_MEDIA_TYPES` allow you to decide how to handle media types. These settings are mutually exclusive. If both are enabled, DAST API reports an error. - variables: - DAST_API_PROFILE: Quick - ``` +#### Configure DAST API with an OpenAPI Specification -1. Provide the location of the OpenAPI specification. You can provide the specification as a file - or URL. Specify the location by adding the `DAST_API_OPENAPI` variable: +To configure DAST API scanning with an OpenAPI specification: - ```yaml - stages: - - dast +To configure DAST API scanning with an OpenAPI Specification: - include: - - template: DAST-API.gitlab-ci.yml +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) in your `.gitlab-ci.yml` file. - variables: - DAST_API_PROFILE: Quick - DAST_API_OPENAPI: test-api-specification.json - ``` +1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. + Testing with this profile completes faster, allowing for easier configuration validation. + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. + +1. Provide the location of the OpenAPI Specification as either a file or URL. + Specify the location by adding the `DAST_API_OPENAPI` variable. 1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. @@ -140,20 +120,20 @@ Follow these steps to configure DAST API in GitLab with an OpenAPI specification automatically parses that file to find its scan target. 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). - Here's an example of using `DAST_API_TARGET_URL`: +Complete example configuration of using an OpenAPI Specification: - ```yaml - stages: - - dast +```yaml +stages: + - dast - include: - - template: DAST-API.gitlab-ci.yml +include: + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_PROFILE: Quick - DAST_API_OPENAPI: test-api-specification.json - DAST_API_TARGET_URL: http://test-deployment/ - ``` +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ +``` This is a minimal configuration for DAST API. From here you can: @@ -161,14 +141,12 @@ This is a minimal configuration for DAST API. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run DAST API testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run DAST API scanning against a test server. - ### HTTP Archive (HAR) -The [HTTP Archive format (HAR)](http://www.softwareishard.com/blog/har-12-spec/) -is an archive file format for logging HTTP transactions. When used with the GitLab DAST API scanner, HAR must contain records of calling the web API to test. The DAST API scanner extracts all the requests and -uses them to perform testing. +The [HTTP Archive format (HAR)](../api_fuzzing/create_har_files.md) is an archive file format for +logging HTTP transactions. When used with the GitLab DAST API scanner, the HAR file must contain +records of calling the web API to test. The DAST API scanner extracts all of the requests and uses them +to perform testing. You can use various tools to generate HAR files: @@ -182,53 +160,20 @@ WARNING: HAR files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the HAR file contents before adding them to a repository. -Follow these steps to configure DAST API to use a HAR file that provides information about the -target API to test: +#### DAST API scanning with a HAR file -1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) - that's provided as part of your GitLab installation. To do so, add the following to your - `.gitlab-ci.yml` file: +To configure DAST API to use a HAR file that provides information about the target API to test: - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - ``` +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) in your `.gitlab-ci.yml` file. 1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. Testing with this profile completes faster, allowing for easier configuration validation. - Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick` for the profile you choose: - - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - ``` + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. 1. Provide the location of the HAR file. You can provide the location as a file path - or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable: - - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - DAST_API_HAR: test-api-recording.har - ``` + or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable. 1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. @@ -239,20 +184,20 @@ target API to test: automatically parses that file to find its scan target. 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). - Here's an example of using `DAST_API_TARGET_URL`: +Complete example configuration of using an HAR file: - ```yaml - stages: - - dast +```yaml +stages: + - dast - include: - - template: DAST-API.gitlab-ci.yml +include: + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_PROFILE: Quick - DAST_API_HAR: test-api-recording.har - DAST_API_TARGET_URL: http://test-deployment/ - ``` +variables: + DAST_API_PROFILE: Quick + DAST_API_HAR: test-api-recording.har + DAST_API_TARGET_URL: http://test-deployment/ +``` This is a minimal configuration for DAST API. From here you can: @@ -260,11 +205,6 @@ This is a minimal configuration for DAST API. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run DAST API testing against a production server. Not only can it perform *any* function that -the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting -data. Only run DAST API against a test server. - ### Postman Collection The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that @@ -282,52 +222,20 @@ Postman Collection files may contain sensitive information such as authenticatio and session cookies. We recommend that you review the Postman Collection file contents before adding them to a repository. -Follow these steps to configure DAST API to use a Postman Collection file that provides -information about the target API to test: - -1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) - that's provided as part of your GitLab installation. To do so, add the following to your - `.gitlab-ci.yml` file: +#### DAST API scanning with a Postman Collection file - ```yaml - stages: - - dast +To configure DAST API to use a Postman Collection file that provides information about the target +API to test: - include: - - template: DAST-API.gitlab-ci.yml - ``` +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). 1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. Testing with this profile completes faster, allowing for easier configuration validation. - Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick` for the profile you choose: + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - ``` - -1. Provide the location of the Postman Collection file. You can provide the location as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: - - ```yaml - stages: - - dast - - include: - - template: DAST-API.gitlab-ci.yml - - variables: - DAST_API_PROFILE: Quick - DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json - ``` +1. Provide the location of the Postman Collection file as either a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable. 1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. @@ -338,20 +246,20 @@ information about the target API to test: automatically parses that file to find its scan target. 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). - Here's an example of using `DAST_API_TARGET_URL`: +Complete example configuration of using a Postman collection: - ```yaml - stages: - - dast +```yaml +stages: + - dast - include: - - template: DAST-API.gitlab-ci.yml +include: + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_PROFILE: Quick - DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json - DAST_API_TARGET_URL: http://test-deployment/ - ``` +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json + DAST_API_TARGET_URL: http://test-deployment/ +``` This is a minimal configuration for DAST API. From here you can: @@ -359,12 +267,7 @@ This is a minimal configuration for DAST API. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run DAST API testing against a production server. Not only can it perform *any* function that -the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting -data. Only run DAST API against a test server. - -#### Postman variables +##### Postman variables Postman allows the developer to define placeholders that can be used in different parts of the requests. These placeholders are called variables, as explained in [Using variables](https://learning.postman.com/docs/sending-requests/variables/). @@ -388,11 +291,11 @@ Postman file. For example, Postman does not export environment-scoped variables file. By default, the DAST API scanner uses the Postman file to resolve Postman variable values. If a JSON file -is set in a GitLab CI environment variable `DAST_API_POSTMAN_COLLECTION_VARIABLES`, then the JSON +is set in a GitLab CI/CD environment variable `DAST_API_POSTMAN_COLLECTION_VARIABLES`, then the JSON file takes precedence to get Postman variable values. -Although Postman can export environment variables into a JSON file, the format is not compatible -with the JSON expected by `DAST_API_POSTMAN_COLLECTION_VARIABLES`. +WARNING: +Although Postman can export environment variables into a JSON file, the format is not compatible with the JSON expected by `DAST_API_POSTMAN_COLLECTION_VARIABLES`. Here is an example of using `DAST_API_POSTMAN_COLLECTION_VARIABLES`: @@ -421,12 +324,12 @@ values. For example: } ``` -### Authentication +## Authentication Authentication is handled by providing the authentication token as a header or cookie. You can provide a script that performs an authentication flow or calculates the token. -#### HTTP Basic Authentication +### HTTP Basic Authentication [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) is an authentication method built in to the HTTP protocol and used in conjunction with @@ -456,23 +359,23 @@ variables: DAST_API_HTTP_PASSWORD: $TEST_API_PASSWORD ``` -#### Bearer Tokens +### Bearer tokens Bearer tokens are used by several different authentication mechanisms, including OAuth2 and JSON Web -Tokens (JWT). Bearer tokens are transmitted using the `Authorization` HTTP header. To use bearer +Tokens (JWT). Bearer tokens are transmitted using the `Authorization` HTTP header. To use Bearer tokens with DAST API, you need one of the following: -- A token that doesn't expire -- A way to generate a token that lasts the length of testing -- A Python script that DAST API can call to generate the token +- A token that doesn't expire. +- A way to generate a token that lasts the length of testing. +- A Python script that DAST API can call to generate the token. -##### Token doesn't expire +#### Token doesn't expire -If the bearer token doesn't expire, use the `DAST_API_OVERRIDES_ENV` variable to provide it. This +If the Bearer token doesn't expire, use the `DAST_API_OVERRIDES_ENV` variable to provide it. This variable's content is a JSON snippet that provides headers and cookies to add to DAST API's outgoing HTTP requests. -Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: +Follow these steps to provide the Bearer token with `DAST_API_OVERRIDES_ENV`: 1. [Create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables), for example `TEST_API_BEARERAUTH`, with the value @@ -502,9 +405,9 @@ Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: 1. To validate that authentication is working, run an DAST API test and review the job logs and the test API's application logs. -##### Token generated at test runtime +#### Token generated at test runtime -If the bearer token must be generated and doesn't expire during testing, you can provide to DAST API a file containing the token. A prior stage and job, or part of the DAST API job, can +If the Bearer token must be generated and doesn't expire during testing, you can provide DAST API a file that has the token. A prior stage and job, or part of the DAST API job, can generate this file. DAST API expects to receive a JSON file with the following structure: @@ -539,14 +442,14 @@ variables: To validate that authentication is working, run an DAST API test and review the job logs and the test API's application logs. -##### Token has short expiration +#### Token has short expiration -If the bearer token must be generated and expires prior to the scan's completion, you can provide a +If the Bearer token must be generated and expires prior to the scan's completion, you can provide a program or script for the DAST API scanner to execute on a provided interval. The provided script runs in an Alpine Linux container that has Python 3 and Bash installed. If the Python script requires additional packages, it must detect this and install the packages at runtime. -The script must create a JSON file containing the bearer token in a specific format: +The script must create a JSON file containing the Bearer token in a specific format: ```json { @@ -582,7 +485,7 @@ variables: To validate that authentication is working, run an DAST API test and review the job logs and the test API's application logs. See the [overrides section](#overrides) for more information about override commands. -### Configuration files +## Configuration files To get you started quickly, GitLab provides the configuration file [`gitlab-dast-api-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/dast/-/blob/master/config/gitlab-dast-api-config.yml). @@ -590,12 +493,12 @@ This file has several testing profiles that perform various numbers of tests. Th profile increases as the test numbers go up. To use a configuration file, add it to your repository's root as `.gitlab/gitlab-dast-api-config.yml`. -#### Profiles +### Profiles The following profiles are pre-defined in the default configuration file. Profiles can be added, removed, and modified by creating a custom configuration. -##### Quick +#### Quick - Application Information Check - Cleartext Authentication Check @@ -610,7 +513,7 @@ can be added, removed, and modified by creating a custom configuration. - Token Check - XML Injection Check -##### Full +#### Full - Application Information Check - Cleartext AuthenticationCheck @@ -630,17 +533,24 @@ can be added, removed, and modified by creating a custom configuration. - Token Check - XML Injection Check -### Available CI/CD variables +## Available CI/CD variables | CI/CD variable | Description | |------------------------------------------------------|--------------------| -| `DAST_API_VERSION` | Specify DAST API container version. Defaults to `latest`. | +| `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | +| `DAST_API_VERSION` | Specify DAST API container version. Defaults to `1`. | +| `DAST_API_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | |[`DAST_API_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | +|[`DAST_API_EXCLUDE_URLS`](#exclude-urls) | Exclude API URL from testing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. | +|[`DAST_API_EXCLUDE_PARAMETER_ENV`](#exclude-parameters) | JSON string containing excluded parameters. | +|[`DAST_API_EXCLUDE_PARAMETER_FILE`](#exclude-parameters) | Path to a JSON file containing excluded parameters. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`DAST_API_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | +|[`DAST_API_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | @@ -656,7 +566,7 @@ can be added, removed, and modified by creating a custom configuration. |`DAST_API_SERVICE_START_TIMEOUT` | How long to wait for target API to become available in seconds. Default is 300 seconds. | |`DAST_API_TIMEOUT` | How long to wait for API responses in seconds. Default is 30 seconds. | -### Overrides +## Overrides DAST API provides a method to add or override specific items in your request, for example: @@ -814,7 +724,7 @@ It is changed to: You can provide this JSON document as a file or environment variable. You may also provide a command to generate the JSON document. The command can run at intervals to support values that expire. -#### Using a file +### Using a file To provide the overrides JSON as a file, the `DAST_API_OVERRIDES_FILE` CI/CD variable is set. The path is relative to the job current working directory. @@ -834,7 +744,7 @@ variables: DAST_API_OVERRIDES_FILE: dast-api-overrides.json ``` -#### Using a CI/CD variable +### Using a CI/CD variable To provide the overrides JSON as a CI/CD variable, use the `DAST_API_OVERRIDES_ENV` variable. This allows you to place the JSON as variables that can be masked and protected. @@ -872,7 +782,7 @@ variables: DAST_API_OVERRIDES_ENV: $SECRET_OVERRIDES ``` -#### Using a command +### Using a command If the value must be generated or regenerated on expiration, you can provide a program or script for the DAST API scanner to execute on a specified interval. The provided command runs in an Alpine Linux @@ -914,7 +824,7 @@ variables: DAST_API_OVERRIDES_INTERVAL: 300 ``` -#### Debugging overrides +### Debugging overrides > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. @@ -965,10 +875,10 @@ def get_auth_response(): # In our example, access token is retrieved from a given endpoint try: - # Performs a http request, response sample: + # Performs a http request, response sample: # { "Token" : "b5638ae7-6e77-4585-b035-7d9de2e3f6b3" } response = get_auth_response() - + # Check that the request is successful. may raise `requests.exceptions.HTTPError` response.raise_for_status() @@ -995,7 +905,7 @@ except Exception as e: logging.error(f'Error, unknown error while retrieving access token. Error message: {e}') raise -# computes object that holds overrides file content. +# computes object that holds overrides file content. # It uses data fetched from request overrides_data = { "headers": { @@ -1070,7 +980,7 @@ variables: In the previous sample, you could use the script `user-pre-scan-set-up.sh` to also install new runtimes or applications that later on you could use in our overrides command. -### Exclude Paths +## Exclude Paths > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. @@ -1088,7 +998,7 @@ To verify the paths are excluded, review the `Tested Operations` and `Excluded O 2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ ``` -#### Examples +### Examples This example excludes the `/auth` resource. This does not exclude child resources (`/auth/child`). @@ -1111,6 +1021,294 @@ variables: DAST_API_EXCLUDE_PATHS=/auth*;/v1/* ``` +### Exclude parameters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. + +While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters, you can set one of the following variables: `DAST_API_EXCLUDE_PARAMETER_ENV` or `DAST_API_EXCLUDE_PARAMETER_FILE`. + +The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre script using `DAST_API_PRE_SCRIPT`. + +#### Exclude parameters using a JSON document + +The JSON document contains a JSON object, this object uses specific properties to identify which parameter should be excluded. +You can provide the following properties to exclude specific parameters during the scanning process: + +- `headers`: Use this property to exclude specific headers. The property's value is an array of header names to be excluded. Names are case-insensitive. +- `cookies`: Use this property's value to exclude specific cookies. The property's value is an array of cookie names to be excluded. Names are case-sensitive. +- `query`: Use this property to exclude specific fields from the query string. The property's value is an array of field names from the query string to be excluded. Names are case-sensitive. +- `body-form`: Use this property to exclude specific fields from a request that uses the media type `application/x-www-form-urlencoded`. The property's value is an array of the field names from the body to be excluded. Names are case-sensitive. +- `body-json`: Use this property to exclude specific JSON nodes from a request that uses the media type `application/json`. The property's value is an array, each entry of the array is a [JSON Path](https://goessner.net/articles/JsonPath/) expression. +- `body-xml`: Use this property to exclude specific XML nodes from a request that uses media type `application/xml`. The property's value is an array, each entry of the array is a [XPath v2](https://www.w3.org/TR/xpath20/) expression. + +Thus, the following JSON document is an example of the expected structure to exclude parameters. + +```json +{ + "headers": [ + "header1", + "header2" + ], + "cookies": [ + "cookie1", + "cookie2" + ], + "query": [ + "query-string1", + "query-string2" + ], + "body-form": [ + "form-param1", + "form-param2" + ], + "body-json": [ + "json-path-expression-1", + "json-path-expression-2" + ], + "body-xml" : [ + "xpath-expression-1", + "xpath-expression-2" + ] +} +``` + +#### Examples + +##### Excluding a single header + +To exclude the header `Upgrade-Insecure-Requests`, set the `header` property's value to an array with the header name: `[ "Upgrade-Insecure-Requests" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Upgrade-Insecure-Requests" ] +} +``` + +Header names are case-insensitive, so the header name `UPGRADE-INSECURE-REQUESTS` is equivalent to `Upgrade-Insecure-Requests`. + +##### Excluding both a header and two cookies + +To exclude the header `Authorization`, and the cookies `PHPSESSID` and `csrftoken`, set the `headers` property's value to an array with header name `[ "Authorization" ]` and the `cookies` property's value to an array with the cookies' names `[ "PHPSESSID", "csrftoken" ]`. For instance, the JSON document looks like this: + +```json +{ + "headers": [ "Authorization" ], + "cookies": [ "PHPSESSID", "csrftoken" ] +} +``` + +##### Excluding a `body-form` parameter + +To exclude the `password` field in a request that uses `application/x-www-form-urlencoded`, set the `body-form` property's value to an array with the field name `[ "password" ]`. For instance, the JSON document looks like this: + +```json +{ + "body-form": [ "password" ] +} +``` + +The exclude parameters uses `body-form` when the request uses a content type `application/x-www-form-urlencoded`. + +##### Excluding a specific JSON nodes using JSON Path + +To exclude the `schema` property in the root object, set the `body-json` property's value to an array with the JSON Path expression `[ "$.schema" ]`. + +The JSON Path expression uses special syntax to identify JSON nodes: `$` refers to the root of the JSON document, `.` refers to the current object (in our case the root object), and the text `schema` refers to a property name. Thus, the JSON path expression `$.schema` refers to a property `schema` in the root object. +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.schema" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding multiple JSON nodes using JSON Path + +To exclude the property `password` on each entry of an array of `users` at the root level, set the `body-json` property's value to an array with the JSON Path expression `[ "$.users[*].paswword" ]`. + +The JSON Path expression starts with `$` to refer to the root node and uses `.` to refer to the current node. Then, it uses `users` to refer to a property and the characters `[` and `]` to enclose the index in the array you want to use, instead of providing a number as an index you use `*` to specify any index. After the index reference, we find `.` which now refers to any given selected index in the array, preceded by a property name `password`. + +For instance, the JSON document looks like this: + +```json +{ + "body-json": [ "$.users[*].paswword" ] +} +``` + +The exclude parameters uses `body-json` when the request uses a content type `application/json`. Each entry in `body-json` is expected to be a [JSON Path expression](https://goessner.net/articles/JsonPath/). In JSON Path characters like `$`, `*`, `.` among others have special meaning. + +##### Excluding a XML attribute + +To exclude an attribute named `isEnabled` located in the root element `credentials`, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/@isEnabled" ]`. + +The XPath expression `/credentials/@isEnabled`, starts with `/` to indicate the root of the XML document, then it is followed by the word `credentials` which indicates the name of the element to match. It uses a `/` to refer to a node of the previous XML element, and the character `@` to indicate that the name `isEnable` is an attribute. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/@isEnabled" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding a XML text's element + +To exclude the text of the `username` element contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username/text()" ]`. + +In the XPath expression `/credentials/username/text()`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. Last part has a `/` that refers to the current element, and uses a XPath function called `text()` which identifies the text of the current element. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username/text()" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML element + +To exclude the element `username` contained in root node `credentials`, set the `body-xml` property's value to an array with the XPath expression `[/credentials/username" ]`. + +In the XPath expression `/credentials/username`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `username`. + +For instance, the JSON document looks like this: + +```json +{ + "body-xml": [ + "/credentials/username" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be a [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +##### Excluding an XML node with namespaces + +To exclude anXML element `login` which is defined in namespace `s`, and contained in `credentials` root node, set the `body-xml` property's value to an array with the XPath expression `[ "/credentials/s:login" ]`. + +In the XPath expression `/credentials/s:login`, the first character `/` refers to the root XML node, and then after it indicates an XML element's name `credentials`. Similarly, the character `/` refers to the current element, followed by a new XML element's name `s:login`. Notice that name contains the character `:`, this character separates the namespace from the node name. + +The namespace name should have been defined in the XML document which is part of the body request. You may check the namespace in the specification document HAR, OpenAPI, or Postman Collection file. + +```json +{ + "body-xml": [ + "/credentials/s:login" + ] +} +``` + +The exclude parameters uses `body-xml` when the request uses a content type `application/xml`. Each entry in `body-xml` is expected to be an [XPath v2 expression](https://www.w3.org/TR/xpath20/). In XPath, expressions characters like `@`, `/`, `:`, `[`, `]` among others have special meanings. + +#### Using a JSON string + +To provide the exclusion JSON document set the variable `DAST_API_EXCLUDE_PARAMETER_ENV` with the JSON string. In the following example, the `.gitlab-ci.yml`, the `DAST_API_EXCLUDE_PARAMETER_ENV` variable is set to a JSON string: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_EXCLUDE_PARAMETER_ENV: '{ "headers": [ "Upgrade-Insecure-Requests" ] }' +``` + +#### Using a file + +To provide the exclusion JSON document set the variable `DAST_API_EXCLUDE_PARAMETER_FILE` with the JSON file path. The file path is relative to the job current working directory. In the following example `.gitlab-ci.yml` content, the `DAST_API_EXCLUDE_PARAMETER_FILE` variable is set to a JSON file path: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_EXCLUDE_PARAMETER_FILE: dast-api-exclude-parameters.json +``` + +The `dast-api-exclude-parameters.json` is a JSON document that follows the structure of [exclude parameters document](#exclude-parameters-using-a-json-document). + +### Exclude URLS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. + +As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` will exclude all URLs because it is a regular expression that matches everything. + +In your job output you can check if any URLs matched any provided regular expression from `DAST_API_EXCLUDE_URLS`. Matching operations are listed in the **Excluded Operations** section. Operations listed in the **Excluded Operations** should not be listed in the **Tested Operations** section. For example the following portion of a job output: + +```plaintext +2021-05-27 21:51:08 [INF] API Security: --[ Tested Operations ]------------------------- +2021-05-27 21:51:08 [INF] API Security: 201 POST http://target:7777/api/users CREATED +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +2021-05-27 21:51:08 [INF] API Security: --[ Excluded Operations ]----------------------- +2021-05-27 21:51:08 [INF] API Security: GET http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: POST http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +``` + +NOTE: +Each value in `DAST_API_EXCLUDE_URLS` is a regular expression. Characters such as `.` , `*` and `$` among many others have special meanings in [regular expressions](https://en.wikipedia.org/wiki/Regular_expression#Standards). + +#### Examples + +##### Excluding a URL and child resources + +The following example excludes the URL `http://target/api/auth` and its child resources. + +```yaml +variables: + DAST_API_EXCLUDE_URLS: http://target/api/auth +``` + +##### Excluding two URLs and allow their child resources + +To exclude the URLs `http://target/api/buy` and `http://target/api/sell` but allowing to scan their child resources, for instance: `http://target/api/buy/toy` or `http://target/api/sell/chair`. You could use the value `http://target/api/buy/$,http://target/api/sell/$`. This value is using two regular expressions, each of them separated by a `,` character. Hence, it contains `http://target/api/buy$` and `http://target/api/sell$`. In each regular expression, the trailing `$` character points out where the matching URL should end. + +```yaml +variables: + DAST_API_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$ +``` + +##### Excluding two URLs and their child resources + +In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: + +```yaml +variables: + DAST_API_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell +``` + +##### Excluding URL using regular expressions + +In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. + +```yaml +variables: + DAST_API_EXCLUDE_URLS: https://target/api/v.*/user/create$ +``` + ## Running your first scan When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During normal operation, the job always succeeds even if vulnerabilities are identified during testing. @@ -1165,7 +1363,7 @@ pipelines. For more information, see the [Security Dashboard documentation](../s Once a vulnerability is found, you can interact with it. Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). -## Handling False Positives +### Handling False Positives False positives can be handled in several ways: @@ -1177,7 +1375,7 @@ False positives can be handled in several ways: - Turn off the Check producing the false positive. This prevents the check from generating any vulnerabilities. Example checks are the SQL Injection Check, and JSON Hijacking Check. -### Turn off a Check +#### Turn off a Check 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 @@ -1235,7 +1433,7 @@ This results in the following YAML: - Name: XmlInjectionCheck ``` -### Turn off an Assertion for a Check +#### Turn off an Assertion for a Check Assertions detect vulnerabilities in tests produced by checks. Many checks support multiple Assertions such as Log Analysis, Response Analysis, and Status Code. When a vulnerability is found, the Assertion used is provided. To identify which Assertions are on by default, see the Checks default configuration in the configuration file. The section is called `Checks`. @@ -1419,6 +1617,19 @@ API Security can still try to consume an OpenAPI document that does not fully co DAST_API_OPENAPI_RELAXED_VALIDATION: On ``` +### No operation in the OpenAPI document is consuming any supported media type + +API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. + +**Error message** + +- In [GitLab 14.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/333304), `Error, no operation in the OpenApi document is consuming any supported media type. Check 'OpenAPI Specification' to check the supported media types.` + +**Solution** + +1. Review supported media types in the [OpenAPI Specification](#openapi-specification) section. +1. Edit your OpenAPI document, allowing at least a given operation to accept any of the supported media types. Alternatively, a supported media type could be set in the OpenAPI document level and get applied to all operations. This step may require changes in your application to ensure the supported media type is accepted by the application. + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a4a7e6703ab..924e3838d91 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -321,13 +321,13 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Package Manager | Supported File Format Versions | Tested Versions | | ------ | ------ | ------ | -| Bundler | N/A | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| Composer | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/tests/php-composer/-/blob/master/composer.lock) | -| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/c-conan/-/blob/master/conan.lock) | -| Go | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/tests/go-modules/-/blob/master/go.mod) | -| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/tests/csharp-nuget-dotnetcore/-/blob/master/src/web.api/packages.lock.json#L2) | -| npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/master/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/blob/lockfile-v2-FREEZE/package-lock.json#L4) | -| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/tests/js-yarn/-/blob/master/yarn.lock) | +| Bundler | N/A | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/main/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| Composer | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/main/composer.lock) | +| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/main/conan.lock) | +| Go | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/main/go.sum) | +| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/main/src/web.api/packages.lock.json#L2) | +| npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/main/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4) | +| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/main/yarn.lock#L2) | #### Obtaining dependency information by running a package manager to generate a parsable file @@ -339,19 +339,19 @@ To support the following package managers, the GitLab analyzers proceed in two s | Package Manager | Pre-installed Versions | Tested Versions | | ------ | ------ | ------ | | Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L330), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L339), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L348), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L357), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L366), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L384) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L289-297)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3), [7.3](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-7-3/gradle/wrapper/gradle-wrapper.properties#L3), [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L299-317)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup> | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | -| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | -| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-4">4</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | +| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L443-447), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L449-453), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L455-459), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L461-465), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L467-471), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L473-477), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L479-483) | +| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L319-323), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L286-288)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L331-335), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L300-302)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup> | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L224-247) | +| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L77-91) | +| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L168-191)<sup><b><a href="#exported-dependency-information-notes-4">4</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L143-166) | <!-- markdownlint-disable MD044 --> <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> - The pre-installed version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a>. + The pre-installed and tested version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a>. </p> </li> <li> @@ -508,19 +508,18 @@ always take the latest dependency scanning artifact available. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/282533) in GitLab 14.1. > - [Feature flag sec_dependency_scanning_ui_enable removed](https://gitlab.com/gitlab-org/gitlab/-/issues/326005) in GitLab 14.2. -To enable Dependency Scanning in a project, you can create a merge request -from the Security Configuration page. +To enable Dependency Scanning in a project, you can create a merge request: -1. In the project where you want to enable Dependency Scanning, navigate to - **Security & Compliance > Configuration**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dependency Scanning** row, select **Configure with a merge request**. +1. Review and merge the merge request to enable Dependency Scanning. -This automatically creates a merge request with the changes necessary to enable Dependency Scanning -that you can review and merge to complete the configuration. +Pipelines now include a dependency scanning job. ### Customizing the dependency scanning settings -The dependency scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the +The Dependency Scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. For example: @@ -580,6 +579,7 @@ The following variables allow configuration of global dependency scanning settin | `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_DEFAULT_ANALYZERS` | ([**DEPRECATED - use `DS_EXCLUDED_ANALYZERS` instead**](https://gitlab.com/gitlab-org/gitlab/-/issues/287691)) Override the names of the official default images. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | +| `DS_IMAGE_SUFFIX` | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info`. | @@ -660,6 +660,40 @@ you can use the `MAVEN_CLI_OPTS` CI/CD variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repositories). +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10. + +GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the Gemnasium images. You can therefore replace standard images with FIPS-enabled images. + +To use FIPS-enabled images, set the `DS_IMAGE_SUFFIX` to `-fips`, +and set `DS_EXCLUDED_ANALYZERS` to `bundler-audit, retire.js` +to exclude the analyzers that don't support FIPS. + +```yaml +variables: + DS_IMAGE_SUFFIX: "-fips" + DS_EXCLUDED_ANALYZERS: "bundler-audit, retire.js" +``` + +If you want to execute `bundler-audit` or `retire.js` in your project pipeline, you can override the +Gemnasium scanning jobs, and set `DS_IMAGE_SUFFIX` to `-fips` only for those jobs. + +```yaml +gemnasium-dependency_scanning: + variables: + DS_IMAGE_SUFFIX: "-fips" + +gemnasium-maven-dependency_scanning: + variables: + DS_IMAGE_SUFFIX: "-fips" + +gemnasium-python-dependency_scanning: + variables: + DS_IMAGE_SUFFIX: "-fips" +``` + ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to @@ -890,7 +924,7 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s ## Contributing to the vulnerability database You can search the [`gemnasium-db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project -to find a vulnerability in the Gemnasium database. +to find a vulnerability in the GitLab Advisory Database. You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). ## Running dependency scanning in an offline environment @@ -1237,3 +1271,24 @@ analyzers, edit your `gitlab-ci.yml` file and either: For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to `"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"`. + +### Dependency Scanning of setuptools project fails with `use_2to3 is invalid` error + +Support for [2to3](https://docs.python.org/3/library/2to3.html) +was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) +in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` +version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on +`lib2to3` will fail with this message: + +```plaintext +error in <dependency name> setup command: use_2to3 is invalid +``` + +To work around this error, downgrade the analyzer's version of `setuptools` (e.g. `v57.5.0`): + +```yaml +gemnasium-python-dependency_scanning: + before_script: + - pip install setuptools==57.5.0 + image: registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python:2-python-3.9 +``` diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index b72f54b4493..35968a6361f 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -41,9 +41,31 @@ GitLab IaC scanning supports a variety of IaC configuration files. Our IaC secur | Google Deployment Manager | [KICS](https://kics.io/) | 14.5 | | Kubernetes | [KICS](https://kics.io/) | 14.5 | | OpenAPI | [KICS](https://kics.io/) | 14.5 | -| Terraform | [KICS](https://kics.io/) | 14.5 | +| Terraform <sup>2</sup> | [KICS](https://kics.io/) | 14.5 | 1. IaC scanning can analyze Azure Resource Manager templates in JSON format. If you write templates in the [Bicep](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview) language, you must use [the bicep CLI](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli) to convert your Bicep files into JSON before GitLab IaC scanning can analyze them. +1. Terraform modules in a custom registry are not scanned for vulnerabilities. You can follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/357004) for the proposed feature. + +### Supported distributions + +GitLab scanners are provided with a base alpine image for size and maintainability. + +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. + +GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the images. You can therefore replace standard images with FIPS-enabled +images. To configure the images, set the `SAST_IMAGE_SUFFIX` to `-fips` or modify the +standard tag plus the `-fips` extension. + +```yaml +variables: + SAST_IMAGE_SUFFIX: '-fips' + +include: + - template: Security/SAST-IaC.latest.gitlab-ci.yml +``` ### Making IaC analyzers available to all GitLab tiers @@ -54,13 +76,13 @@ All open source (OSS) analyzers are available with the GitLab Free tier. Future Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | -|:---------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure IaC Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in merge request | **{dotted-circle}** | **{check-circle}** | -| [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free & Premium | In Ultimate | +|:----------------------------------------------------------------|:--------------------|:-------------------| +| [Configure IaC scanner](#configuration) | **{check-circle}** | **{check-circle}** | +| Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -92,15 +114,14 @@ that you can download and analyze. ### Enable IaC Scanning via an automatic merge request -To enable IaC Scanning in a project, you can create a merge request -from the Security Configuration page: +To enable IaC Scanning in a project, you can create a merge request: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. +1. Review and merge the merge request to enable IaC Scanning. -This automatically creates a merge request with the changes necessary to enable IaC Scanning -that you can review and merge to complete the configuration. +Pipelines now include an IaC job. ## Reports JSON format diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index ff548f1d29f..3a6aa8e3485 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -52,7 +52,7 @@ The following vulnerability scanners and their databases are regularly updated: | Secure scanning tool | Vulnerabilities database updates | |:----------------------------------------------------------------|:---------------------------------| | [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. For more details, see [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database-update). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Security Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | @@ -218,7 +218,7 @@ security issues: WARNING: This feature is in its end-of-life process. It is [deprecated](../../update/deprecations.md#vulnerability-check) -for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new +in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new [Security Approval Policies](policies/scan-result-policies.md). To prevent a merge request introducing a security vulnerability in a project, enable the @@ -381,6 +381,12 @@ Learn more on overriding security jobs: All the security scanning tools define their stage, so this error can occur with all of them. +## Self managed installation options + +For self managed installations, you can choose to run most of the GitLab security scanners even when [not connected to the internet](offline_deployments/index.md). + +Self managed installations can also run the security scanners on a GitLab Runner [running inside OpenShift](../../install/openshift_and_gitlab/index.md). + ## Security report validation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. @@ -474,6 +480,7 @@ GitLab provides two methods of accomplishing this, each with advantages and disa - [Compliance framework pipelines](../project/settings/#compliance-pipeline-configuration) are recommended when: + - Scan execution enforcement is required for SAST or Secret Detection scans that use custom rulesets. - Scan execution enforcement is required for SAST IaC, Dependency Scanning, License Compliance, API Fuzzing, or Coverage-guided Fuzzing. - Scan execution enforcement is required for scanners external to GitLab. @@ -482,9 +489,18 @@ GitLab provides two methods of accomplishing this, each with advantages and disa - [Scan execution policies](policies/scan-execution-policies.md) are recommended when: - - Scan execution enforcement is required for DAST, SAST, Secret Detection, or Container Scanning. + - Scan execution enforcement is required for DAST. + - Scan execution enforcement is required for Container Scanning with project-specific variable + customizations. To accomplish this, users must create a separate security policy per project. - Scans are required to run on a regular, scheduled cadence. +- Either solution can be used equally well when: + + - Scan execution enforcement is required for SAST or Secret Detection when custom rulesets are not + used. + - Scan execution enforcement is required for Container Scanning with no project-specific variable + customizations. + Additional details about the differences between the two solutions are outlined below: | | Compliance Framework Pipelines | Scan Execution Policies | diff --git a/doc/user/application_security/policies/img/association_diagram.png b/doc/user/application_security/policies/img/association_diagram.png Binary files differnew file mode 100644 index 00000000000..d082e297c68 --- /dev/null +++ b/doc/user/application_security/policies/img/association_diagram.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 8a39220da35..81d24104340 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -21,6 +21,56 @@ GitLab supports the following security policies: - [Scan Result Policy](scan-result-policies.md) - [Container Network Policy](#container-network-policy) (DEPRECATED) +## Security policy project + +All security policies are stored as YAML in a separate security policy project that gets linked to +the development project. This association can be a one-to-many relationship, allowing one security +policy project to apply to multiple development projects. Linked projects are not required to be in +the same group as the development projects to which they are linked. + + + +Although it is possible to have one project linked to itself and to serve as both the development +project and the security policy project, this is not recommended. Keeping the security policy +project separate from the development project allows for complete separation of duties between +security/compliance teams and development teams. + +All security policies are stored in the `.gitlab/security-policies/policy.yml` YAML file inside the +linked security policy project. The format for this YAML is specific to the type of policy that is +stored there. Examples and schema information are available for the following policy types: + +- [Scan execution policy](scan-execution-policies.md#example-security-policies-project) +- [Scan result policy](scan-result-policies.md#example-security-scan-result-policies-project) + +Policies created in this project are applied through a background job that runs once every 10 +minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. + +### Managing the linked security policy project + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select, edit, and unlink a security policy project. + +As a project owner, take the following steps to create or edit an association between your current +project and a project that you would like to designate as the security policy project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Select **Edit Policy Project**, and search for and select the + project you would like to link from the dropdown menu. +1. Select **Save**. + +To unlink a security policy project, follow the same steps but instead select the trash can icon in +the modal. + + + +### Viewing the linked security policy project + +All users who have access to the project policy page and are not project owners will instead view a +button linking out to the associated security policy project. If no security policy project has been +associated then the linking button does not appear. + ## Policy management The Policies page displays deployed @@ -57,6 +107,7 @@ You can use the policy editor to create, edit, and delete policies: 1. On the top bar, select **Menu > Projects** and find your group. 1. On the left sidebar, select **Security & Compliance > Policies**. - To create a new policy, select **New policy** which is located in the **Policies** page's header. + You can then select which type of policy to create. - To edit an existing policy, select **Edit policy** in the selected policy drawer. The policy editor has two modes: @@ -78,44 +129,12 @@ by the Rule mode, Rule mode is automatically disabled. If the YAML is incorrect, you must use YAML mode to fix your policy before Rule mode is available again. -## Security Policies project - -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. - -The Security Policies feature is a repository to store policies. All security policies are stored in -the `.gitlab/security-policies/policy.yml` YAML file. The format for this YAML is specific to the type of policy that is being stored there. Examples and schema information are available for the following policy types: - -- [Scan execution policy](scan-execution-policies.md#example-security-policies-project) -- [Scan result policy](scan-result-policies.md#example-security-scan-result-policies-project) - -Policies created in this project are applied through a background job that runs once every 10 -minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. - -## Security Policy project selection - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. - -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: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Policies**. -1. Select **Edit Policy Project**, and search for and select the - project you would like to link from the dropdown menu. -1. Select **Save**. - -  - -### Unlink Security Policy projects - -Project owners can unlink Security Policy projects from development projects. To do this, follow -the steps described in [Security Policy project selection](#security-policy-project-selection), -but select the trash can icon in the modal. +When you finish creating or editing your policy, save and apply it by selecting the +**Configure with a merge request** button and then merging the resulting merge request. When you +press this button, the policy YAML is validated and any resulting errors are displayed. +Additionally, if you are a project owner and a security policy project has not been previously +associated with this project, then a new project is created and associated automatically at the same +time that the first policy merge request is created. ## Scan execution policies @@ -132,7 +151,7 @@ See [Scan result policies](scan-result-policies.md). WARNING: Container Network Policy is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. The **Container Network Policy** section provides packet flow metrics for diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index c3778ac97de..7e8e60768b9 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -132,8 +132,8 @@ Note the following: ## Example security policies project -You can use this example in a `.gitlab/security-policies/policy.yml`, as described in -[Security policies project](index.md#security-policies-project). +You can use this example in a `.gitlab/security-policies/policy.yml` file stored in a +[security policy project](index.md#security-policy-project): ```yaml --- diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 8215316bcab..d2cce207bfd 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -65,7 +65,7 @@ This rule enforces the defined actions based on the information provided. | `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | | `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. The `newly_detected` state considers all newly detected vulnerabilities regardless of their status or dismissal. The other states consider findings that match the selected state and already exist in the default branch. | ## `require_approval` action type @@ -90,8 +90,8 @@ Requirements and limitations: ## Example security scan result policies project -You can use this example in a `.gitlab/security-policies/policy.yml`, as described in -[Security policies project](index.md#security-policies-project): +You can use this example in a `.gitlab/security-policies/policy.yml` file stored in a +[security policy project](index.md#security-policy-project): ```yaml --- diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index d3a79410eea..8f006f258b6 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -81,6 +81,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Go | [Semgrep](https://semgrep.dev) | 14.4 | | 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 (any build system) | [Semgrep](https://semgrep.dev) | 14.10 | | 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 | @@ -132,6 +133,30 @@ The following analyzers have multi-project support: Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). +### Supported distributions + +The default scanner images are build off a base Alpine image for size and maintainability. + +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. + +GitLab offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the images that are FIPS-enabled. To use the FIPS-enabled images, you can either: + +- Set the `SAST_IMAGE_SUFFIX` to `-fips`. +- Add the `-fips` extension to the default image name. + +For example: + +```yaml +variables: + SAST_IMAGE_SUFFIX: '-fips' + +include: + - template: Security/SAST.gitlab-ci.yml +``` + ### Making SAST analyzers available to all GitLab tiers All open source (OSS) analyzers have been moved to the GitLab Free tier as of GitLab 13.3. @@ -141,17 +166,17 @@ All open source (OSS) analyzers have been moved to the GitLab Free tier as of Gi Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | -|:---------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | -| [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | -| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | -| [False Positive Detection](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free & Premium | In Ultimate | +|:----------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | +| Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | +| [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -190,28 +215,28 @@ always take the latest SAST artifact available. ### Configure SAST in the UI You can enable and configure SAST in the UI, either with default settings, or with customizations. -Use the method that best meets your needs. +The method you can use depends on your GitLab license tier. -- [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings) -- [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations) +- [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings). +- [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations). **(ULTIMATE)** ### Configure SAST in the UI with default settings > [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + To enable and configure SAST with default settings: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance** > **Configuration**. -1. In the SAST section, select `Enable via MR`. -1. Review the draft MR that enables SAST with the default recommended settings in the - `.gitlab-ci.yml` file. -1. Merge the MR to enable SAST. You should see SAST jobs run in that MR's pipeline. +1. In the SAST section, select **Configure with a merge request**. +1. Review and merge the merge request to enable SAST. -NOTE: -The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal -configuration file. If you have a complex GitLab configuration file it may not be parsed -successfully, and an error may occur. +Pipelines now include a SAST job. ### Configure SAST in the UI with customizations **(ULTIMATE)** @@ -219,27 +244,28 @@ successfully, and an error may occur. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab 13.4. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab 13.5. +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + To enable and configure SAST with customizations: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. -1. If the project does not have a `.gitlab-ci.yml` file, select **Enable** in the Static Application - Security Testing (SAST) row, otherwise select **Configure**. +1. If the project does not have a `.gitlab-ci.yml` file, select **Enable SAST** in the Static + Application Security Testing (SAST) row, otherwise select **Configure SAST**. 1. Enter the custom SAST values. Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST - Configuration page, their values are left unchanged. Default values are inherited from the GitLab - SAST template. + Configuration page, their values are inherited from the GitLab SAST template. 1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Select **Create Merge Request**. 1. Review and merge the merge request. -NOTE: -The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal -configuration file. If you have a complex GitLab configuration file it may not be parsed -successfully, and an error may occur. +Pipelines now include a SAST job. ### Overriding SAST jobs @@ -399,7 +425,7 @@ and `value` of identifiers and then overridden: ``` If a vulnerability is found with a type `CWE` with a value of `703` then -the vulnerability severity is overwritten to `Critical`. +the vulnerability severity is overwritten to `Critical`. #### Synthesize a custom configuration @@ -523,7 +549,7 @@ Several passthrouh types generate a configuration for the target analyzer: the configuration. - If there is a filename collision between files in both repositories, files from the `sast` repository overwrite files from the `myrules` repository, - as `sast-rules` has higher precedence. + as `sast-rules` has higher precedence. - The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The full path is `/sgrules/insecure.yml`. - The `url` entry fetches a configuration made available through a URL and @@ -831,6 +857,7 @@ The following are Docker image-related CI/CD variables. | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SAST_EXCLUDED_ANALYZERS` | Names of default images that should never run. Read more about [customizing analyzers](analyzers.md). | | `SAST_ANALYZER_IMAGE_TAG` | Override the default version of analyzer image. Read more about [pinning the analyzer image version](#pinning-to-minor-image-version). | +| `SAST_IMAGE_SUFFIX` | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355518) in GitLab 14.10. | #### Vulnerability filters @@ -936,7 +963,7 @@ To use SAST in an offline environment, you need: - A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Configure certificate checking of packages (optional). -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull_policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -990,7 +1017,7 @@ Support for custom certificate authorities was introduced in the following versi | `phpcs-security-audit` | [v2.8.2](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit/-/releases/v2.8.2) | | `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | | `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | -| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/releases/v0.0.1) | +| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/releases/v0.0.1) | | `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | | `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 582497eb465..0a18e7d5f45 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -60,13 +60,14 @@ as shown in the following table: | Capability | In Free & Premium | In Ultimate | |:----------------------------------------------------------------|:--------------------|:-------------------| -| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in merge request | **{dotted-circle}** | **{check-circle}** | +| [Configure Secret Detection scanner](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize Secret Detection settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | +| Download [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | +| See new findings in the merge request widget | **{dotted-circle}** | **{check-circle}** | | View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** | **{check-circle}** | -| [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Configuration @@ -107,25 +108,48 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. +### Supported distributions + +The default scanner images are build off a base Alpine image for size and maintainability. + +#### FIPS-enabled images + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. + +GitLab offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the images that are FIPS-enabled. To use the FIPS-enabled images, you can either: + +- Set the `SAST_IMAGE_SUFFIX` to `-fips`. +- Add the `-fips` extension to the default image name. + +For example: + +```yaml +variables: + SECRET_DETECTION_IMAGE_SUFFIX: '-fips' + +include: + - template: Security/Secret-Detection.gitlab-ci.yml +``` + ### Enable Secret Detection via an automatic merge request > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, deployed behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1. -To enable Secret Detection in a project, you can create a merge request -from the Security Configuration page. +NOTE: +This method works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration +file. If you have a complex GitLab configuration file it may not be parsed successfully, and an +error may occur. -1. In the project where you want to enable Secret Detection, go to - **Security & Compliance > Configuration**. -1. In the **Secret Detection** row, select **Configure with a merge request**. +To enable Secret Detection in a project, you can create a merge request: -This automatically creates a merge request with the changes necessary to enable Secret Detection -that you can review and merge to complete the configuration. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **Secret Detection** row, select **Configure with a merge request**. +1. Review and merge the merge request to enable Secret Detection. -NOTE: -The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal -configuration file. If you have a complex GitLab configuration file it may not be parsed -successfully, and an error may occur. +Pipelines now include a Secret Detection job. ### Customizing settings @@ -176,6 +200,7 @@ Secret Detection can be customized by defining available CI/CD variables: | `SECRET_DETECTION_COMMITS` | - | The list of commits that Gitleaks should scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. | | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | +| `SECRET_DETECTION_IMAGE_SUFFIX` | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355519) in GitLab 14.10. | ### Custom rulesets **(ULTIMATE)** diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index a0cfd6d9d77..488ec336646 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -52,6 +52,9 @@ To view vulnerabilities in a pipeline: 1. From the list, select the pipeline you want to check for vulnerabilities. 1. Select the **Security** tab. +**Scan details** shows vulnerabilities introduced by the merge request, in addition to existing vulnerabilities +from the latest successful pipeline in your project's default branch. + A pipeline consists of multiple jobs, such as SAST and DAST scans. If a job fails to finish, the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, @@ -66,7 +69,8 @@ To view the total number of vulnerabilities per scan: 1. Select the **Status** of a branch. 1. Select the **Security** tab. -**Scan details** show the total number of vulnerabilities found per scan in the pipeline. +**Scan details** shows vulnerabilities introduced by the merge request, in addition to existing vulnerabilities +from the latest successful pipeline in your project's default branch. ### Download security scan outputs diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 390882d4326..9b8dd2825ea 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Threat Monitoring is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. The **Threat Monitoring** page provides alerts and metrics diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 0b27760b4bb..18b99e06299 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -28,7 +28,7 @@ On the vulnerability's page, you can: - [Create an issue](#create-an-issue-for-a-vulnerability). - [Link issues to the vulnerability](#linked-issues). - [Resolve a vulnerability](#resolve-a-vulnerability) if a solution is - available. + available. - [View security training specific to the detected vulnerability](#view-security-training-for-a-vulnerability). ## Vulnerability status values diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index eb59c289700..a9cef15e3e8 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -222,12 +222,8 @@ To undo this action, select a different status from the same menu. ## Manually add a vulnerability finding -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. - -FLAG: -This feature is not enabled by default. To make it available, ask an administrator to -[enable the feature flag](../../feature_flags.md) named `new_vulnerability_form`. -On GitLab.com, this feature is not yet available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353796) in GitLab 14.10. To add a new vulnerability finding from your project level Vulnerability Report page: @@ -236,7 +232,7 @@ To add a new vulnerability finding from your project level Vulnerability Report 1. Click on **Submit Vulnerability**. 1. Complete the fields and submit the form. -You will be brought to the newly created vulnerability's detail page. Manually created records appear in the +You will be brought to the newly created vulnerability's detail page. Manually created records appear in the Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. ## Operational vulnerabilities diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 73a8470e025..c15041f6b0d 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -8,6 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. > - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3. > - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. > - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. @@ -69,6 +70,7 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma ``` - The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is. + - You can install additional agents into the same cluster to accommodate additional hierarchies. - You can authorize up to 100 projects. All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. @@ -91,9 +93,11 @@ To authorize the agent to access all of the GitLab projects in a group or subgro ``` - The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is. + - You can install additional agents into the same cluster to accommodate additional hierarchies. + - All of the subgroups of an authorized group also have access to the same agent (without being specified individually). - You can authorize up to 100 groups. -All the projects that belong to the group are now authorized to access the agent. +All the projects that belong to the group and its subgroups are now authorized to access the agent. All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. Choose the context to run `kubectl` commands from your CI/CD scripts. @@ -123,7 +127,7 @@ Run `kubectl config get-contexts`. When you deploy to an environment that has both a [certificate-based cluster](../../infrastructure/clusters/index.md) (deprecated) and an agent connection: -- The certificate-based cluster's context is called `gitlab-deploy`. This context +- The certificate-based cluster's context is called `gitlab-deploy`. This context is always selected by default. - In GitLab 14.9 and later, agent contexts are included in the `KUBECONFIG`. You can select them by using `kubectl config use-context diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 8f0e2255121..e99e3b00ec7 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Using a GitOps workflow for Kubernetes **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. With GitOps, you can manage containerized clusters and applications from a Git repository that: @@ -18,6 +19,8 @@ By combining GitLab, Kubernetes, and GitOps, you can have: - GitLab as the GitOps operator. - Kubernetes as the automation and convergence system. - GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment. +- Built-in automatic drift remediation. +- Resource management with [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/) for transparent multi-actor field management. This diagram shows the repositories and main actors in a GitOps deployment: @@ -90,6 +93,37 @@ gitops: | `prune_propagation_policy` | The deletion propagation policy that [should be used for pruning](https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470). Can be: `orphan`, `background`, or `foreground`. Default is `foreground`. | | `inventory_policy` | Determines whether an inventory object can take over objects that belong to another inventory object or don't belong to any inventory object. This is done by determining if the apply/prune operation can go through for a resource based on comparison of the `inventory-id` value in the package and the `owning-inventory` annotation (`config.k8s.io/owning-inventory`) [in the live object](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66). Can be: `must_match`, `adopt_if_no_inventory`, or `adopt_all`. Default is `must_match`. | +## GitOps annotations + +The GitLab agent for Kubernetes has annotations you can use to: + +- **Sort resources**: Apply or delete resources in a specific order. +- **Use apply-time mutation**: Dynamically substitute fields from one resource configuration to another. + +The agent has [default sorting](https://github.com/kubernetes-sigs/cli-utils/blob/d7d63f4b62897f584ca9e02b6faf4d2f327a9b09/pkg/ordering/sort.go#L74), +but with annotations, you can fine-tune the order and apply time-value injection. + +To provide the GitOps functionality, the GitLab agent for Kubernetes uses the [`cli-utils` library](https://github.com/kubernetes-sigs/cli-utils/), +a Kubernetes SIG project. You can read more about the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md#apply-sort-ordering). + +- [Learn more about apply sort ordering](https://github.com/kubernetes-sigs/cli-utils#apply-sort-ordering). +- [Learn more about apply-time mutation](https://github.com/kubernetes-sigs/cli-utils#apply-time-mutation). + +## Automatic drift remediation + +Drift happens when the current configuration of an infrastructure resource differs from its expected configuration. +Typically, this is caused by manually editing resources directly through the service that created the resource. Minimizing the +risk of drift helps to ensure configuration consistency and successful operations. + +In GitLab, the agent for Kubernetes regularly compares the expected state from the `git` repository with +the known state from the `cluster`. Deviations from the `git` state are fixed at every check. These checks +happen automatically every 5 minutes. They are not configurable. + +The agent uses [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/). +As a result, every field in a resource can have different managers. Only fields managed by `git` +are checked for drift. This facilitates the use of in-cluster controllers to modify resources like +[Horizontal Pod Autoscalers](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). + ## Additional resources The following documentation and examples can help you get started with a GitOps workflow. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index a8ad19df2e1..bab3f3137fe 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -9,12 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in GitLab 13.4. > - Support for `grpcs` [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6. > - Agent server [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program in GitLab 13.10. -> - The agent became available to every project on GitLab.com in GitLab 13.11. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab agent became available on GitLab.com. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab agent for Kubernetes" in GitLab 14.6. You can connect your Kubernetes cluster with GitLab to deploy, manage, -and monitor your cloud-native solutions. +and monitor your cloud-native solutions. To connect a Kubernetes cluster to GitLab, you must first [install an agent in your cluster](install/index.md). @@ -43,8 +43,8 @@ This workflow is considered push-based, because GitLab is pushing requests from GitLab supports the following Kubernetes versions. You can upgrade your Kubernetes version to a supported version at any time: +- 1.21 (support ends on November 22, 2022) - 1.20 (support ends on July 22, 2022) -- 1.19 (support ends on February 22, 2022) GitLab supports at least two production-ready Kubernetes minor versions at any given time. GitLab regularly reviews the supported versions and diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index fca80a4a291..e76ef9e827d 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -39,6 +39,9 @@ To install the agent in your cluster: You must register an agent with GitLab. +FLAG: +In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `certificate_based_clusters` changed the **Actions** menu to focus on the agent rather than certificates. The flag is [enabled on GitLab.com and self-managed](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). + Prerequisites: - For a [GitLab CI/CD workflow](../ci_cd_tunnel.md), ensure that @@ -48,8 +51,7 @@ To register an agent with GitLab: 1. On the top bar, select **Menu > Projects** and find your project. 1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select **Actions**. -1. From the **Select an agent** dropdown list: +1. Select **Connect a cluster (agent)**. - If you want to create a configuration with CI/CD defaults, type a name for the agent. - If you already have an [agent configuration file](#create-an-agent-configuration-file), select it from the list. 1. Select **Register an agent**. @@ -61,11 +63,12 @@ To register an agent with GitLab: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository. > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -You can use an agent configuration file to specify details about your implementation. -Creating a file is optional but is needed if: +The agent is configured through a configuration file. This file is optional. Without a configuration file, you can still use the CI/CD workflow in the project where the agent is registered. + +You need a configuration file if: -- You use [a GitOps workflow](../gitops.md#gitops-configuration-reference) and you want a more advanced configuration. -- You use a GitLab CI/CD workflow. In that workflow, you must [authorize the agent](../ci_cd_tunnel.md#authorize-the-agent). +- You want to use [a GitOps workflow](../gitops.md#gitops-configuration-reference). +- You want to authorize a different project to use the agent for a [GitLab CI/CD workflow](../ci_cd_tunnel.md#authorize-the-agent). To create an agent configuration file, go to the GitLab project. In the repository, create a file called `config.yaml` at this path: @@ -79,104 +82,62 @@ To create an agent configuration file, go to the GitLab project. In the reposito - For a GitOps workflow, view [the configuration reference](../gitops.md#gitops-configuration-reference) for details. - For a GitLab CI/CD workflow, you can leave the file blank for now. -The agent bootstraps with the GitLab installation URL and an access token, -and you provide the rest of the configuration in your repository, following -Infrastructure as Code (IaaC) best practices. - ### Install the agent in the cluster -To connect your cluster to GitLab, install the registered agent -in your cluster. To install it, you can use either: +> Introduced in GitLab 14.10, GitLab recommends using Helm to install the agent. -- [The one-liner installation method](#one-liner-installation). -- [The advanced installation method](#advanced-installation). +To connect your cluster to GitLab, install the registered agent +in your cluster. You can either: -You can use the one-liner installation for trying to use the agent for the first time, to do internal setups with -high trust, and to quickly get started. For long-term production usage, you may want to use the advanced installation -method to benefit from more configuration options. +- [Install the agent with Helm](#install-the-agent-with-helm). +- Or, follow the [advanced installation method](#advanced-installation-method). -#### One-liner installation +If you do not know which one to choose, we recommend starting with Helm. -The one-liner installation is the simplest process, but you need -Docker installed locally. If you don't have it, you can either install -it or opt to the [advanced installation method](#advanced-installation). +#### Install the agent with Helm -To install the agent on your cluster using the one-liner installation: +To install the agent on your cluster using Helm: +1. [Install Helm](https://helm.sh/docs/intro/install/) 1. In your computer, open a terminal and [connect to your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/). -1. Run the command you copied when registering your cluster in the previous step. +1. Run the command you copied when registering your agent with GitLab. -Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation). +Optionally, you can [customize the Helm installation](#customize-the-helm-installation). -##### Customize the one-liner installation +##### Customize the Helm installation -By default, the one-liner command generated by GitLab: +By default, the Helm installation command generated by GitLab: -- Creates a namespace for the deployment (`gitlab-agent`). -- Sets up a service account with `cluster-admin` rights (see [how to restrict this service account](#customize-the-permissions-for-the-agentk-service-account)). -- Creates a `Secret` resource for the agent's access token. +- Creates a namespace `gitlab-agent` for the deployment (`--namespace gitlab-agent`). You can skip creating the namespace by omitting the `--create-namespace` flag. +- Sets up a service account for the agent with `cluster-admin` rights. You can: + - Skip creating the service account by adding `--set serviceAccount.create=false` to the `helm install` command. In this case, you must set `serviceAccount.name` to a pre-existing service account. + - Skip creating the RBAC permissions by adding `--set rbac.create=false` to the `helm install` command. In this case, you must bring your own RBAC permissions for the agent. Otherwise, it has no permissions at all. +- Creates a `Secret` resource for the agent's access token. To instead bring your own secret with a token, omit the token (`--set token=...`) and instead use `--set config.secretName=<your secret name>`. - Creates a `Deployment` resource for the `agentk` pod. -You can edit these parameters to customize the one-liner installation command. -To view all available options, open a terminal and run this command: - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help - -Usage: - cli generate [flags] - -Flags: - --agent-token string Access token registered for agent - --agent-version string Version of the agentk image to use (default "v14.8.1") - -h, --help help for generate - --kas-address string GitLab agent server for Kubernetes address - --name-prefix string The prefix to use for names of Kubernetes objects - --namespace string Kubernetes namespace to create resources in (default "gitlab-agent") - --no-rbac Do not include corresponding Roles and RoleBindings for the agent service account -``` - -WARNING: -Use `--agent-version stable` to refer to the latest stable -release at the time when the command runs. For production, however, -you should explicitly specify a matching version. - -#### Advanced installation - -For advanced installation options, use [the `kpt` installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). - -##### Customize the permissions for the `agentk` service account - -You own your cluster and can grant GitLab the permissions you want. -By default, however, the generated manifests provide `cluster-admin` rights to the agent. - -You can restrict the agent's access rights by using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. - -To restrict permissions: +To see the full list of customizations available, see the Helm chart's [default values file](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/blob/main/values.yaml). -1. Copy the `cluster` directory. -1. Edit the `kustomization.yaml` and `components/*` files based on your requirements. -1. Run `kustomize build <your copied directory> | kubectl apply -f -` to apply your configuration. +#### Advanced installation method -#### Update the advanced installation base layer - -Now you can update from the upstream package by using `kpt pkg update gitlab-agent --strategy resource-merge`. -When the advanced installation setup changes, you will not need to change your custom overlays. +GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users. ## Install multiple agents in your cluster -For total separation between teams, you might need to run multiple `agentk` instances in your cluster. -You might want multiple agents so you can restrict RBAC for every `agentk` deployment. +To install a second agent in your cluster, you can follow the [previous steps](#register-the-agent-with-gitlab) a second time. To avoid resource name collisions within the cluster, you must either: + +- Use a different release name for the agent, e.g. `second-gitlab-agent`: -To install multiple agents, follow the -[advanced installation steps](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent) -a second time and: + ```shell + helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ... + ``` -1. Change the agent name and create a new configuration file. -1. Register the new agent. You receive a new access token. Each token should be used only with one agent. -1. Change the namespace or prefix you use for the installation. +- Or, install the agent in a different namespace, e.g. `different-namespace`: -You should also change the RBAC for the installed `agentk`. + ```shell + helm upgrade --install gitlab-agent gitlab/gitlab-agent \ + --namespace different-namespace \ + ... + ``` ## Example projects @@ -187,50 +148,37 @@ The following example projects can help you get started with the agent. - [Auto DevOps setup that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service) - [Cluster management project template example that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/cluster-management) -## Upgrades and version compatibility - -The agent has two major components: `agentk` and `kas`. -GitLab provides `kas` installers built into the various GitLab installation methods. -The required `kas` version corresponds to the GitLab `major.minor` (X.Y) versions. - -At the same time, `agentk` and `kas` can differ by 1 minor version in either direction. For example, -`agentk` 14.4 supports `kas` 14.3, 14.4, and 14.5 (regardless of the patch). +## Updates and version compatibility -A feature introduced in a given GitLab minor version might work with other `agentk` or `kas` versions. -To ensure it works, use at least the same `agentk` and `kas` minor version. For example, -if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2. - -We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to -[upgrade the `agentk` installations](#update-the-agent-version) after upgrading GitLab. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the agent's list page to update the agent version installed on your cluster. -The available `agentk` and `kas` versions are available in -[the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). +For the best experience, the version of the agent installed in your cluster should match the GitLab major and minor version. The previous minor version is also supported. For example, if your GitLab version is v14.9.4 (major version 14, minor version 9), then versions v14.9.0 and v14.9.1 of the agent are ideal, but any v14.8.x version of the agent is also supported. See [this page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/releases) of releases of the GitLab agent. ### Update the agent version -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the agent's list page to update the agent version installed on your cluster. - -To update the agent's version, re-run the [installation command](#install-the-agent-in-the-cluster) -with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`. -The available `agentk` versions are in [the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc). +To update the agent to the latest version, you can run: -If you don't have access to your agent's access token, you can retrieve it from your cluster: - -1. Open a terminal and connect to your cluster. -1. To retrieve the namespace, run: +```shell +helm repo update +helm upgrade --install gitlab-agent gitlab/gitlab-agent \ + --namespace gitlab-agent \ + --reuse-values +``` - ```shell - kubectl get namespaces - ``` +To set a specific version, you can override the `image.tag` value. For example, to install version `v14.9.1`, run: -1. To retrieve the secret, run: +```shell +helm upgrade gitlab-agent gitlab/gitlab-agent \ + --namespace gitlab-agent \ + --reuse-values \ + --set image.tag=v14.9.1 +``` - ```shell - kubectl -n <namespace> get secrets - ``` +## Uninstall the agent -1. To retrieve the access token, run: +If you [installed the agent with Helm](#install-the-agent-with-helm), then you can also uninstall with Helm. For example, if the release and namespace are both called `gitlab-agent`, then you can uninstall the agent using the following command: - ```shell - kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode - ``` +```shell +helm uninstall gitlab-agent \ + --namespace gitlab-agent +``` diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 3f743d34e0a..2087c804e26 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -6,11 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Working with the agent for Kubernetes **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab agent became available on GitLab.com. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3. -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. +Use the following tasks when working with the agent for Kubernetes. ## View your agents @@ -171,7 +167,7 @@ To remove an agent from the UI: WARNING: Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. The agent for Kubernetes also provides an integration with Cilium. This integration provides a simple way to diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index a5e568837ad..c5c7e46c078 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -27,9 +27,8 @@ If you are a GitLab administrator, you can also view the [GitLab agent server lo } ``` -This error is shown if there are some connectivity issues between the address -specified as `kas-address`, and your agent pod. To fix it, make sure that you -specified the `kas-address` correctly. +This error occurs when there are connectivity issues between the `kas-address` +and your agent pod. To fix this issue, make sure the `kas-address` is accurate. ```json { @@ -41,8 +40,8 @@ specified the `kas-address` correctly. } ``` -This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the -`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` +This error occurs when the `kas-address` doesn't include a trailing slash. To fix this issue, make sure that the +`wss` or `ws` URL ends with a trailing slash, like `wss://GitLab.host.tld:443/-/kubernetes-agent/` or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. ## ValidationError(Deployment.metadata) @@ -58,9 +57,10 @@ or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. } ``` -This error is shown if a manifest file is malformed, and Kubernetes can't -create specified objects. Make sure that your manifest files are valid. You -may try using them to create objects in Kubernetes directly for more troubleshooting. +This error occurs when a manifest file is malformed and Kubernetes can't +create the specified objects. Make sure that your manifest files are valid. + +For additional troubleshooting, try to use the manifest files to create objects in Kubernetes directly. ## Error while dialing failed to WebSocket dial: failed to send handshake request @@ -73,16 +73,10 @@ may try using them to create objects in Kubernetes directly for more troubleshoo } ``` -This error is shown if you configured `wss` as `kas-address` on the agent side, -but KAS on the server side is not available via `wss`. To fix it, make sure the +This error occurs when you configured `wss` as `kas-address` on the agent side, +but the agent server is not available at `wss`. To fix this issue, make sure the same schemes are configured on both sides. -It's not possible to set the `grpc` scheme due to the issue -[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the -issue is in progress, directly edit the deployment with the -`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use -`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`. - ## Decompressor is not installed for grpc-encoding ```json @@ -94,8 +88,8 @@ issue is in progress, directly edit the deployment with the } ``` -This error is shown if the version of the agent is newer that the version of KAS. -To fix it, make sure that both `agentk` and KAS use the same versions. +This error occurs when the version of the agent is newer that the version of the agent server (KAS). +To fix it, make sure that both `agentk` and the agent server are the same version. ## Certificate signed by unknown authority @@ -109,9 +103,11 @@ To fix it, make sure that both `agentk` and KAS use the same versions. } ``` -This error is shown if your GitLab instance is using a certificate signed by an internal CA that -is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent -via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it +This error occurs when your GitLab instance is using a certificate signed by an internal +certificate authority that is unknown to the agent. + +To fix this issue, you can present the CA certificate file to the agent +by using a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it will be picked up automatically. For example, if your internal CA certificate is `myCA.pem`: @@ -153,7 +149,7 @@ Then in `resources.yml`: path: myCA.pem ``` -Alternatively, you can mount the certificate file at a different location and include it using the +Alternatively, you can mount the certificate file at a different location and specify it for the `--ca-cert-file` agent parameter: ```yaml @@ -188,5 +184,5 @@ Alternatively, you can mount the certificate file at a different location and in } ``` -This error is shown if the manifest project is not public. To fix it, make sure your manifest project is public or your manifest files -are stored in the agent's configuration repository. +This error occurs when the project where you keep your manifests is not public. To fix it, make sure your project is public or your manifest files +are stored in the repository where the agent is configured. diff --git a/doc/user/compliance/compliance_report/img/failed_icon_v13_3.png b/doc/user/compliance/compliance_report/img/failed_icon_v13_3.png Binary files differdeleted file mode 100644 index c3f386c9dee..00000000000 --- a/doc/user/compliance/compliance_report/img/failed_icon_v13_3.png +++ /dev/null diff --git a/doc/user/compliance/compliance_report/img/success_icon_v13_3.png b/doc/user/compliance/compliance_report/img/success_icon_v13_3.png Binary files differdeleted file mode 100644 index ea6ca924f81..00000000000 --- a/doc/user/compliance/compliance_report/img/success_icon_v13_3.png +++ /dev/null diff --git a/doc/user/compliance/compliance_report/img/warning_icon_v13_3.png b/doc/user/compliance/compliance_report/img/warning_icon_v13_3.png Binary files differdeleted file mode 100644 index 168a7021948..00000000000 --- a/doc/user/compliance/compliance_report/img/warning_icon_v13_3.png +++ /dev/null diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 27783a063da..77dbefa0755 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -9,17 +9,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in GitLab 12.8 as Compliance Dashboard. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/299360) to compliance report in GitLab 14.2. +> - [Replaced](https://gitlab.com/groups/gitlab-org/-/epics/5237) by merge request violations in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `compliance_violations_report`. Disabled by default. +> - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. +> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/5237) in GitLab 14.10. [Feature flag `compliance_violations_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/346266) removed. Compliance report gives you the ability to see a group's merge request activity. It provides a high-level view for all projects in the group. For example, code approved for merging into production. -You can use the report to: +You can use the report to get: -- Get an overview of the latest merge request for each project. -- See if merge requests were approved and by whom. -- See merge request authors. -- See the latest [CI/CD pipeline](../../../ci/pipelines/index.md) result for each merge request. +- A list of compliance violations from all merged merge requests within the group. +- The reason and severity of each compliance violation. +- A link to the merge request that caused each compliance violation. ## View the compliance report for a group @@ -32,8 +34,36 @@ To view the compliance report: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Compliance report**. -NOTE: -The compliance report shows only the latest merge request on each project. +### Severity levels scale + +The following is a list of available violation severity levels, ranked from most to least severe: + +| Icon | Severity level | +|:----------------------------------------------|:---------------| +| **{severity-critical, 18, gl-fill-red-800}** | Critical | +| **{severity-high, 18, gl-fill-red-600}** | High | +| **{severity-medium, 18, gl-fill-orange-400}** | Medium | +| **{severity-low, 18, gl-fill-orange-300}** | Low | +| **{severity-info, 18, gl-fill-blue-400}** | Info | + +### Violation types + +The following is a list of violations that are either: + +- Already available. +- Aren't available, but which we are tracking in issues. + +| Violation | Severity level | Category | Description | Availability | +|:-------------------------------------|:----------------|:---------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------| +| Author approved merge request | High | [Separation of duties](#separation-of-duties) | The author of the merge request approved their own merge request. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | The committers of the merge request approved the merge request they contributed to. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | The merge request was merged with fewer than two approvals. [Learn more](../../project/merge_requests/approvals/rules.md). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | The merge requests pipeline failed and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | The merge request pipeline passed with warnings and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down more than 10% | High | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of more than 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down less than 1% | Info | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of less than 1%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | ## Merge request drawer @@ -51,30 +81,15 @@ request: - A list of users that approved the merge request. - The user that merged the merge request. -## Approval status and separation of duties - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in GitLab 13.3. +## Separation of duties We support a separation of duties policy between users who create and approve merge requests. -The approval status column can help you identify violations of this policy. Our criteria for the separation of duties is as follows: - [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author) - [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits) - [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md) -The **Approval status** column shows you at a glance whether a merge request is complying with the above. -This column has four states: - -| State | Description | -|:------|:------------| -| Empty | The merge request approval status is unknown | -|  | The merge request **does not** comply with any of the above criteria | -|  | The merge request complies with **some** of the above criteria | -|  | The merge request complies with **all** of the above criteria | - -If you see a non-success state, review the criteria for the merge request's project to ensure it complies with the separation of duties. - ## Chain of Custody report > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. @@ -105,64 +120,3 @@ You can generate a commit-specific Chain of Custody report for a given commit SH NOTE: The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. The remaining records are truncated when this limit is reached. - -## Merge request violations - -> - Introduced in GitLab 14.6. [Deployed behind the `compliance_violations_report` flag](../../../administration/feature_flags.md). Disabled by default. -> - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `compliance_violations_report`. -On GitLab.com, this feature is not available. This feature is not ready for production use. - -Merge request violations provide a view of all the [separation of duties](#approval-status-and-separation-of-duties) compliance violations -that exist in projects in a specific group. For each separation of duties compliance violation, you can see: - -- A list of compliance violations. -- The severity of each compliance violation. -- Reason for the compliance violation. -- A link to the merge request that caused the compliance violation. - -Merge request violations can be accessed: - -- In the GitLab UI. -- Using the [GraphQL API](../../../api/graphql/reference/index.md#complianceviolation) (GitLab 14.9 and later). - -### View merge request violations - -To view merge request violations: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Security & Compliance > Compliance report**. - -### Severity levels scale - -The following is a list of available violation severity levels, ranked from most to least severe: - -| Icon | Severity level | -|:----------------------------------------------|:---------------| -| **{severity-critical, 18, gl-fill-red-800}** | Critical | -| **{severity-high, 18, gl-fill-red-600}** | High | -| **{severity-medium, 18, gl-fill-orange-400}** | Medium | -| **{severity-low, 18, gl-fill-orange-300}** | Low | -| **{severity-info, 18, gl-fill-blue-400}** | Info | - -### Violation types - -The following is a list of violations that are either: - -- Already available. -- Aren't available, but which we are tracking in issues. - -| Violation | Severity level | Category | Description | Availability | -|:-------------------------------------|:----------------|:----------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------| -| Author approved merge request | High | [Separation of duties](#approval-status-and-separation-of-duties) | The author of the merge request approved their own merge request. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | [Unavailable](https://gitlab.com/groups/gitlab-org/-/epics/6870) | -| Committers approved merge request | High | [Separation of duties](#approval-status-and-separation-of-duties) | The committers of the merge request approved the merge request they contributed to. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | [Unavailable](https://gitlab.com/groups/gitlab-org/-/epics/6870) | -| Fewer than two approvals | High | [Separation of duties](#approval-status-and-separation-of-duties) | The merge request was merged with fewer than two approvals. [Learn more](../../project/merge_requests/approvals/rules.md). | [Unavailable](https://gitlab.com/groups/gitlab-org/-/epics/6870) | -| Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | The merge requests pipeline failed and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | -| Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | The merge request pipeline passed with warnings and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | -| Code coverage down more than 10% | High | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of more than 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | -| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | -| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | -| Code coverage down less than 1% | Info | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of less than 1%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | diff --git a/doc/user/crm/crm_contacts_v14_10.png b/doc/user/crm/crm_contacts_v14_10.png Binary files differnew file mode 100644 index 00000000000..f82878f9d4b --- /dev/null +++ b/doc/user/crm/crm_contacts_v14_10.png diff --git a/doc/user/crm/crm_contacts_v14_6.png b/doc/user/crm/crm_contacts_v14_6.png Binary files differdeleted file mode 100644 index 37a615f3926..00000000000 --- a/doc/user/crm/crm_contacts_v14_6.png +++ /dev/null diff --git a/doc/user/crm/crm_organizations_v14_10.png b/doc/user/crm/crm_organizations_v14_10.png Binary files differnew file mode 100644 index 00000000000..256c9c3f83b --- /dev/null +++ b/doc/user/crm/crm_organizations_v14_10.png diff --git a/doc/user/crm/crm_organizations_v14_6.png b/doc/user/crm/crm_organizations_v14_6.png Binary files differdeleted file mode 100644 index 2bde3823cc7..00000000000 --- a/doc/user/crm/crm_organizations_v14_6.png +++ /dev/null diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 1fb628cf505..7fc11add2cd 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -49,7 +49,7 @@ To view a group's contacts: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Contacts**. - + ### Create a contact @@ -86,7 +86,7 @@ To view a group's organizations: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Organizations**. - + ### Create an organization @@ -103,7 +103,15 @@ organizations using the GraphQL API. ### Edit an organization -You can only [edit](../../api/graphql/reference/index.md#mutationcustomerrelationsorganizationupdate) +To edit an existing organization: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Customer relations > Organizations**. +1. Next to the organization you wish to edit, select **Edit** (**{pencil}**). +1. Edit the required fields. +1. Select **Save changes**. + +You can also [edit](../../api/graphql/reference/index.md#mutationcustomerrelationsorganizationupdate) organizations using the GraphQL API. ## Issues @@ -171,3 +179,23 @@ When you use the `/add_contacts` or `/remove_contacts` quick actions, follow the /add_contacts [contact: /remove_contacts [contact: ``` + +## Moving objects with CRM entries + +The root group is the topmost group in the group hierarchy. + +When you move an issue, project, or group **within the same group hierarchy**, +issues retain their contacts. + +When you move an issue or project and the **root group changes**, +issues lose their contacts. + +When you move a group and its **root group changes**: + +- All unique contacts and organizations are migrated to the new root group. +- Contacts that already exist (by email address) are deemed duplicates and deleted. +- Organizations that already exist (by name) are deemed duplicates and deleted. +- All issues retain their contacts or are updated to point at contacts with the same email address. + +If you do not have permission to create contacts and organizations in the new +root group, the group transfer fails. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index a6343e0d1cf..8537856ef25 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -112,12 +112,27 @@ you can reply to comments by sending an email. You can use [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md) in your email replies. -## Who can edit comments +## Edit a comment You can edit your own comment at any time. - Anyone with at least the Maintainer role can also edit a comment made by someone else. +To edit a comment: + +1. On the comment, select **Edit comment** (**{pencil}**). +1. Make your edits. +1. Select **Save changes**. + +### Editing a comment to add a mention + +By default, when you mention a user, GitLab [creates a to-do item](../todos.md#actions-that-create-to-do-items) +for them, and sends them a [notification email](../profile/notifications.md). + +If you edit an existing comment to add a user mention that wasn't there before, GitLab: + +- Creates a to-do item for the mentioned user. +- Does not send a notification email. + ## Prevent comments by locking an issue You can prevent public comments in an issue or merge request. @@ -137,7 +152,8 @@ If an issue or merge request is locked and closed, you cannot reopen it. ## Mark a comment as confidential **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9 [with a flag](../../administration/feature_flags.md) named `confidential_notes`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9 [with a flag](../../administration/feature_flags.md) named `confidential_notes`. Disabled by default. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/351143) in GitLab 14.10: you can only mark comments in issues and epics as confidential. Previously, it was also possible for comments in merge requests and snippets. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, @@ -145,9 +161,25 @@ ask an administrator to [enable the feature flag](../../administration/feature_f On GitLab.com, this feature is not available. You should not use this feature for production environments. -You can make a comment confidential, so that it is visible only to project members -who have at least the Reporter role. +You can make a comment **in an issue or an epic** confidential, so that it is visible only to you (the commenting user) and +the project members who have at least the Reporter role. + +Keep in mind: + +- You can only mark comments as confidential when you create them. +- You can't change the confidentiality of existing comments. +- Replies to comments use same confidentiality as the original comment. + +Prerequisites: + +- You must either: + - Have at least the Reporter role for the project. + - Be the issue assignee. + - Be the issue author. + +To mark a comment as confidential: +1. Start adding a new comment. 1. Below the comment, select the **Make this comment confidential** checkbox. 1. Select **Comment**. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 5cf6a505bee..6bb45575fc3 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -48,9 +48,16 @@ gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAA ## Mail configuration GitLab.com sends emails from the `mg.gitlab.com` domain by using [Mailgun](https://www.mailgun.com/), -and has its own dedicated IP address (`192.237.158.143`). +and has its own dedicated IP addresses: -The IP address for `mg.gitlab.com` is subject to change at any time. +- `161.38.202.219` +- `159.135.226.146` +- `192.237.158.143` +- `198.61.254.136` +- `23.253.183.236` +- `69.72.35.190` + +The IP addresses for `mg.gitlab.com` are subject to change at any time. ### Service Desk custom mailbox @@ -138,7 +145,7 @@ the related documentation. | Artifacts maximum size (compressed) | 1 GB | See [Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size) | | Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | See [Default artifacts expiration](../admin_area/settings/continuous_integration.md#default-artifacts-expiration) | | Scheduled Pipeline Cron | `*/5 * * * *` | See [Pipeline schedules advanced configuration](../../administration/cicd.md#change-maximum-scheduled-pipeline-frequency) | -| Maximum jobs in active pipelines | `500` for Free tier, unlimited otherwise | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | +| Maximum jobs in active pipelines | `500` for Free tier, `1000` for all trial tiers, and unlimited otherwise. | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | | Maximum CI/CD subscriptions to a project | `2` | See [Number of CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | | Maximum number of pipeline triggers in a project | `25000` for Free tier, Unlimited for all paid tiers | See [Limit the number of pipeline triggers](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers) | | Maximum pipeline schedules in projects | `10` for Free tier, `50` for all paid tiers | See [Number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules) | @@ -315,24 +322,30 @@ limiting responses](#rate-limiting-responses). The following table describes the rate limits for GitLab.com, both before and after the limits change in January, 2021: -| Rate limit | Before 2021-02-12 | From 2021-02-12 | From 2022-02-03 | -|:--------------------------------------------------------------------------|:------------------------------|:------------------------------|:----------------------------------------| -| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | **10** requests per minute | -| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | **300** requests per minute | -| **Unauthenticated** traffic (from a given **IP address**) | **500** requests per minute | **500** requests per minute | **500** requests per minute | -| **Authenticated** API traffic (for a given **user**) | **2,000** requests per minute | **2,000** requests per minute | **2,000** requests per minute | -| **Authenticated** non-API HTTP traffic (for a given **user**) | **1,000** requests per minute | **1,000** requests per minute | **1,000** requests per minute | -| **All** traffic (from a given **IP address**) | **2,000** requests per minute | **2,000** requests per minute | **2,000** requests per minute | -| **Issue creation** | **300** requests per minute | **300** requests per minute | **300** requests per minute | -| **Note creation** (on issues and merge requests) | **300** requests per minute | **60** requests per minute | **60** requests per minute | -| **Advanced, project, and group search** API (for a given **IP address**) | | **10** requests per minute | **10** requests per minute | -| **GitLab Pages** requests (for a given **IP address**) | | | **1000** requests per **50 seconds** | -| **GitLab Pages** requests (for a given **GitLab Pages domain**) | | | **5000** requests per **10 seconds** | +| Rate limit | From 2021-02-12 | From 2022-02-03 | +|:--------------------------------------------------------------------------|:------------------------------|:----------------------------------------| +| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | +| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | +| **Unauthenticated** traffic (from a given **IP address**) | **500** requests per minute | **500** requests per minute | +| **Authenticated** API traffic (for a given **user**) | **2,000** requests per minute | **2,000** requests per minute | +| **Authenticated** non-API HTTP traffic (for a given **user**) | **1,000** requests per minute | **1,000** requests per minute | +| **All** traffic (from a given **IP address**) | **2,000** requests per minute | **2,000** requests per minute | +| **Issue creation** | **300** requests per minute | **300** requests per minute | +| **Note creation** (on issues and merge requests) | **60** requests per minute | **60** requests per minute | +| **Advanced, project, and group search** API (for a given **IP address**) | **10** requests per minute | **10** requests per minute | +| **GitLab Pages** requests (for a given **IP address**) | | **1000** requests per **50 seconds** | +| **GitLab Pages** requests (for a given **GitLab Pages domain**) | | **5000** requests per **10 seconds** | More details are available on the rate limits for [protected paths](#protected-paths-throttle) and [raw endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). +GitLab can rate-limit requests at several layers. The rate limits listed here +are configured in the application. These limits are the most +restrictive per IP address. To learn more about the rate limiting +for GitLab.com, read our runbook page +[Overview of rate limits for GitLab.com](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/rate-limiting). + ### Rate limiting responses For information on rate limiting responses, see: @@ -395,7 +408,7 @@ doesn't return the following headers: ### Visibility settings If created before GitLab 12.2 (July 2019), these items have the -[Internal visibility](../../public_access/public_access.md#internal-projects-and-groups) +[Internal visibility](../public_access.md#internal-projects-and-groups) setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/12388): - Projects diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 3b866c4a1b0..cd2d5c190a1 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. -With Contribution Analytics, you can get an overview of the [contribution events](../../index.md#user-contribution-events) in your +With Contribution Analytics, you can get an overview of the [contribution events](../../profile/index.md#user-contribution-events) in your group. - Analyze your team's contributions over a period of time. diff --git a/doc/user/group/epics/img/related_epic_block_v14_9.png b/doc/user/group/epics/img/related_epic_block_v14_9.png Binary files differindex 7b5824b84d1..20fdce0151d 100644 --- a/doc/user/group/epics/img/related_epic_block_v14_9.png +++ b/doc/user/group/epics/img/related_epic_block_v14_9.png diff --git a/doc/user/group/epics/img/related_epics_add_v14_9.png b/doc/user/group/epics/img/related_epics_add_v14_9.png Binary files differindex 3da6eeaff43..112b900f2e3 100644 --- a/doc/user/group/epics/img/related_epics_add_v14_9.png +++ b/doc/user/group/epics/img/related_epics_add_v14_9.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 149c5362ac9..f2cb437ffda 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -45,20 +45,6 @@ have a start or due date, a visual  -## Permissions - -If you have access to view an epic and an issue added to that epic, you can view the issue in the -epic's issue list. - -If you have access to edit an epic and an issue added to that epic, you can add the issue to or -remove it from the epic. - -For a given group, the visibility of all projects must be the same as -the group, or less restrictive. That means if you have access to a group's epic, -then you already have access to its projects' issues. - -You can also consult the [group permissions table](../../permissions.md#group-members-permissions). - ## Related topics - [Manage epics](manage_epics.md) and multi-level child epics. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 3350b0f1169..e8f720238ed 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -16,6 +16,10 @@ to them. > - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. > - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty roadmap. +Prerequisites: + +- You must have at least the Reporter role for the epic's group. + To create an epic in the group you're in: 1. Get to the New Epic form: @@ -68,6 +72,10 @@ After you create an epic, you can edit the following details: - Due date - Labels +Prerequisites: + +- You must have at least the Reporter role for the epic's group. + To edit an epic's title or description: 1. Select **Edit title and description** **{pencil}**. @@ -87,6 +95,10 @@ Users with at least the Reporter role can manage epics. When bulk editing epics in a group, you can edit their labels. +Prerequisites: + +- You must have at least the Reporter role for the parent epic's group. + To update multiple epics at the same time: 1. In a group, go to **Epics > List**. @@ -97,8 +109,9 @@ To update multiple epics at the same time: ## Delete an epic -NOTE: -To delete an epic, you must be an Owner of a group or subgroup. +Prerequisites: + +- You must have the Owner role for the epic's group. To delete the epic: @@ -112,6 +125,10 @@ If you delete an epic, all its child epics and their descendants are deleted as ## Close an epic +Prerequisites: + +- You must have at least the Reporter role for the epic's group. + Whenever you decide that there is no longer need for that epic, close the epic by: @@ -123,13 +140,19 @@ close the epic by: ## Reopen a closed epic -You can reopen an epic that was closed by: +You can reopen an epic that was closed. + +Prerequisites: -- Selecting **Reopen epic**. +- You must have at least the Reporter role for the epic's group. + +To do so, either: + +- Select **Reopen epic**.  -- Using the `/reopen` [quick action](../../project/quick_actions.md). +- Use the `/reopen` [quick action](../../project/quick_actions.md). ## Go to an epic from an issue @@ -144,6 +167,13 @@ In a group, the left sidebar displays the total count of open epics. This number indicates all epics associated with the group and its subgroups, including epics you might not have permission to view. +Prerequisites: + +- You must be a member of either: + - The group + - A project in the group + - A project in one of the group's subgroups + To view epics in a group: 1. On the top bar, select **Menu > Groups** and find your group. @@ -225,6 +255,10 @@ and confidential child epics. However, merge requests are public, if created in Read [Merge requests for confidential issues](../../project/merge_requests/confidential.md) to learn how to create a confidential merge request. +Prerequisites: + +- You must have at least the Reporter role for the epic's group. + To make an epic confidential: - **When creating an epic:** select the checkbox under **Confidentiality**. @@ -236,6 +270,15 @@ To make an epic confidential: This section collects instructions for all the things you can do with [issues](../../project/issues/index.md) in relation to epics. +### View issues assigned to an epic + +On the **Epics and Issues** tab, you can see epics and issues assigned to this epic. +Only epics and issues that you can access show on the list. + +You can always view the issues assigned to the epic if they are in the group's child project. +It's possible because the visibility setting of a project must be the same as or less restrictive than +of its parent group. + ### View count of issues in an epic On the **Epics and Issues** tab, under each epic name, hover over the total counts. @@ -258,7 +301,12 @@ An epic contains a list of issues and an issue can be associated with at most on When you add a new issue that's already linked to an epic, the issue is automatically unlinked from its current parent. -To add a new issue to an epic: +Prerequisites: + +- You must have at least the Reporter role for the epic's group. +- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). + +To add an existing issue to an epic: 1. On the epic's page, under **Epics and Issues**, select **Add**. 1. Select **Add an existing issue**. @@ -277,19 +325,30 @@ To add a new issue to an epic: Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts. +Prerequisites: + +- You must have at least the Reporter role for the epic's group. + To create an issue from an epic: 1. On the epic's page, under **Epics and Issues**, select **Add**. 1. Select **Add a new issue**. 1. Under **Title**, enter the title for the new issue. -1. From the **Project** dropdown, select the project in which the issue should be created. +1. From the **Project** dropdown list, select the project in which the issue should be created. 1. Select **Create issue**. +The new issue is assigned to the epic. + ### Remove an issue from an epic You can remove issues from an epic when you're on the epic's details page. After you remove an issue from an epic, the issue is no longer associated with this epic. +Prerequisites: + +- You must have at least the Reporter role for the epic's group. +- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). + To remove an issue from an epic: 1. Next to the issue you want to remove, select **Remove** (**{close}**). @@ -305,6 +364,10 @@ To remove an issue from an epic: New issues appear at the top of the list in the **Epics and Issues** tab. You can reorder the list of issues by dragging them. +Prerequisites: + +- You must have at least the Reporter role for the epic's group. + To reorder issues assigned to an epic: 1. Go to the **Epics and Issues** tab. @@ -317,32 +380,47 @@ To reorder issues assigned to an epic: New issues appear at the top of the list in the **Epics and Issues** tab. You can move issues from one epic to another. +Prerequisites: + +- You must have at least the Reporter role for the epic's group. +- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). + To move an issue to another epic: 1. Go to the **Epics and Issues** tab. -1. Drag issues into the desired parent epic. +1. Drag issues into the desired parent epic in the visible hierarchy. ### Promote an issue to an epic > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. -If you have the necessary [permissions](../../permissions.md) to close an issue and create an -epic in the immediate parent group, you can promote an issue to an epic with the `/promote` +Prerequisites: + +- The project to which the issue belongs must be in a group. +- You must have at least the Reporter role the project's immediate parent group. +- You must either: + - Have at least the Reporter role for the project. + - Be the author of the issue. + - Be assigned to the issue. + +You can promote an issue to an epic with the `/promote` [quick action](../../project/quick_actions.md#issues-merge-requests-and-epics). -Only issues from projects that are in groups can be promoted. When you attempt to promote a confidential -issue, a warning is displayed. Promoting a confidential issue to an epic makes all information + +NOTE: +Promoting a confidential issue to an epic makes all information related to the issue public as epics are public to group members. When an issue is promoted to an epic: +- If the issue was confidential, an additional warning is displayed first. - An epic is created in the same group as the project of the issue. - Subscribers of the issue are notified that the epic was created. The following issue metadata is copied to the epic: - Title, description, activity/comment thread. -- Upvotes/downvotes. +- Upvotes and downvotes. - Participants. - Group labels that the issue already has. - Parent epic. @@ -367,6 +445,10 @@ Epics can contain multiple nested child epics, up to a total of seven levels dee ### Add a child epic to an epic +Prerequisites: + +- You must have at least the Reporter role for the parent epic's group. + To add a child epic to an epic: 1. Select **Add**. @@ -388,6 +470,10 @@ You can move child epics from one epic to another. When you add a new epic that's already linked to a parent epic, the link to its current parent is removed. Issues and child epics cannot be intermingled. +Prerequisites: + +- You must have at least the Reporter role for the parent epic's group. + To move child epics to another epic: 1. Go to the **Epics and Issues** tab. @@ -400,6 +486,10 @@ To move child epics to another epic: New child epics appear at the top of the list in the **Epics and Issues** tab. You can reorder the list of child epics. +Prerequisites: + +- You must have at least the Reporter role for the parent epic's group. + To reorder child epics assigned to an epic: 1. Go to the **Epics and Issues** tab. @@ -407,6 +497,10 @@ To reorder child epics assigned to an epic: ### Remove a child epic from a parent epic +Prerequisites: + +- You must have at least the Reporter role for the parent epic's group. + To remove a child epic from a parent epic: 1. Select **Remove** (**{close}**) in the parent epic's list of epics. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 0c16b535ed1..0185cb9cfdf 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -138,9 +138,9 @@ migrated: In a [rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session), you can find the failure or error messages for the group import attempt using: -```shell +```ruby # Get relevant import records -import = BulkImports::Entity.where(namespace_id: Group.id).bulk_import +import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) # Alternative lookup by user import = BulkImport.where(user_id: User.find(...)).last @@ -154,3 +154,18 @@ entities.map(&:failures).flatten # Alternative failure lookup by status entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :status) ``` + +### Stale imports + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352985) in GitLab 14.10. + +When troubleshooting group migration, an import may not complete because the import workers took +longer than 8 hours to execute. In this case, the `status` of either a `BulkImport` or +`BulkImport::Entity` is `3` (`timeout`): + +```ruby +# Get relevant import records +import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) + +import.status #=> 3 means that the import timed out. +``` diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 4b9ff7f64e8..085cd054c14 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,6 @@ --- -type: reference, howto stage: Manage -group: Authentication and Authorization +group: Workspace info: 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 --- @@ -68,7 +67,7 @@ To create a group: 1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see [reserved names](../reserved_names.md). 1. Enter a path for the group in **Group URL**, which is used for the [namespace](#namespaces). -1. Choose the [visibility level](../../public_access/public_access.md). +1. Choose the [visibility level](../public_access.md). 1. Personalize your GitLab experience by answering the following questions: - What is your role? - Who will be using this group? @@ -279,8 +278,8 @@ To view the activity feed in Atom format, select the [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. 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 includes members who inherited group membership from a parent group. +you can share a group with another group. To invite a group, you must be a member of it. Members get direct access +to the shared group. This includes members who inherited group membership from a parent group. To share a given group, for example, `Frontend` with another group, for example, `Engineering`: @@ -289,10 +288,14 @@ To share a given group, for example, `Frontend` with another group, for example, 1. On the left sidebar, select **Group information > Members**. 1. Select **Invite a group**. 1. In the **Select a group to invite** list, select `Engineering`. -1. Select a [role](../permissions.md). +1. Select a [role](../permissions.md) as maximum access level. 1. Select **Invite**. -All the members of the `Engineering` group are added to the `Frontend` group. +After sharing the `Frontend` group with the `Engineering` group: + +- The **Groups** tab lists the `Engineering` group. +- The **Groups** tab lists a group regardless of whether it is a public or private group. +- All members of the `Engineering` group have access to the `Frontend` group. The same access levels of the members apply up to the maximum access level selected when sharing the group. ## Manage group memberships via LDAP **(PREMIUM SELF)** @@ -793,23 +796,25 @@ The group's new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. -## Group approval rules **(PREMIUM)** +## Group approval settings **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. > - [Feature flag `group_merge_request_approval_settings_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/issues/343872) removed in GitLab 14.9. -Group approval rules manage [project merge request approval rules](../project/merge_requests/approvals/index.md) -at the top-level group level. These rules [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) +Group approval settings manage [project merge request approval settings](../project/merge_requests/approvals/settings.md) +at the top-level group level. These settings [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) that belong to the group. -To view the merge request approval rules for a group: +To view the merge request approval settings for a group: 1. Go to the top-level group's **Settings > General** page. 1. Expand the **Merge request approvals** section. 1. Select the settings you want. 1. Select **Save changes**. +Support for group-level settings for merge request approval rules is tracked in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). + ## Related topics - [Group wikis](../project/wiki/index.md) diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index b5912a0b40e..1c316f2157d 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -12,6 +12,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Moved to GitLab Premium in 13.9. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 14.6. [Feature flag `group_iterations`](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) removed. +WARNING: +After [Iteration Cadences](#iteration-cadences) becomes generally available, +manual iteration scheduling will be [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 15.6. +To enhance the role of iterations as time boundaries, we will also deprecate the title field. + Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) for tracking over different time periods. @@ -28,54 +33,6 @@ In GitLab, iterations are similar to milestones, with a few differences: - Iterations require both a start and an end date. - Iteration date ranges cannot overlap. -## Iteration cadences - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1. -> - Deployed behind a [feature flag](../../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-iteration-cadences). - -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - -Iteration cadences automate some common iteration tasks. They can be used to -automatically create iterations every 1, 2, 3, 4, or 6 weeks. They can also -be configured to automatically roll over incomplete issues to the next iteration. - -With iteration cadences enabled, you must first -[create an iteration cadence](#create-an-iteration-cadence) before you can -[create an iteration](#create-an-iteration). - -### Create an iteration cadence - -Prerequisites: - -- You must have at least the Developer role for a group. - -To create an iteration cadence: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. -1. Select **New iteration cadence**. -1. Fill out required fields, and select **Create iteration cadence**. The cadence list page opens. - -### Delete an iteration cadence - -Prerequisites: - -- You must have at least the Developer role for a group. - -Deleting an iteration cadence also deletes all iterations within that cadence. - -To delete an iteration cadence: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. -1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. -1. Select **Delete cadence** in the confirmation modal. - ## View the iterations list To view the iterations list, go to **{issues}** **Issues > Iterations**. @@ -84,12 +41,16 @@ From there you can create a new iteration or select an iteration to get a more d ## Create an iteration +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 14.10. + +WARNING: +Manual iteration management is in its end-of-life process. Creating an iteration is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) +in GitLab 14.10, and is planned for removal in GitLab 16.0. + Prerequisites: - You must have at least the Developer role for a group. -For manually scheduled iteration cadences, you create and add iterations yourself. - To create an iteration: 1. On the top bar, select **Menu > Groups** and find your group. @@ -100,7 +61,13 @@ To create an iteration: ## Edit an iteration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in GitLab 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in GitLab 13.2. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 14.10. + +WARNING: +Editing all attributes, with the exception of `description` is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) +in GitLab 14.10, and is planned for removal in GitLab 16.0. +In the future only editing an iteration's `description` will be allowed. Prerequisites: @@ -110,7 +77,12 @@ To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit**. ## Delete an iteration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292268) in GitLab 14.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292268) in GitLab 14.3. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 14.10. + +WARNING: +Manual iteration management is in its end-of-life process. Deleting an iteration is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) +in GitLab 14.10, and is planned for removal in GitLab 16.0. Prerequisites: @@ -136,7 +108,7 @@ The report also shows a breakdown of total issues in an iteration. Open iteration reports show a summary of completed, unstarted, and in-progress issues. Closed iteration reports show the total number of issues completed by the due date. -To view an iteration report, go to the iterations list page and select an iteration's title. +To view an iteration report, go to the iterations list page and select an iteration's period. ### Iteration burndown and burnup charts @@ -195,33 +167,61 @@ To group issues by label: You can also search for labels by typing in the search input. 1. Select any area outside the label dropdown list. The page is now grouped by the selected labels. -### Enable or disable iteration cadences **(PREMIUM SELF)** +## Iteration cadences + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1. +> - Deployed behind a [feature flag](../../feature_flags.md), named `iteration_cadences`, disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an +administrator to [enable the feature flag](../../../administration/feature_flags.md) named +`iteration_cadences` for a root group. +On GitLab.com, this feature is not available. This feature is not ready for production use. + +Iteration cadences automate iteration scheduling. You can use them to +automate creating iterations every 1, 2, 3, 4, or 6 weeks. You can also +configure iteration cadences to automatically roll over incomplete issues to the next iteration. + +### Create an iteration cadence + +Prerequisites: + +- You must have at least the Developer role for a group. + +To create an iteration cadence: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Iterations**. +1. Select **New iteration cadence**. +1. Fill out required fields, and select **Create iteration cadence**. The cadence list page opens. + +### Delete an iteration cadence + +Prerequisites: + +- You must have at least the Developer role for a group. -Iteration Cadences feature is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +Deleting an iteration cadence also deletes all iterations within that cadence. -To enable it: +To delete an iteration cadence: -```ruby -Feature.enable(:iteration_cadences) -``` +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Iterations**. +1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. +1. Select **Delete cadence** in the confirmation modal. -To disable it: +### Convert manual cadence to use automatic scheduling -```ruby -Feature.disable(:iteration_cadences) -``` +WARNING: +The upgrade is irreversible. After it's done, manual iteration cadences cannot be created. -<!-- ## Troubleshooting +When you **enable** the iteration cadences feature, all iterations are added +to a default iteration cadence. +In this default iteration cadence, you can continue to add, edit, and remove iterations. -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. +To upgrade the iteration cadence to use the automation features: -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. --> +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Iterations**. +1. Select the three-dot menu (**{ellipsis_v}**) > **Edit cadence** for the cadence you want to upgrade. +1. Fill out required fields, and select **Save changes**. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 8ebcd9f62d0..4d122e337db 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -23,12 +23,14 @@ If required, you can find [a glossary of common terms](../../../integration/saml ## Configure your identity provider -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, 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). +1. Find the information in GitLab required for configuration: + 1. On the top bar, select **Menu > Groups** and find your group. + 1. On the left sidebar, select **Settings > SAML SSO**. + 1. Note the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. +1. Configure your SAML identity provider app using the noted details. + Alternatively, GitLab provides a [metadata XML configuration](#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 the SAML response to include a [NameID](#nameid) that uniquely identifies each user. 1. Configure the required [user attributes](#user-attributes), ensuring you include the user's email address. 1. While the default is enabled for most SAML providers, please ensure the app is set to have service provider initiated calls in order to link existing GitLab accounts. @@ -245,7 +247,7 @@ To migrate users to a new email domain, users must: ## User access and management -> [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. +> SAML user provisioning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 331288e33a1..3960c97142e 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -20,7 +20,7 @@ The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 prot The following actions are available: - Create users -- Deactivate users +- Remove users (deactivate SCIM identity) The following identity providers are supported: @@ -133,7 +133,7 @@ After the above steps are complete: The Okta GitLab application currently only supports SCIM. Continue using the separate Okta [SAML SSO](index.md) configuration along with the new SCIM -application described above. +application described above. An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/216173) to add SAML support to the Okta GitLab application. ### OneLogin @@ -150,7 +150,7 @@ The following diagram is a general outline on what happens when you add users to ```mermaid graph TD - A[Add User to SCIM app] -->|IdP sends user info to GitLab| B(GitLab: Does the email exists?) + A[Add User to SCIM app] -->|IdP sends user info to GitLab| B(GitLab: Does the email exist?) B -->|No| C[GitLab creates user with SCIM identity] B -->|Yes| D[GitLab sends message back 'Email exists'] ``` diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 6b20f1763d4..0666303bcf8 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -16,14 +16,17 @@ You can use a group access token to authenticate: - With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. + Use: -After you configure a group access token, you don't need a password when you authenticate. -Instead, you can enter any non-blank value. + - Any non-blank value as a username. + - The group access token as the password. Group access tokens are similar to [project access tokens](../../project/settings/project_access_tokens.md) and [personal access tokens](../../profile/personal_access_tokens.md), except they are associated with a group rather than a project or user. +In self-managed instances, group access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) as personal access tokens if the limit is set. + You can use group access tokens: - On GitLab SaaS if you have the Premium license tier or higher. Group access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). @@ -33,6 +36,8 @@ You can use group access tokens: - Consider [disabling group access tokens](#enable-or-disable-group-access-token-creation) to lower potential abuse. +You cannot use group access tokens to create other access tokens. + Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. @@ -45,7 +50,7 @@ To create a group access token: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the group. -1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. +1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-group-access-token). 1. Select **Create group access token**. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index a98f213bb3f..2cddbaa9723 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication and Authorization +group: Workspace info: 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 --- @@ -49,9 +49,16 @@ graph TD ## Create a subgroup -Users with the at least the Maintainer role on a group can create subgroups immediately below the group, unless -[configured otherwise](#change-who-can-create-subgroups). These users can create subgroups even if group creation is -[disabled by an Administrator](../../admin_area/index.md#prevent-a-user-from-creating-groups) in the user's settings. +Prerequisites: + +- You must either: + - Have at least the Maintainer role for a group to create subgroups for it. + - Have the [role determined by a setting](#change-who-can-create-subgroups). These users can create + subgroups even if group creation is + [disabled by an Administrator](../../admin_area/index.md#prevent-a-user-from-creating-groups) in the user's settings. + +NOTE: +You cannot host a GitLab Pages subgroup website with a top-level domain name. For example, `subgroupname.example.io`. To create a subgroup: diff --git a/doc/user/group/value_stream_analytics/img/vsa_aggregated_data_toggle_v14_9.png b/doc/user/group/value_stream_analytics/img/vsa_aggregated_data_toggle_v14_9.png Binary files differnew file mode 100644 index 00000000000..5ad8026b8fd --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_aggregated_data_toggle_v14_9.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png Binary files differdeleted file mode 100644 index 834556df051..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png b/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png Binary files differdeleted file mode 100644 index 8d77c53db7f..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png +++ /dev/null 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 differdeleted file mode 100644 index 5dd79d06463..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_path_nav_v13_11.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png Binary files differdeleted file mode 100644 index 7c3305792bb..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png Binary files differdeleted file mode 100644 index 68d9741bed8..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 5ea8512ed5a..3fce9baa9ce 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -16,6 +16,7 @@ Use value stream analytics to identify: - The amount of time it takes to go from an idea to production. - The velocity of a given project. - Bottlenecks in the development process. +- Detecting long-running issues or merge requests. - Factors that cause your software development lifecycle to slow down. Value stream analytics is also available for [projects](../../analytics/value_stream_analytics.md). @@ -26,7 +27,10 @@ Value stream analytics is also available for [projects](../../analytics/value_st > - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 > - Horizontal stage path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in 13.0 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in 13.12 -You must have at least the Reporter role to view value stream analytics for groups. +Prerequisite: + +- You must have at least the Reporter role to view value stream analytics for groups. +- You must create a [custom value stream](#custom-value-streams). Value stream analytics only shows custom value streams created for your group. To view value stream analytics for your group: @@ -37,6 +41,9 @@ To view value stream analytics for your group: 1. Select the **Filter results** text box. 1. Select a parameter. 1. Select a value or enter text to refine the results. + 1. Select whether to view metrics for items with a start or stop event: + - To view items with a stop event in the date range, turn on the **Filter by stop date** toggle. Enabled by default. + - To view items with a start event in the date range, turn off the **Filter by stop date** toggle. 1. To adjust the date range: - In the **From** field, select a start date. - In the **To** field, select an end date. The charts and list show workflow items created @@ -71,6 +78,9 @@ To view the median time spent in each stage by a group: 1. Select the **Filter results** text box. 1. Select a parameter. 1. Select a value or enter text to refine the results. + 1. Select whether to view metrics for items with a start or stop event: + - To view items with a stop event in the date range, turn on the **Filter by stop date** toggle. Enabled by default. + - To view items with a start event in the date range, turn off the **Filter by stop date** toggle. 1. To adjust the date range: - In the **From** field, select a start date. - In the **To** field, select an end date. @@ -91,6 +101,9 @@ To view the lead time and cycle time for issues: 1. Select the **Filter results** text box. 1. Select a parameter. 1. Select a value or enter text to refine the results. + 1. Select whether to view metrics for items with a start or stop event: + - To view items with a stop event in the date range, turn on the **Filter by stop date** toggle. Enabled by default. + - To view items with a start event in the date range, turn off the **Filter by stop date** toggle. 1. To adjust the date range: - In the **From** field, select a start date. - In the **To** field, select an end date. @@ -111,6 +124,9 @@ To view the lead time for changes for merge requests in your group: 1. Select the **Filter results** text box. 1. Select a parameter. 1. Select a value or enter text to refine the results. + 1. Select whether to view metrics for items with a start or stop event: + - To view items with a stop event in the date range, turn on the **Filter by stop date** toggle. Enabled by default. + - To view items with a start event in the date range, turn off the **Filter by stop date** toggle. 1. To adjust the date range: - In the **From** field, select a start date. - In the **To** field, select an end date. @@ -125,7 +141,7 @@ To view deployment metrics, you must have a [production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). Value stream analytics shows the following deployment metrics for your group: - + - Deploys: The number of successful deployments in the date range. - Deployment Frequency: The average number of successful deployments per day in the date range. @@ -137,6 +153,9 @@ To view deployment metrics for your group: 1. Select the **Filter results** text box. 1. Select a parameter. 1. Select a value or enter text to refine the results. + 1. Select whether to view metrics for items with a start or stop event: + - To view items with a stop event in the date range, turn on the **Filter by stop date** toggle. Enabled by default. + - To view items with a start event in the date range, turn off the **Filter by stop date** toggle. 1. To adjust the date range: - In the **From** field, select a start date. - In the **To** field, select an end date. @@ -150,25 +169,24 @@ NOTE: In GitLab 13.9 and later, metrics are calculated based on when the deployment was finished. In GitLab 13.8 and earlier, metrics are calculated based on when the deployment was created. -## Upcoming date filter change +### How value stream analytics aggregates data + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335391) in GitLab 14.5 [with a flag](../../../administration/feature_flags.md) named `use_vsa_aggregated_tables`. Disabled by default. +> - Filter by stop date toggle [added](https://gitlab.com/gitlab-org/gitlab/-/issues/352428) in GitLab 14.9 +> - Data refresh badge [added](https://gitlab.com/gitlab-org/gitlab/-/issues/341739) in GitLab 14.9 + +Plans for value stream analytics to filter items by stop event instead of start event are tracked in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/6046). With the completion of this work, value stream analytics will only display items with a stop event in the date range. -In the [epics](https://gitlab.com/groups/gitlab-org/-/epics/6046), we plan to alter -the date filter behavior to filter the end event time of the currently selected stage. +To preview this functionality, you can use the **Filter by stop date** toggle to enable or disable this filter until the [default filtering mode is introduced](../../../update/deprecations.md#value-stream-analytics-filtering-calculation-change) and the toggle is removed. -The change makes it possible to get a much better picture about the completed items within the -stage and helps uncover long-running items. +If you turn on the **Filter by stop date** toggle, the results show items with a stop event within the date range. When this function is enabled, it may take up to 10 minutes for results to show due to data aggregation. There are occasions when it may take longer than 10 minutes for results to display: -For example, an issue was created a year ago and the current stage was finished in the current month. -If you were to look at the metrics for the last three months, this issue would not be included in the calculation of -the stage metrics. With the new date filter, this item would be included. +- If this is the first time you are viewing value stream analytics and have not yet [created a value stream](#create-a-value-stream). +- If the group hierarchy has been re-arranged. +- If there have been bulk updates on issues and merge requests. -DISCLAIMER: -This section contains information related to upcoming products, features, and functionality. -It is important to note that the information presented is for informational purposes only. -Please do not rely on this information for purchasing or planning purposes. -As with all projects, the items mentioned on this page are subject to change or delay. -The development, release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. +To view when the data was most recently updated, in the right corner next to **Edit**, hover over the **Last updated** badge. This badge is only available if you have turned on the **Filter by start date** toggle. + ## How value stream analytics measures stages @@ -177,7 +195,10 @@ Value stream analytics measures each stage from its start event to its end event For example, a stage might start when a user adds a label to an issue, and ends when they add another label. Items aren't included in the stage time calculation if they have not reached the end event. -Each stage of value stream analytics is further described in the table below. +Value stream analytics allows you to customize your stages based on pre-defined events. To make the +configuration easier, GitLab provides a pre-defined list of stages that can be used as a template + +Each pre-defined stages of value stream analytics is further described in the table below. | Stage | Measurement method | | ------- | -------------------- | @@ -188,21 +209,21 @@ Each stage of value stream analytics is further described in the table below. | Review | The median time taken to review a merge request that has a closing issue pattern, between its creation and until it's merged. | | Staging | The median time between merging a merge request that has a closing issue pattern until the very first deployment to a [production environment](#how-value-stream-analytics-identifies-the-production-environment). If there isn't a production environment, this is not tracked. | -## Example workflow +### Example workflow -This example shows a workflow through all seven stages in one day. +This example shows a workflow through all seven stages in one day. -If a stage does not include a start and a stop time, its data is not included in the median time. +If a stage does not include a start and a stop time, its data is not included in the median time. In this example, milestones have been created and CI/CD for testing and setting environments is configured. - 09:00: Create issue. **Issue** stage starts. -- 11:00: Add issue to a milestone, start work on the issue, and create a branch locally. - **Issue** stage stops and **Plan** stage starts. +- 11:00: Add issue to a milestone, start work on the issue, and create a branch locally. + **Issue** stage stops and **Plan** stage starts. - 12:00: Make the first commit. - 12:30: Make the second commit to the branch that mentions the issue number. **Plan** stage stops and **Code** stage starts. -- 14:00: Push branch and create a merge request that contains the - [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically). +- 14:00: Push branch and create a merge request that contains the + [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically). **Code** stage stops and **Test** and **Review** stages start. - GitLab CI/CD takes 5 minutes to run scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/index.md). - 19:00: Merge the merge request. **Review** stage stops and **Staging** stage starts. @@ -214,7 +235,7 @@ Value stream analytics records the following times for each stage: - **Plan**: 11:00 to 12:00: 1 hr - **Code**: 12:00 to 14:00: 2 hrs - **Test**: 5 minutes -- **Review**: 14:00 to 19:00: 5 hrs +- **Review**: 14:00 to 19:00: 5 hrs - **Staging**: 19:00 to 19:30: 30 minutes There are some additional considerations for this example: @@ -263,13 +284,16 @@ To create a value stream: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. -1. In the top right, select the dropdown list and then **Create new Value Stream**. +1. If this is the first time you are creating a value stream, select **Create custom value stream**. Otherwise, in the top right, select the dropdown list and then **Create new Value Stream**. 1. Enter a name for the new Value Stream. - You can [customize the stages](#create-a-value-stream-with-stages). 1. Select **Create Value Stream**.  +NOTE: +If you have recently upgraded to GitLab Premium, it can take up to 30 minutes for data to collect and display. + ### Create a value stream with stages > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50229) in GitLab 13.7. @@ -283,7 +307,7 @@ To create a value stream with stages: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. -1. In the top right, select the dropdown list and then **Create new Value Stream**. +1. If this is the first time you are creating a value stream, select **Create custom value stream**. Otherwise, in the top right, select the dropdown list and then **Create new Value Stream**. 1. Select either **Create from default template** or **Create from no template**. - You can hide or re-order default stages in the value stream. diff --git a/doc/user/index.md b/doc/user/index.md index 4ce46c5b46f..af106b85ce9 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -2,253 +2,20 @@ stage: none group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, index -description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.' --- -# User Docs **(FREE)** - -Welcome to GitLab! We're glad to have you here! - -As a GitLab user you have access to all the features -your [subscription](https://about.gitlab.com/pricing/) -includes, except [GitLab administrator](../administration/index.md) -settings, unless you have administrator privileges to install, configure, -and upgrade your GitLab instance. - -Administrator privileges for [GitLab.com](https://gitlab.com/) are restricted to the GitLab team. - -For more information on configuring GitLab self-managed instances, see the [Administrator documentation](../administration/index.md). - -## Overview - -GitLab is a fully integrated software development platform that enables your team to be transparent, fast, effective, and cohesive from discussion on a new idea to production, all on the same platform. - -For more information, see [All GitLab Features](https://about.gitlab.com/features/). - -### Concepts - -To get familiar with the concepts needed to develop code on GitLab, read the following articles: - -- [Demo: Mastering Code Review With GitLab](https://about.gitlab.com/blog/2017/03/17/demo-mastering-code-review-with-gitlab/). -- [What is GitLab Flow?](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/). -- [Tutorial: It's all connected in GitLab](https://about.gitlab.com/blog/2016/03/08/gitlab-tutorial-its-all-connected/): an overview on code collaboration with GitLab. -- [Trends in Version Control Land: Microservices](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). -- [Trends in Version Control Land: Innersourcing](https://about.gitlab.com/topics/version-control/what-is-innersource/). - -## Use cases - -GitLab is a Git-based platform that integrates a great number of essential tools for software development and deployment, and project management: - -- 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). -- 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). -- Building, testing, and deploying with built-in [Continuous Integration](../ci/index.md). -- View the current health and status of each CI environment running on Kubernetes with [deploy boards](project/deploy_boards.md). -- Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). -- Deploying personal and professional static websites with [GitLab Pages](project/pages/index.md). -- Integrating with Docker by using [GitLab Container Registry](packages/container_registry/index.md). -- Tracking the development lifecycle by using [GitLab Value Stream Analytics](analytics/value_stream_analytics.md). -- Provide support with [Service Desk](project/service_desk.md). -- [Export issues as CSV](project/issues/csv_export.md). - -With GitLab Enterprise Edition, you can also: - -- Improve collaboration with: - - [Merge request approvals](project/merge_requests/approvals/index.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 [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). -- [Mirror a repository](project/repository/mirror/index.md) from elsewhere on your local server. -- View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/pipelines/multi_project_pipelines.md). -- [Lock files](project/file_lock.md) to prevent conflicts. -- 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, Trello, Slack, Bamboo CI, Jira, and a lot more. - -## User types - -There are several types of users in GitLab: - -- Regular users. -- [Internal users](../development/internal_users.md) often referred to as bot or system users. -- [Auditor](permissions.md#auditor-users) with read access to self-managed instances. -- [GitLab Administrator](../administration/index.md) with full access to - self-managed instances including settings and the [Admin Area](admin_area/index.md). - -Each user can be a member in a [group](group/index.md). - -See the [permissions page](permissions.md) for details on how each user type is used. - -## User activity - -GitLab tracks user contribution activity. -You can follow or unfollow other users from their [user profiles](profile/index.md#access-your-user-profile). -To view a user's activity in a top-level Activity view: - -1. From a user's profile, select **Follow**. -1. In the GitLab menu, select **Activity**. -1. Select the **Followed users** tab. - -### User contribution events - -Each of these contribution events is tracked: - -- `approved` - - Merge request -- `closed` - - [Epic](group/epics/index.md) - - Issue - - Merge request - - Milestone -- `commented` on any `Noteable` record. - - Alert - - Commit - - Design - - Issue - - Merge request - - Snippet -- `created` - - Design - - [Epic](group/epics/index.md) - - Issue - - Merge request - - Milestone - - Project - - Wiki page -- `destroyed` - - Design - - Milestone - - Wiki page -- `expired` - - Project membership -- `joined` - - Project membership -- `left` - - Project membership -- `merged` - - Merge request -- `pushed` commits to (or deleted commits from) a repository, individually or in bulk. - - Project -- `reopened` - - [Epic](group/epics/index.md) - - Issue - - Merge request - - Milestone -- `updated` - - Design - - Wiki page - -## Projects - -In GitLab, you can create [projects](project/index.md) to host -your code, track issues, collaborate on code, and continuously -build, test, and deploy your app with built-in GitLab CI/CD. Or, you can do -it all at once, from one single project. - -- [Repositories](project/repository/index.md): Host your codebase in - repositories with version control and as part of a fully integrated platform. -- [Issues](project/issues/index.md): Explore the best of GitLab Issues' features. -- [Merge requests](project/merge_requests/index.md): Collaborate on code, - reviews, live preview changes per branch, and request approvals with merge requests. -- [Milestones](project/milestones/index.md): Work on multiple issues and merge - requests towards the same target date with Milestones. - -## Account - -There is a lot you can customize and configure to enjoy the best of GitLab. - -- [Settings](profile/index.md): Manage your user settings to change your personal information, - personal access tokens, authorized applications, etc. -- [Authentication](../topics/authentication/index.md): Read through the authentication - methods available in GitLab. -- [Permissions](permissions.md): Learn the different set of permissions levels for each - user type (guest, reporter, developer, maintainer, owner). -- [Feature highlight](feature_highlight.md): Learn more about the little blue dots - around the app that explain certain features. -- [Abuse reports](report_abuse.md): Report abuse from users to GitLab administrators. - -## Groups - -With GitLab [Groups](group/index.md) you can assemble related projects together -and grant members access to several projects at once. - -Groups can also be nested in [subgroups](group/subgroups/index.md). - -## Discussions - -In GitLab, you can comment and mention collaborators in issues, -merge requests, code snippets, and commits. - -When performing inline reviews to implementations -to your codebase through merge requests you can -gather feedback through [resolvable threads](discussions/index.md#resolve-a-thread). - -### GitLab Flavored Markdown (GFM) - -Read through the [GFM documentation](markdown.md) to learn how to apply -the best of GitLab Flavored Markdown in your threads, comments, -issues and merge requests descriptions, and everywhere else GFM is -supported. - -## To-Do List - -Never forget to reply to your collaborators. [GitLab To-Do List](todos.md) -is a tool for working faster and more effectively with your team, -by listing all user or group mentions, as well as issues and merge -requests you're assigned to. - -## Search - -[Search and filter](search/index.md) through groups, projects, issues, merge requests, files, code, and more. - -## Snippets - -[Snippets](snippets.md) are code blocks that you want to store in GitLab, from which -you have quick access to. You can also gather feedback on them through [Discussions](#discussions). - -## GitLab CI/CD - -Use built-in [GitLab CI/CD](../ci/index.md) to test, build, and deploy your applications -directly from GitLab. No third-party integrations needed. - -## Features behind feature flags - -Understand what [features behind feature flags](feature_flags.md) mean. - -## Keyboard shortcuts - -There are many [keyboard shortcuts](shortcuts.md) in GitLab to help you navigate between -pages and accomplish tasks faster. - -## Integrations - -[Integrate GitLab](../integration/index.md) with your preferred tool, such as Trello, Jira, etc. - -## Webhooks - -Configure [webhooks](project/integrations/webhooks.md) to listen for -specific events like pushes, issues or merge requests. GitLab sends a -POST request with data to the webhook URL. - -## API - -Automate GitLab via [API](../api/index.md). - -## Git and GitLab - -Learn what is [Git](../topics/git/index.md) and its best practices. - -## Instance-level analytics - -See [various statistics](admin_area/analytics/index.md) of your GitLab instance. - -## Operations Dashboard - -See [Operations Dashboard](operations_dashboard/index.md) for a summary of each project's operational health. +# Use GitLab **(FREE)** + +Get to know the GitLab end-to-end workflow. Configure permissions, +organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. + +- [Set up your organization](../topics/set_up_organization.md) +- [Organize work with projects](../user/project/index.md) +- [Plan and track work](../topics/plan_and_track.md) +- [Build your application](../topics/build_your_application.md) +- [Secure your application](../user/application_security/index.md) +- [Deploy and release your application](../topics/release_your_application.md) +- [Monitor application performance](../operations/index.md) +- [Monitor runner performance](https://docs.gitlab.com/runner/monitoring/index.html) +- [Manage your infrastructure](../user/infrastructure/index.md) +- [Analyze GitLab usage](../user/analytics/index.md) diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 87b8f510289..50899053cad 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -48,10 +48,13 @@ This project provides you with: ## Register the agent +FLAG: +In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `certificate_based_clusters` changed the **Actions** menu to focus on the agent rather than certificates. The flag is [enabled on GitLab.com and self-managed](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). + To create a GitLab agent for Kubernetes: 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select **Actions**. +1. Select **Connect a cluster (agent)**. 1. From the **Select an agent** dropdown list, select `eks-agent` and select **Register an agent**. 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. 1. GitLab provides an address for the agent server (KAS), which you will also need later. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 1ed8b0ef350..ab04187284d 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -6,6 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a Google GKE cluster +INFO: +Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), +and in partnership with Google, GitLab is able to offer an additional $200 for new +GCP accounts to get started with the GitLab integration with Google Kubernetes Engine. +[Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) +and apply for credit. + Learn how to create a new cluster on Google Kubernetes Engine (GKE) through [Infrastructure as Code (IaC)](../../index.md). This process uses the Google and Kubernetes Terraform providers create GKE clusters. You connect the clusters to GitLab @@ -48,10 +55,13 @@ with defaults for name, location, node count, and Kubernetes version. ## Register the agent +FLAG: +In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `certificate_based_clusters` changed the **Actions** menu to focus on the agent rather than certificates. The flag is [enabled on GitLab.com and self-managed](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). + To create a GitLab agent for Kubernetes: 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select **Actions**. +1. Select **Connect a cluster (agent)**. 1. From the **Select an agent** dropdown list, select `gke-agent` and select **Register an agent**. 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. 1. GitLab provides an address for the agent server (KAS), which you will also need later. diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index d76ef0b9359..d184d969ace 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -23,7 +23,7 @@ gitops: default_namespace: my-ns ``` -The agent creates an inventory object for every item in the `manifest_projects` list. +The agent creates an inventory object for every item in the `manifest_projects` list. The inventory object is stored in the namespace you specify for `default_namespace`. The name and location of the inventory object is based on: @@ -58,7 +58,7 @@ This action changes the location of the object in the cluster. inventory objects in the same namespace in the future. 1. Ensure the value for `cli-utils.sigs.k8s.io/inventory-id` is unique. This value is used for objects tracked by this inventory object. Their `config.k8s.io/owning-inventory` annotation is set to this value. - + The value doesn't have to match the `name` but it's convenient to set them to the same value. 1. Save the file with the manifest files as a single logical group. diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 01530422e4a..61ec0a559f0 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -18,7 +18,7 @@ in GitLab 14.5. It is expected to be [turned off by default in 15.0](../../../update/deprecations.md#certificate-based-integration-with-kubernetes) and removed in GitLab 15.6. -If you are using the certificate-based integration, you should move to another workflow as soon as possible. +If you are using the certificate-based integration, you should move to another workflow as soon as possible. As a general rule, to migrate clusters that rely on GitLab CI/CD, you can use the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). @@ -60,7 +60,7 @@ To configure your Auto DevOps project to use the GitLab agent: 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. From the certificate-based clusters section, open the cluster that serves the same environment scope. 1. Select the **Details** tab and disable the cluster. -1. To activate the changes, on the left sidebar, select **CI/CD > Variables > Run pipeline**. +1. To activate the changes, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. For an example, [view this project](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service). @@ -70,7 +70,11 @@ Follow the process for the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md ## Migrate from GitLab Managed applications -Follow the process to [migrate from GitLab Managed Apps to the cluster management project](../../clusters/migrating_from_gma_to_project_template.md). +[GitLab Managed Apps (GMA)](../../clusters/applications.md#gitlab-managed-apps-deprecated) were deprecated in GitLab 14.0, and +the agent for Kubernetes does not support them. To migrate from GMA to the agent, go through the following steps: + +1. [Migrate from GitLab Managed Apps to a cluster management project](../../clusters/migrating_from_gma_to_project_template.md). +1. [Migrate the cluster management project to use the agent](../../clusters/management_project_template.md). ## Migrate a cluster management project diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 3bc7495d4be..bc7a3c0d069 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -6,110 +6,121 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Infrastructure as Code with Terraform and GitLab **(FREE)** -With Terraform in GitLab, you can use GitLab authentication and authorization with -your GitOps and Infrastructure-as-Code (IaC) workflows. -Use these features if you want to collaborate on Terraform code within GitLab or would like to use GitLab as a Terraform state storage that incorporates best practices out of the box. +To manage your infrastructure with GitLab, you can use the integration with +Terraform to define resources that you can version, reuse, and share: + +- Manage low-level components like compute, storage, and networking resources. +- Manage high-level components like DNS entries and SaaS features. +- Incorporate GitOps deployments and Infrastructure-as-Code (IaC) workflows. +- Use GitLab as a Terraform state storage. +- Store and use Terraform modules to simplify common and complex infrastructure patterns. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch [a video overview](https://www.youtube.com/watch?v=iGXjUrkkzDI) of the features GitLab provides with the integration with Terraform. ## Integrate your project with Terraform > SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. -In GitLab 14.0 and later, to integrate your project with Terraform, add the following -to your `.gitlab-ci.yml` file: +The integration with GitLab and Terraform happens through GitLab CI/CD. +Use an `include` attribute to add the Terraform template to your project and +customize from there. -```yaml -include: - - template: Terraform.latest.gitlab-ci.yml +To get started, choose the template that best suits your needs: -variables: - # If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables - TF_STATE_NAME: default - TF_CACHE_KEY: default - # If your terraform files are in a subdirectory, set TF_ROOT accordingly - # TF_ROOT: terraform/production -``` +- [Latest template](#latest-terraform-template) +- [Stable template and advanced template](#stable-and-advanced-terraform-templates) -The `Terraform.latest.gitlab-ci.yml` template: +All templates: -- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). -- Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as +- Use the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as the Terraform state storage backend. -- Creates [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): - `test`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) - `test`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. -- Runs the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually), - that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`. +- Trigger four pipeline stages: `test`, `validate`, `build`, and `deploy`. +- Run Terraform commands: `test`, `validate`, `plan`, and `plan-json`. It also runs the `apply` only on the default branch. +- Run the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually). -You can override the values in the default template by updating your `.gitlab-ci.yml` file. +### Latest Terraform template -The latest template might contain breaking changes between major GitLab releases. -For a more stable template, we recommend: +The [latest template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml) +is compatible with the most recent GitLab version. It provides the most recent +GitLab features, but can potentially include breaking changes. -- [A ready-to-use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) -- [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) +You can safely use the latest Terraform template: -This video from January 2021 walks you through all the GitLab Terraform integration features: +- If you use GitLab.com. +- If you use a self-managed instance updated with every new GitLab release. -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> -</figure> +### Stable and advanced Terraform templates -## GitLab-managed Terraform state +If you use earlier versions of GitLab, you might face incompatibility errors +between the GitLab version and the template version. In this case, you can opt +to use one of these templates: + +- [The stable template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) with an skeleton that you can built on top of. +- [The advanced template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) to fully customize your setup. + +### Use a Terraform template + +To use a Terraform template: -[Terraform remote backends](https://www.terraform.io/language/settings/backends) -enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/language/settings/backends/http) -to securely store the state files in local storage (the default) or -[the remote store of your choice](../../../administration/terraform_state.md). +1. On the top bar, select **Menu > Projects** and find the project you want to integrate with Terraform. +1. On the left sidebar, select **Repository > Files**. +1. Edit your `.gitlab-ci.yml` file, use the `include` attribute to fetch the Terraform template: -The GitLab-managed Terraform state backend can store your Terraform state easily and -securely. It spares you from setting up additional remote resources like -Amazon S3 or Google Cloud Storage. Its features include: + ```yaml + include: + # To fetch the latest template, use: + - template: Terraform.latest.gitlab-ci.yml + # To fetch the stable template, use: + - template: Terraform/Base.gitlab-ci.yml + # To fetch the advanced template, use: + - template: Terraform/Base.latest.gitlab-ci.yml + ``` -- Supporting encryption of the state file both in transit and at rest. -- Locking and unlocking state. -- Remote Terraform plan and apply execution. +1. Add the variables as described below: -Read more about setting up and [using GitLab-managed Terraform states](terraform_state.md). + ```yaml + variables: + TF_STATE_NAME: default + TF_CACHE_KEY: default + # If your terraform files are in a subdirectory, set TF_ROOT accordingly. For example: + # TF_ROOT: terraform/production + ``` + +1. (Optional) Override in your `.gitlab-ci.yaml` file the attributes present +in the template you fetched to customize your configuration. + +## GitLab-managed Terraform state + +Use the [GitLab-managed Terraform state](terraform_state.md) to store state +files in local storage or in a remote store of your choice. ## Terraform module registry -GitLab can be used as a [Terraform module registry](../../packages/terraform_module_registry/index.md) -to create and publish Terraform modules to a private registry specific to your -top-level namespace. +Use GitLab as a [Terraform module registry](../../packages/terraform_module_registry/index.md) +to create and publish Terraform modules to a private registry. ## Terraform integration in merge requests -Collaborating around Infrastructure as Code (IaC) changes requires both code changes -and expected infrastructure changes to be checked and approved. GitLab provides a -solution to help collaboration around Terraform code changes and their expected -effects using the merge request pages. This way users don't have to build custom -tools or rely on 3rd party solutions to streamline their IaC workflows. - -Read more on setting up and [using the merge request integrations](mr_integration.md). +Use the [Terraform integration in merge requests](mr_integration.md) +to collaborate on Terraform code changes and Infrastructure-as-Code +workflows. ## The GitLab Terraform provider -WARNING: +NOTE: The GitLab Terraform provider is released separately from GitLab. -We are working on migrating the GitLab Terraform provider for GitLab.com. - -You can use the [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) -to manage various aspects of GitLab using Terraform. The provider is an open source project, -owned by GitLab, where everyone can contribute. +We are working on migrating the GitLab Terraform provider to GitLab.com. -The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) -is available as part of the official Terraform provider documentation. +The [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) is a plugin for Terraform to facilitate +managing of GitLab resources such as users, groups, and projects. +Its documentation is available on [Terraform](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs). ## Create a new cluster through IaC - Learn how to [create a new cluster on Amazon Elastic Kubernetes Service (EKS)](../clusters/connect/new_eks_cluster.md). - Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). -## Troubleshooting +## Related topics -See the [troubleshooting](troubleshooting.md) documentation. +- [Terraform images](https://gitlab.com/gitlab-org/terraform-images). +- [Troubleshooting](troubleshooting.md) issues with GitLab and Terraform. diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index bcad5c9279a..0fea05a3f03 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -23,7 +23,7 @@ recommend encrypting plan output or modifying the project visibility settings. ## Configure Terraform report artifacts -GitLab ships with a [pre-built CI template](index.md#integrate-your-project-with-terraform) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. +GitLab [integrates with Terraform](index.md#integrate-your-project-with-terraform) through CI/CD templates that use GitLab-managed Terraform state and display Terraform changes on merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. To manually configure a GitLab Terraform Report artifact: diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 39a57b60787..60f97f522cf 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -454,29 +454,6 @@ query ProjectTerraformStates { For those new to the GitLab GraphQL API, read [Getting started with GitLab GraphQL API](../../../api/graphql/getting_started.md). -## Troubleshooting +## Related topics -### Unable to lock Terraform state files in CI jobs for `terraform apply` using a plan created in a previous job - -When passing `-backend-config=` to `terraform init`, Terraform persists these values inside the plan -cache file. This includes the `password` value. - -As a result, to create a plan and later use the same plan in another CI job, you might get the error -`Error: Error acquiring the state lock` errors when using `-backend-config=password=$CI_JOB_TOKEN`. -This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration of the current job. - -As a workaround, use [http backend configuration variables](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables) in your CI job, -which is what happens behind the scenes when following the -[Get started using GitLab CI](#get-started-using-gitlab-ci) instructions. - -### Error: "address": required field is not set - -By default, we set `TF_ADDRESS` to `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}`. -If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with the error message -`Error: "address": required field is not set`. - -To resolve this, ensure that either `TF_ADDRESS` or `TF_STATE_NAME` is accessible in the -job that returned the error: - -1. Configure the [CI/CD environment scope](../../../ci/variables/#add-a-cicd-variable-to-a-project) for the job. -1. Set the job's [environment](../../../ci/yaml/#environment), matching the environment scope from the previous step. +- [Troubleshooting GitLab-managed Terraform state](troubleshooting.md). diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index ecefa20db99..bc0aa39bc70 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -66,3 +66,30 @@ with better Terraform-specific names. To resolve the syntax error, you can: my-Terraform-job: extends: .terraform:init # The updated name. ``` + +## Troubleshooting Terraform state + +### Unable to lock Terraform state files in CI jobs for `terraform apply` using a plan created in a previous job + +When passing `-backend-config=` to `terraform init`, Terraform persists these values inside the plan +cache file. This includes the `password` value. + +As a result, to create a plan and later use the same plan in another CI job, you might get the error +`Error: Error acquiring the state lock` errors when using `-backend-config=password=$CI_JOB_TOKEN`. +This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration of the current job. + +As a workaround, use [http backend configuration variables](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables) in your CI job, +which is what happens behind the scenes when following the +[Get started using GitLab CI](terraform_state.md#get-started-using-gitlab-ci) instructions. + +### Error: "address": required field is not set + +By default, we set `TF_ADDRESS` to `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}`. +If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with the error message +`Error: "address": required field is not set`. + +To resolve this, ensure that either `TF_ADDRESS` or `TF_STATE_NAME` is accessible in the +job that returned the error: + +1. Configure the [CI/CD environment scope](../../../ci/variables/#add-a-cicd-variable-to-a-project) for the job. +1. Set the job's [environment](../../../ci/yaml/#environment), matching the environment scope from the previous step. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index c81fdc275d9..fc2f1de5ce2 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -4,7 +4,9 @@ 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 --- -# GitLab Flavored Markdown **(FREE)** +# GitLab Flavored Markdown (GLFM) **(FREE)** + +> The abbreviation [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/24592) from `GFM` to `GLFM` in GitLab 14.10. GitLab automatically renders Markdown content. For example, when you add a comment to an issue, you type the text in the Markdown language. When you save the issue, the text is rendered @@ -525,6 +527,7 @@ GitLab Flavored Markdown recognizes the following: | merge request | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | | [epic](group/epics/index.md) | `&123` | `group1/subgroup&123` | | +| [iteration](group/iterations/index.md) | `*iteration:"iteration title"`| | | | [vulnerability](application_security/vulnerabilities/index.md) <sup>1</sup> | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | | feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | | label by ID | `~123` | `namespace/project~123` | `project~123` | @@ -819,7 +822,8 @@ Regardless of the tag names, the relative order of the reference tags determines numbering. <!-- -Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test. +The following codeblock uses HTML to skip the Vale ReferenceLinks test. +Do not change it back to a markdown codeblock. --> <pre class="highlight"><code>A footnote reference tag looks like this: [^1] @@ -926,7 +930,8 @@ ___ Examples: <!-- -Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test. +The following codeblock uses HTML to skip the Vale ReferenceLinks test. +Do not change it back to a markdown codeblock. --> <pre class="highlight"><code>Inline-style (hover to see title text): @@ -1192,17 +1197,18 @@ A new line due to the previous backslash. You can create links two ways: inline-style and reference-style. For example: <!-- -Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test. +The following codeblock uses HTML to skip the Vale ReferenceLinks test. +Do not change it back to a markdown codeblock. --> <pre class="highlight"><code>- This line shows an [inline-style link](https://www.google.com) -- This line shows a [link to a repository file in the same directory](index.md) -- This line shows a [relative link to a readme one directory higher](../index.md) +- This line shows a [link to a repository file in the same directory](permissions.md) +- This line shows a [relative link to a file one directory higher](../index.md) - This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!") Using header ID anchors: -- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview) +- This line links to [a section on a different Markdown page, using a "#" and the header ID](permissions.md#project-features-permissions) - This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) Using references: @@ -1219,13 +1225,13 @@ Some text to show that the reference links can follow later. </code></pre> - This line shows an [inline-style link](https://www.google.com) -- This line shows a [link to a repository file in the same directory](index.md) -- This line shows a [relative link to a README one directory higher](../index.md) +- This line shows a [link to a repository file in the same directory](permissions.md) +- This line shows a [relative link to a file one directory higher](../index.md) - This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!") Using header ID anchors: -- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview) +- This line links to [a section on a different Markdown page, using a "#" and the header ID](permissions.md#project-features-permissions) - This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) Using references: @@ -1406,6 +1412,16 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>. <!-- vale gitlab.Spelling = YES --> +### Keyboard HTML tag + +The `<kbd>` element is used to identify text that represents user keyboard input. Text surrounded by `<kbd>` tags is typically displayed in the browser's default monospace font. + +```html +Press <kbd>Enter</kbd> to go to the next page. +``` + +Press <kbd>Enter</kbd> to go to the next page. + ### Tables Tables are not part of the core Markdown spec, but they are part of GitLab Flavored Markdown. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index ea12b225717..901fb740717 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -171,6 +171,8 @@ When you publish: ## Install a Composer package +> Authorization to [download a package archive](../../../api/packages/composer.md#download-a-package-archive) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331601) in GitLab 14.10. + Install a package from the Package Registry so you can use it as a dependency. Prerequisites: @@ -354,6 +356,8 @@ used to access them: ## Troubleshooting +### Caching + To improve performance, Composer caches files related to a package. Note that Composer doesn't remove data by itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with this command: @@ -362,6 +366,14 @@ this command: composer clearcache ``` +### Authorization requirement when using `composer install` + +In GitLab 14.9 and earlier, you did not require authorization to use `composer install` if you already had a generated `composer.lock`. +If you committed your `composer.lock`, you could do a `composer install` in CI without setting up credentials. + +In GitLab 14.10 and later, authorization is required for the [downloading a package archive](../../../api/packages/composer.md#download-a-package-archive) endpoint. +If you encounter a credentials prompt when you are using `composer install`, follow the instructions in the [install a composer package](#install-a-composer-package) section to create an `auth.json` file. + ## Supported CLI commands The GitLab Composer repository supports the following Composer CLI commands: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 731ba04a9f7..b3eadc13772 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -428,3 +428,25 @@ 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 + +### Make output verbose + +For more verbose output when troubleshooting a Conan issue: + +```shell +export CONAN_TRACE_FILE=/tmp/conan_trace.log # Or SET in windows +conan <command> +``` + +You can find more logging tips in the [Conan documentation](https://docs.conan.io/en/latest/mastering/logging.html). + +### SSL Errors + +If you are using a self-signed certificate, there are two methods to manage SSL errors with Conan: + +- Use the `conan remote` command to disable the SSL verification. +- Append your server `crt` file to the `cacert.pem` file. + +Read more about this in the [Conan Documentation](https://docs.conan.io/en/latest/howtos/use_tls_certificates.html). diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 5b6c71d4dd2..59bb4a89b0b 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -626,13 +626,18 @@ Use your own URLs to complete the following steps: docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1 ``` +NOTE: +For container registry authentication, use either a +[personal access token](../../profile/personal_access_tokens.md) or a +[deploy token](../../project/deploy_tokens/index.md). + 1. Rename the images to match the new project name: ```shell docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1 ``` -1. Delete the images in both projects by using the [UI](#delete-images) or [API](../../../api/packages.md#delete-a-project-package). +1. Delete the images in the old project by using the [UI](#delete-images) or [API](../../../api/packages.md#delete-a-project-package). There may be a delay while the images are queued and deleted. 1. Change the path or transfer the project by going to **Settings > General** and expanding **Advanced**. @@ -698,7 +703,7 @@ Follow [this issue](https://gitlab.com/gitlab-org/container-registry/-/issues/55 ### Tags temporarily cannot be marked for deletion -GitLab is [migrating to the next generation of the Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523). -During the migration, you may encounter difficulty deleting tags. -If you encounter an error, it's likely that your image repository is in the process of being migrated. +GitLab is [migrating to the next generation of the Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523). +During the migration, you may encounter difficulty deleting tags. +If you encounter an error, it's likely that your image repository is in the process of being migrated. Please wait a few minutes and try again. diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index 7e8b2865b6e..2cfe99876fa 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -79,7 +79,7 @@ the Container Registry after the policy runs. The next time the policy runs, the so it may take multiple runs for all tags to be deleted. WARNING: -GitLab self-managed installs support for third-party container registries that comply with the +GitLab self-managed installations support third-party container registries that comply with the [Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/) specification. However, this specification does not include a tag delete operation. Therefore, when interacting with third-party container registries, GitLab uses a workaround to delete tags. See the @@ -217,7 +217,23 @@ Valid values for `cadence` when using the API are: - `1month` (every month) - `3month` (every quarter) -See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). +Valid values for `keep_n` (number of tags kept per image name) when using the API are: + +- `1` +- `5` +- `10` +- `25` +- `50` +- `100` + +Valid values for `older_than` (days until tags are automatically removed) when using the API are: + +- `7d` +- `14d` +- `30d` +- `90d` + +See the API documentation for further details: [Edit project API](../../../api/projects.md#edit-project). ### Use with external container registries diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index e431d4d7de3..5e66c8ed7a5 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -96,6 +96,14 @@ You can authenticate using: Users accessing the Dependency Proxy with a personal access token or username and password must have at least the Guest role for the group they pull images from. +The Dependency Proxy follows the [Docker v2 token authentication flow](https://docs.docker.com/registry/spec/auth/token/), +issuing the client a JWT to use for the pull requests. The JWT issued as a result of authenticating +expires after some time. When the token expires, most Docker clients store your credentials and +automatically request a new token without further action. + +The token expiration time is a [configurable setting](../../../administration/packages/dependency_proxy.md#changing-the-jwt-expiration). +On GitLab.com, the expiration time is 15 minutes. + #### SAML SSO When [SSO enforcement](../../group/saml_sso/index.md#sso-enforcement) @@ -132,7 +140,8 @@ There are other additional predefined CI/CD variables you can also use: - `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX`: the image prefix for pulling images through the dependency proxy from the direct group or subgroup that the project belongs to. -`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +`CI_DEPENDENCY_PROXY_SERVER`, `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`, and +`CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` include the server port. If you explicitly include the Dependency Proxy path, the port must be included, unless you have logged into the Dependency Proxy manually without including the port: diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 6e3af6a92d5..6a515b78fc1 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -283,7 +283,8 @@ To authenticate to the Package Registry, you need either a personal access token ### Authenticate with a personal access token in Gradle -Create a file `~/.gradle/gradle.properties` with the following content: +In [your `GRADLE_USER_HOME` directory](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home), +create a file `gradle.properties` with the following content: ```groovy gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN @@ -586,7 +587,7 @@ To publish a package by using Gradle: url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven" credentials(HttpHeaderCredentials) { name = "Private-Token" - value = gitLabPrivateToken // the variable resides in ~/.gradle/gradle.properties + value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties } authentication { header(HttpHeaderAuthentication) @@ -820,7 +821,7 @@ rm -rf ~/.m2/repository If you're using Gradle, run this command to clear the cache: ```shell -rm -rf ~/.gradle/caches +rm -rf ~/.gradle/caches # Or replace ~/.gradle with your custom GRADLE_USER_HOME ``` ### Review network trace logs diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index b980f6a5694..1f278bd1476 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -114,6 +114,26 @@ You can also remove the Package Registry for your project specifically: The **Packages & Registries > Package Registry** entry is removed from the sidebar. +## Package Registry visibility permissions + +[Project-level permissions](../../permissions.md) +determine actions such as downloading, pushing, or deleting packages. + +The visibility of the Package Registry is independent of the repository and can't be controlled from +your project's settings. For example, if you have a public project and set the repository visibility +to **Only Project Members**, the Package Registry is then public. However, disabling the Package +Registry disables all Package Registry operations. + +[GitLab-#329253](https://gitlab.com/gitlab-org/gitlab/-/issues/329253) +proposes adding the ability to control Package Registry visibility from the UI. + +| | | Anonymous<br/>(everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | +| -------------------- | --------------------- | --------- | ----- | ------------------------------------------ | +| Public project with Package Registry enabled | View Package Registry <br/> and pull packages | Yes | Yes | Yes | +| Internal project with Package Registry enabled | View Package Registry <br/> and pull packages | No | Yes | Yes | +| Private project with Package Registry enabled | View Package Registry <br/> and pull packages | No | No | Yes | +| Any project with Package Registry disabled | All operations on Package Registry | No | No | No | + ## Supported package managers WARNING: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index c90f575e83a..2282a7d876e 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -54,155 +54,158 @@ The following table lists project permissions available for each role: <!-- Keep this table sorted: By topic first, then by minimum role, then alphabetically. --> -| Action | Guest | Reporter | Developer | Maintainer | Owner | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|----------| -| [Analytics](analytics/index.md):<br>View issue analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) | | | | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) | | | | | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>View clusters | | | ✓ | ✓ | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*20*) | ✓ (*20*) | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create (*18*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set weight | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Close / reopen (*19*) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Move issues (*14*) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Approve (*8*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Create (*17*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Pull a package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) | | | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*9*) | ✓ (*9*) | ✓ (*9*) | ✓ | ✓ | -| [Projects](project/index.md):<br>View Insights | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*5*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View Requirements | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*12*) | ✓ (*12*) | ✓ (*12*) | -| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*10*) | ✓ | ✓ | -| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (*13*) | ✓ | -| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (*11*) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | -| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | -| [Projects](project/index.md):<br>Archive project | | | | | ✓ | -| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | -| [Projects](project/index.md):<br>Delete project | | | | | ✓ | -| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | -| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*4*) | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to protected branches (*4*) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Force push to protected branches (*3*) | | | | | | -| [Repository](project/repository/index.md):<br>Remove protected branches (*3*) | | | | | | -| [Requirements Management](project/requirements/index.md):<br>Archive / reopen | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Create / edit | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Import / export | | ✓ | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|----------| +| [Analytics](analytics/index.md):<br>View [issue analytics](analytics/issue_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [value stream analytics](analytics/value_stream_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) | | | | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) | | | | | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View clusters | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/index.md#delete-images-by-using-a-cleanup-policy) | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*20*) | ✓ (*20*) | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create (*18*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [related issues](project/issues/related_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Close / reopen (*19*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage [related issues](project/issues/related_issues.md) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Move issues (*14*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Archive [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Approve (*8*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Create (*17*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](discussions/#resolve-a-thread) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Pull a package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) | | | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*9*) | ✓ (*9*) | ✓ (*9*) | ✓ | ✓ | +| [Projects](project/index.md):<br>View [Insights](project/insights/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*5*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [Requirements](project/requirements/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*12*) | ✓ (*12*) | ✓ (*12*) | +| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Enable [Review Apps](../ci/review_apps/index.md) | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*10*) | ✓ | ✓ | +| [Projects](project/index.md):<br>Add [deploy keys](project/deploy_keys/index.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Add new [team members](project/members/index.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Change [project features visibility](public_access.md) level | | | | ✓ (*13*) | ✓ | +| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (*11*) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | +| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Assign project to a [compliance framework](project/settings/index.md#compliance-frameworks) | | | | | ✓ | +| [Projects](project/index.md):<br>Archive project | | | | | ✓ | +| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | +| [Projects](project/index.md):<br>Delete project | | | | | ✓ | +| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | +| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | +| [Projects](project/index.md): View [Usage Quotas](usage_quotas.md) page | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*4*) | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches (*4*) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Force push to protected branches (*3*) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (*3*) | | | | | | +| [Requirements Management](project/requirements/index.md):<br>Archive / reopen | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Create / edit | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Import / export | | ✓ | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | <!-- markdownlint-disable MD029 --> @@ -224,7 +227,7 @@ The following table lists project permissions available for each role: supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). 12. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access Developers and Maintainers are given. 13. A Maintainer can't change project features visibility level if - [project visibility](../public_access/public_access.md) is set to private. + [project visibility](public_access.md) is set to private. 14. Attached design files are moved together with the issue even if the user doesn't have the Developer role. 15. Guest users can only set metadata (for example, labels, assignees, or milestones) @@ -262,6 +265,7 @@ More details about the permissions for some project-level features follow. | View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | | View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | [View vulnerabilities in a pipeline](application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View and download project-level [Secure Files](../api/secure_files.md) | | | | ✓ | ✓ | ✓ | | Cancel and retry jobs | | | | ✓ | ✓ | ✓ | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | | Delete job logs or job artifacts | | | | ✓ (*4*) | ✓ | ✓ | @@ -276,6 +280,7 @@ More details about the permissions for some project-level features follow. | Manage CI/CD settings | | | | | ✓ | ✓ | | Manage job triggers | | | | | ✓ | ✓ | | Manage project-level CI/CD variables | | | | | ✓ | ✓ | +| Manage project-level [Secure Files](../api/secure_files.md) | | | | | ✓ | ✓ | | Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | | ✓ | ✓ | | Delete pipelines | | | | | | ✓ | @@ -391,7 +396,6 @@ The following table lists group permissions available for each role: | View [Group DevOps Adoption](group/devops_adoption/index.md) | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | View [Productivity analytics](analytics/productivity_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| View Usage quota data | | ✓ | ✓ | ✓ | ✓ | | Create and edit [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | | Create project in group | | | ✓ (3)(5) | ✓ (3) | ✓ (3) | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | @@ -407,7 +411,7 @@ The following table lists group permissions available for each role: | List group deploy tokens | | | | ✓ | ✓ | | Manage [group push rules](group/index.md#group-push-rules) | | | | ✓ | ✓ | | View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | -| Administer project compliance frameworks | | | | | ✓ | +| Create and manage compliance frameworks | | | | | ✓ | | Create/Delete group deploy tokens | | | | | ✓ | | Change group visibility level | | | | | ✓ | | Delete group | | | | | ✓ | @@ -421,8 +425,8 @@ The following table lists group permissions available for each role: | Share (invite) groups with groups | | | | | ✓ | | View 2FA status of members | | | | | ✓ | | View [Billing](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) | | | | | ✓ (4) | -| View [Usage Quotas](usage_quotas.md) Page | | | | ✓ | ✓ (4) | -| Manage runners | | | | | ✓ | +| View group [Usage Quotas](usage_quotas.md) page | | | | | ✓ (4) | +| Manage group runners | | | | | ✓ | <!-- markdownlint-disable MD029 --> diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index f201e04183c..a86968654c7 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -88,7 +88,7 @@ The following is hidden from your user profile page (`https://gitlab.example.com - 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. +Making your user profile page private does not hide all your public resources from the REST or GraphQL APIs. ### User visibility @@ -123,7 +123,7 @@ To create a new project and add its README to your profile: 1. For **Project Configuration**, ensure **Initialize repository with a README** is selected. 1. Select **Create project**. 1. Create a README file inside this project. The file can be any valid [README or index file](../project/repository/index.md#readme-and-index-files). -1. Populate the README file with [Markdown](../markdown.md). +1. Populate the README file with [Markdown](../markdown.md), or another [supported markup language](../project/repository/index.md#supported-markup-languages). GitLab displays the contents of your README below your contribution graph. @@ -150,7 +150,7 @@ To add links to other accounts: ## Show private contributions on your user profile page -In the user contribution calendar graph and recent activity list, you can see your [contribution actions](../index.md#user-contribution-events) to private projects. +In the user contribution calendar graph and recent activity list, you can see your [contribution actions](#user-contribution-events) to private projects. To show private contributions: @@ -322,6 +322,65 @@ and configure it on your local machine by using the following command: git config --global user.email <your email address> ``` +## User activity + +GitLab tracks user contribution activity. +You can follow or unfollow other users from their [user profiles](#access-your-user-profile). +To view a user's activity in a top-level Activity view: + +1. From a user's profile, select **Follow**. +1. In the GitLab menu, select **Activity**. +1. Select the **Followed users** tab. + +### User contribution events + +Each of these contribution events is tracked: + +- `approved` + - Merge request +- `closed` + - [Epic](../group/epics/index.md) + - Issue + - Merge request + - Milestone +- `commented` on any `Noteable` record. + - Alert + - Commit + - Design + - Issue + - Merge request + - Snippet +- `created` + - Design + - [Epic](../group/epics/index.md) + - Issue + - Merge request + - Milestone + - Project + - Wiki page +- `destroyed` + - Design + - Milestone + - Wiki page +- `expired` + - Project membership +- `joined` + - Project membership +- `left` + - Project membership +- `merged` + - Merge request +- `pushed` commits to (or deleted commits from) a repository, individually or in bulk. + - Project +- `reopened` + - [Epic](../group/epics/index.md) + - Issue + - Merge request + - Milestone +- `updated` + - Design + - Wiki page + ## Troubleshooting ### Why do I keep getting signed out? @@ -379,6 +438,6 @@ Without the `config.extend_remember_period` flag, you would be forced to sign in - [Receive emails for sign-ins from unknown IP addresses or devices](unknown_sign_in_notification.md) - Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications -- Manage [SSH keys](../../ssh/index.md) to access your account via SSH +- Manage [SSH keys](../ssh.md) to access your account via SSH - Change your [syntax highlighting theme](preferences.md#syntax-highlighting-theme) - [View your active sessions](active_sessions.md) and revoke any of them if necessary diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 4c9622810b2..d0e9b427f1c 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -11,7 +11,7 @@ Stay informed about what's happening in GitLab with email notifications. You can receive updates about activity in issues, merge requests, epics, and designs. For the tool that GitLab administrators can use to send messages to users, read -[Email from GitLab](../../tools/email.md). +[Email from GitLab](../admin_area/email_from_gitlab.md). ## Who receives notifications @@ -21,11 +21,14 @@ that happen there. You might receive notifications for one of the following reasons: - You participate in an issue, merge request, epic, or design. You become a participant when you comment - or edit, or someone mentions you. + or edit, or someone mentions <sup>1</sup> you. - You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). - You've configured notifications for the [project](#change-level-of-project-notifications) or [group](#group-notifications). - You're subscribed to group or project pipeline notifications via the pipeline emails [integration](../project/integrations/overview.md). +1. GitLab doesn't send a notification when + [a comment is edited to include a user mention](../discussions/index.md#editing-a-comment-to-add-a-mention). + NOTE: Administrators can block notifications, preventing them from being sent. @@ -171,26 +174,27 @@ Users are notified of the following events: <!-- The table is sorted first by recipient, then alphabetically. --> -| Event | Sent to | Settings level | -|------------------------------|---------------------|------------------------------| -| New release | Project members | Custom notification. | -| Project moved | Project members | Any other than disabled. | -| Email changed | User | Security email, always sent. | -| Group access level changed | User | Sent when user group access level is changed. | -| New email added | User | Security email, always sent. | -| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 | -| New SSH key added | User | Security email, always sent. | -| New user created | User | Sent on user creation, except for OmniAuth (LDAP). | -| Password changed | User | Security email, always sent when user changes their own password. | -| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user. | -| Personal access tokens expiring soon | User | Security email, always sent. | -| Personal access tokens have been created | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337591) in GitLab 14.9. | -| Personal access tokens have expired | User | Security email, always sent. | -| Project access level changed | User | Sent when user project access level is changed. | -| SSH key has expired | User | Security email, always sent. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12._ | -| Two-factor authentication disabled | User | Security email, always sent. | -| User added to group | User | Sent when user is added to group. | -| User added to project | User | Sent when user is added to project. | +| Event | Sent to | Settings level | +|------------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| New release | Project members | Custom notification. | +| Project moved | Project members | Any other than disabled. | +| Email changed | User | Security email, always sent. | +| Group access level changed | User | Sent when user group access level is changed. | +| New email address added | User | Security email, sent to primary email address. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337635) in GitLab 14.9._ | +| New email address added | User | Security email, sent to newly-added email address. | +| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8._ | +| New SSH key added | User | Security email, always sent. | +| New user created | User | Sent on user creation, except for OmniAuth (LDAP). | +| Password changed | User | Security email, always sent when user changes their own password. | +| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user. | +| Personal access tokens expiring soon | User | Security email, always sent. | +| Personal access tokens have been created | User | Security email, always sent. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337591) in GitLab 14.9._ | +| Personal access tokens have expired | User | Security email, always sent. | +| Project access level changed | User | Sent when user project access level is changed. | +| SSH key has expired | User | Security email, always sent. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12._ | +| Two-factor authentication disabled | User | Security email, always sent. | +| User added to group | User | Sent when user is added to group. | +| User added to project | User | Sent when user is added to project. | ## Notifications on issues, merge requests, and epics @@ -241,26 +245,26 @@ epics: | Event | Sent to | |------------------------|---------| -| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected. | -| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected. | +| Change milestone issue | Subscribers and participants mentioned. | +| Change milestone merge request | Subscribers and participants mentioned. | | Close epic | | | Close issue | | | Close merge request | | -| Due issue | Participants and Custom notification level with this event selected. | | Failed pipeline | The author of the pipeline. | | Fixed pipeline | The author of the pipeline. Enabled by default. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1._ | +| Issue due | Participants and Custom notification level with this event selected. | | Merge merge request | | | Merge when pipeline succeeds | Author, Participants, Watchers, Subscribers, and Custom notification level with this event selected. Custom notification level is ignored for Author, Watchers and Subscribers. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4._ | | Merge request [marked as ready](../project/merge_requests/drafts.md) | Watchers and participants. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15332) in GitLab 13.10._ | -| New comment | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | | New epic | | | New issue | | | New merge request | | +| New note | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | | Push to merge request | Participants and Custom notification level with this event selected. | | Reassign issue | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | | Reassign merge request | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | -| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected. | -| Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected. | +| Remove milestone issue | Subscribers and participants mentioned. | +| Remove milestone merge request | Subscribers and participants mentioned. | | Reopen epic | | | Reopen issue | | | Reopen merge request | | @@ -304,7 +308,7 @@ If you no longer wish to receive any email notifications: **Disabled**. On self-managed installations, even after doing this, your instance administrator -[can still email you](../../tools/email.md). +[can still email you](../admin_area/email_from_gitlab.md). To unsubscribe, select the unsubscribe link in one of these emails. ## Email headers you can use to filter email diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 1fbbe438370..4c132094d24 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -98,8 +98,8 @@ A personal access token can perform actions based on the assigned scopes. | `read_api` | Read-only for the complete API, including all groups and projects, the Container Registry, and the Package Registry. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) in GitLab 12.10.) | | `read_repository` | Read-only (pull) for the repository through `git clone`. | | `write_repository` | Read-write (pull, push) for the repository through `git clone`. | -| `read_registry` | Read-only (pull) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | Read-write (push) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | +| `read_registry` | Read-only (pull) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. | +| `write_registry` | Read-write (push) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | | `sudo` | API actions as any user in the system (if the authenticated user is an administrator). | ## When personal access tokens expire diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 48160bb97ac..ecd6e83efa1 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -89,6 +89,20 @@ The default syntax theme is White, and you can choose among 5 different themes: Introduced in GitLab 13.6, the themes [Solarized](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) also apply to the [Web IDE](../project/web_ide/index.md) and [Snippets](../snippets.md). +## Diff colors + +A diff compares the old/removed content with the new/added content (e.g. when +[reviewing a merge request](../project/merge_requests/reviews/index.md#review-a-merge-request) or in a +[Markdown inline diff](../markdown.md#inline-diff)). +Typically, the colors red and green are used for removed and added lines in diffs. +The exact colors depend on the selected [syntax highlighting theme](#syntax-highlighting-theme). +The colors may lead to difficulties in case of red–green color blindness. + +For this reason, you can customize the following colors: + +- Color for removed lines +- Color for added lines + ## Behavior The following settings allow you to customize the behavior of the GitLab layout diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index f6f31ee8f36..c897100f14e 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Container Host Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index 25e2f6ddb91..af3128e3006 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Container Host Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. The following steps are recommended for installing Container Host Security. diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index eeaf7e82ef4..b294859c660 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Container Network Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 43f4ea6c326..7671ed7eb73 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Container Network Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. The following steps are recommended for installing Container Network Security. diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md index 3a80132fb50..6b89f7f1557 100644 --- a/doc/user/project/clusters/protect/index.md +++ b/doc/user/project/clusters/protect/index.md @@ -12,7 +12,7 @@ WARNING: The Container Network Security and Container Host Security features are in their end-of-life processes. They're [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md). diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index f1071af7c1f..7f35caf2a68 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -48,8 +48,8 @@ After the job succeeds, code intelligence data can be viewed while browsing the ## Find references -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217392) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235735) in GitLab 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217392) in GitLab 13.2 [with a flag](../../administration/feature_flags.md) named `code_navigation_references`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/225621) in GitLab 13.3. Feature flag `code_navigation_references` removed. To find where a particular object is being used, you can see links to specific lines of code under the **References** tab: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index fefc27063a6..e37ff560080 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -124,8 +124,8 @@ Only one CODEOWNERS pattern can match per file path. ### Organize Code Owners by putting them into sections -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 behind a feature flag, enabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed. You can organize Code Owners by putting them into named sections. @@ -254,6 +254,11 @@ README @group @group/with-nested/subgroup # `docs/index.md` but not `docs/projects/index.md`: /docs/* @root-docs +# Include `/**` to specify Code Owners for all subdirectories +# in a directory. This rule matches `docs/projects/index.md` or +# `docs/development/index.md` +/docs/**/*.md @root-docs + # This code makes matches a `lib` directory nested anywhere in the repository: lib/ @lib-owner diff --git a/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png b/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png Binary files differdeleted file mode 100644 index 15e6e71803c..00000000000 --- a/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png +++ /dev/null diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index b7674be2fa0..8f1da4b278a 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -69,7 +69,7 @@ The deploy keys available are listed: Prerequisites: - You must have at least the Maintainer role for the project. -- [Generate an SSH key pair](../../../ssh/index.md#generate-an-ssh-key-pair). Put the private SSH +- [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. 1. On the top bar, select **Menu > Projects** and find your project. @@ -87,7 +87,7 @@ name and permissions. Prerequisites: - You must have administrator access. -- [Generate an SSH key pair](../../../ssh/index.md#generate-an-ssh-key-pair). Put the private SSH +- [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. To create a public deploy key: diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 4d69209aafa..64c18ab6f3b 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -16,7 +16,9 @@ container registry images of a project without having a user and a password. Deploy tokens can be managed only by users with the Maintainer role. -Deploy tokens cannot be used with the GitLab API. +Deploy tokens can't be used with the GitLab public API. However, you can use deploy tokens with some +endpoints, such as those from the Package Registry. For details, see +[Authenticate with the registry](../../packages/package_registry/index.md#authenticate-with-the-registry). Deploy tokens are tied to the project and stay enabled even when the user who created the token is removed from the project. diff --git a/doc/user/project/img/promote_to_parent_group_workaround_v14_10.png b/doc/user/project/img/promote_to_parent_group_workaround_v14_10.png Binary files differnew file mode 100644 index 00000000000..ed4ac9ba234 --- /dev/null +++ b/doc/user/project/img/promote_to_parent_group_workaround_v14_10.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 8c0d9fc422b..b2425686024 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -49,7 +49,7 @@ The importer will create any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository will be imported under the user's namespace that started the import process. -## Requirements for user-mapped contributions +## Requirements for user-mapped contributions For user contributions to be mapped, each user must complete the following before the project import: @@ -83,7 +83,7 @@ For user contributions to be mapped, each user must complete the following befor ### If you have more than one Bitbucket account -Be sure to sign in to the correct account. +Be sure to sign in to the correct account. If you've accidentally started the import process with the wrong account, follow these steps: diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 4e3642eb3bd..b6241dbbdb0 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,11 +24,10 @@ created as private in GitLab as well. ## Import your Bitbucket repositories -Prerequisites: +Prerequisite: - An administrator must have enabled the **Bitbucket Server** in **Admin > Settings > General > Visibility and access controls > Import sources**. -- Review the importer's [limitations](#limitations). To import your Bitbucket repositories: @@ -41,24 +40,27 @@ To import your Bitbucket repositories: 1. Select the projects to import, or import all projects. You can filter projects by name and select the namespace for which to import each project. -## Limitations +### Items that are not imported -- GitLab doesn't allow comments on arbitrary lines of code. Any out-of-bounds Bitbucket comments are - inserted as comments in the merge request. -- Bitbucket Server allows multiple threading levels. The importer collapses this into one thread and - quotes part of the original comment. -- Declined pull requests have unreachable commits. This prevents the importer from generating a - proper diff. These pull requests show up as empty changes. -- Project filtering doesn't support fuzzy search. Only starts with or full match strings are - supported. - -The following aren't imported: +The following items aren't imported: - Pull request approvals - Attachments in Markdown - Task lists - Emoji reactions +### Items that are imported but changed + +The following items are changed when they are imported: + +- GitLab doesn't allow comments on arbitrary lines of code. Any out-of-bounds Bitbucket comments are + inserted as comments in the merge request. +- Multiple threading levels are collapsed into one thread and + quotes are added as part of the original comment. +- Declined pull requests have unreachable commits. These pull requests show up as empty changes. +- Project filtering doesn't support fuzzy search. Only **starts with** or **full match** strings are + supported. + ## User assignment When issues and pull requests are importing, the importer tries to find the author's email address diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 9f1c049045c..329d91916e8 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -30,7 +30,7 @@ The following aspects of a project are imported: References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility -level is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), +level is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or diff --git a/doc/user/project/import/img/gitlab_import_history_page_v14_10.png b/doc/user/project/import/img/gitlab_import_history_page_v14_10.png Binary files differnew file mode 100644 index 00000000000..c93b5ed2b27 --- /dev/null +++ b/doc/user/project/import/img/gitlab_import_history_page_v14_10.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 41ef15108ec..432f043f945 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -30,6 +30,30 @@ repository is too large, the import can timeout. You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). +## Project import history + +You can view all project imports created by you. This list includes the following: + +- Source (without credentials for security reasons) +- Destination +- Status +- Error details if the import failed + +To view project import history: + +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **History**. + + + +The history also includes projects created from [built-in](../working_with_projects.md#create-a-project-from-a-built-in-template) +or [custom](../working_with_projects.md#create-a-project-from-a-built-in-template) +templates. GitLab uses [import repository by URL](repo_by_url.md) +to create a new project from a template. + ## LFS authentication When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 801c2520bda..60a4ca5c0ea 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -11,7 +11,7 @@ your codebase. You can also use projects to track issues, plan work, collaborate on code, and continuously build, test, and use built-in CI/CD to deploy your app. -Projects can be available [publicly, internally, or privately](../../public_access/public_access.md). +Projects can be available [publicly, internally, or privately](../public_access.md). GitLab does not limit the number of private projects you can create. ## Project features @@ -35,7 +35,7 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Deploy tokens](deploy_tokens/index.md): Manage access to the repository and Container Registry. - [Web IDE](web_ide/index.md) - [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a - vulnerability in your project. **(FREE SAAS)** + vulnerability in your project. **Issues and merge requests:** @@ -83,7 +83,7 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Kubernetes cluster integration](../infrastructure/clusters/index.md): Connect your GitLab project with a Kubernetes cluster. - [Feature Flags](../../operations/feature_flags.md): Ship different features - by dynamically toggling functionality. **(PREMIUM)** + by dynamically toggling functionality. - [GitLab Pages](pages/index.md): Build, test, and deploy your static website. @@ -92,8 +92,8 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Wiki](wiki/index.md): Document your GitLab project in an integrated Wiki. - [Snippets](../snippets.md): Store, share and collaborate on code snippets. - [Value Stream Analytics](../analytics/value_stream_analytics.md): Review your development lifecycle. -- [Insights](insights/index.md): Configure the insights that matter for your projects. **(ULTIMATE)** -- [Security Dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)** +- [Insights](insights/index.md): Configure the insights that matter for your projects. +- [Security Dashboard](../application_security/security_dashboard/index.md) - [Syntax highlighting](highlighting.md): Customize your code blocks, overriding the default language choice. - [Badges](badges.md): Add an image to the **Project information** page. @@ -102,9 +102,9 @@ Projects include the following [features](https://about.gitlab.com/features/): associated with a released version of your code. - [Package Registry](../packages/package_registry/index.md): Publish and install packages. - [Code owners](code_owners.md): Specify code owners for specific files. -- [License Compliance](../compliance/license_compliance/index.md): Approve and deny licenses for projects. **(ULTIMATE)** -- [Dependency List](../application_security/dependency_list/index.md): View project dependencies. **(ULTIMATE)** -- [Requirements](requirements/index.md): Create criteria to check your products against. **(ULTIMATE)** +- [License Compliance](../compliance/license_compliance/index.md): Approve and deny licenses for projects. +- [Dependency List](../application_security/dependency_list/index.md): View project dependencies. +- [Requirements](requirements/index.md): Create criteria to check your products against. - [Code Intelligence](code_intelligence.md): Navigate code. ## Project integrations diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index b4d7790df1d..a10e261f10e 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,8 +32,8 @@ In Asana, create a 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. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Asana. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index a54a3adc408..4a9a8d62098 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,7 +14,8 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Bugzilla**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index ad7719f0e5b..b7e25b815fc 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -26,8 +26,9 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings. That is, **Project > Settings > Integrations**. -1. Select the **Discord Notifications** integration to configure it. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. 1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. 1. Paste the webhook URL that you copied from the create Discord webhook step. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 33c197b962e..c1c48c7fb12 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -9,17 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w By enabling this service, you receive email notifications for every change that is pushed to your project. -From the [Integrations page](overview.md#accessing-integrations) -select **Emails on push** service to activate and configure it. +To enable emails on push: -In the _Recipients_ area, provide a list of emails separated by spaces or newlines. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Emails on push**. +1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. +1. Configure the following options: -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 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. + - **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 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/ewm.md b/doc/user/project/integrations/ewm.md index bc9b2d59db3..b02f1a06e96 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,7 +14,8 @@ This IBM product was [formerly named Rational Team Concert](https://jazz.net/blo To enable the EWM integration, in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **EWM**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 7e8de776619..2dae02dc093 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -25,8 +25,6 @@ the [Slack App Directory](https://slack.com/apps). Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/-/profile/slack/edit) where you can select a project to enable the GitLab Slack application for. - - ## Configuration Alternatively, you can configure the Slack application with a project's diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index d66e2222538..2a1b12057aa 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -6,6 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Harbor container registry integration **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. + Use Harbor as the container registry for your GitLab project. [Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud native compute platforms, like Kubernetes and Docker. @@ -43,7 +45,7 @@ After the Harbor integration is activated: ## Secure your requests to the Harbor APIs For each API request through the Harbor integration, the credentials for your connection to the Harbor API use -the `username:password` combination. The following are suggestions for safe use: +the `username:password` combination. The following are suggestions for safe use: - Use TLS on the Harbor APIs you connect to. - Follow the principle of least privilege (for access on Harbor) with your credentials. diff --git a/doc/user/project/integrations/img/failed_badges.png b/doc/user/project/integrations/img/failed_badges.png Binary files differindex d44415a8687..5a1f481e54c 100644 --- a/doc/user/project/integrations/img/failed_badges.png +++ b/doc/user/project/integrations/img/failed_badges.png diff --git a/doc/user/project/integrations/img/failed_banner.png b/doc/user/project/integrations/img/failed_banner.png Binary files differindex ba40c1301d6..4384ce07873 100644 --- a/doc/user/project/integrations/img/failed_banner.png +++ b/doc/user/project/integrations/img/failed_banner.png diff --git a/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png b/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png Binary files differdeleted file mode 100644 index 57cd35c9f5d..00000000000 --- a/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png +++ /dev/null diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 279b139bacd..b2c2aea2c2b 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,9 +39,8 @@ network. For more details, read ## Complete these steps in GitLab -1. On the top bar, select **Menu > Projects** and find the project you want to - configure for notifications. -1. Navigate to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. 1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty, diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index f3f8d900e12..7dd4c1d1a8b 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -37,27 +37,25 @@ Display name override is not enabled by default, you need to ask your administra ## Configure GitLab to send notifications to Mattermost 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. Select the GitLab events -you want to generate notifications for. - -For each event you select, input the Mattermost channel you want to receive the -notification. You do not need to add the hash sign (`#`). - -Then fill in the integration configuration: - -- **Webhook**: The incoming webhook URL on Mattermost, similar to - `http://mattermost.example/hooks/5xo…`. -- **Username**: Optional. The username shown in messages sent to Mattermost. - To change the bot's username, provide a value. -- **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want - notifications about failed pipelines only. -- **Branches for which notifications are to be sent**: The branches to send notifications for. -- **Labels to be notified**: Optional. Labels required for the issue or merge request - to trigger a notification. Leave blank to notify for all issues and merge requests. -- **Labels to be notified behavior**: When you use the **Labels to be notified** filter, - messages are sent when an issue or merge request contains _any_ of the labels specified - in the filter. You can also choose to trigger messages only when the issue or merge request - contains _all_ the labels defined in the filter. +to send the notifications: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Mattermost notifications**. +1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel + to receive the notification. You do not need to add the hash sign (`#`). +1. Fill in the integration configuration: + + - **Webhook**: The incoming webhook URL on Mattermost, similar to + `http://mattermost.example/hooks/5xo…`. + - **Username**: Optional. The username shown in messages sent to Mattermost. + To change the bot's username, provide a value. + - **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want + notifications about failed pipelines only. + - **Branches for which notifications are to be sent**: The branches to send notifications for. + - **Labels to be notified**: Optional. Labels required for the issue or merge request + to trigger a notification. Leave blank to notify for all issues and merge requests. + - **Labels to be notified behavior**: When you use the **Labels to be notified** filter, + messages are sent when an issue or merge request contains _any_ of the labels specified + in the filter. You can also choose to trigger messages only when the issue or merge request + contains _all_ the labels defined in the filter. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 2cb62b8924e..081780e6277 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -22,9 +22,9 @@ want to configure. ## Integrations listing -Click on the service links to see further configuration instructions and details. +Click on the integration links to see further configuration instructions and details. -| Service | Description | Service hooks | +| Integration | Description | Integration hooks | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | | [Asana](asana.md) | Add commit messages as comments to Asana tasks. | **{dotted-circle}** No | | Assembla | Manage projects. | **{dotted-circle}** No | @@ -69,7 +69,7 @@ Click on the service links to see further configuration instructions and details > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17874) in GitLab 12.4. -If a single push includes changes to more than three branches or tags, services +If a single push includes changes to more than three branches or tags, integrations supported by `push_hooks` and `tag_push_hooks` events aren't executed. The number of branches or tags supported can be changed via @@ -89,12 +89,12 @@ By default, the SSL certificate for outgoing HTTP requests is verified based on an internal list of Certificate Authorities. This means the certificate cannot be self-signed. -You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook) +You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook-in-gitlab) and some integrations. ## 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. Learn more about [troubleshooting service hooks](webhooks.md#troubleshoot-webhooks). +Some integrations use hooks for integration with external applications. To confirm which ones use integration hooks, see the [integrations listing](#integrations-listing) above. Learn more about [troubleshooting integration hooks](webhooks.md#troubleshoot-webhooks). ### Uninitialized repositories diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 8b17f4afaa8..7f5414b86de 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,8 +37,8 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar 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. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Pivotal Tracker. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 760b5030416..068a2810a53 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -62,9 +62,9 @@ GitLab can use these to access the resource. More information about authenticati service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). -1. Navigate to the [Integrations page](overview.md#accessing-integrations) at - **Settings > Integrations**. -1. Click the **Prometheus** service. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Prometheus**. 1. For **API URL**, provide the domain name or IP address of your server, such as `http://prometheus.example.com/` or `http://192.0.2.1/`. 1. (Optional) In **Google IAP Audience Client ID**, provide the Client ID of the @@ -73,7 +73,7 @@ service account can be found at Google's documentation for Service Account credentials file that is authorized to access the Prometheus resource. The JSON key `token_credential_uri` is discarded to prevent [Server-side Request Forgery (SSRF)](https://www.hackerone.com/application-security/how-server-side-request-forgery-ssrf). -1. Click **Save changes**. +1. Select **Save changes**.  @@ -83,11 +83,12 @@ You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prom with GitLab. Use the domain name or IP address of the Thanos server you'd like to integrate with. -1. Navigate to the [Integrations page](overview.md#accessing-integrations). -1. Click the **Prometheus** service. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Prometheus**. 1. Provide the domain name or IP address of your server, for example `http://thanos.example.com/` or `http://192.0.2.1/`. -1. Click **Save changes**. +1. Select **Save changes**. ### Precedence with multiple Prometheus configurations diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index e8d611af30d..08488c33ac7 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab supports automatically detecting and monitoring AWS resources, starting with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) (ELB). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 76d13d5487c..ad2cb2681b9 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 9bdd4945f5d..aba14e1f3e9 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 33a06958e0c..9a9880a0cb6 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring Kubernetes metrics. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index ecf75d7b17a..2825066b8b0 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring NGINX. This is provided by leveraging the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter), which translates [VTS statistics](https://github.com/vozlt/nginx-module-vts) into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index e123000e0c5..6e751b907eb 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. 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 fda7744e847..e1eee649f0a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. NOTE: [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 05d7c31a288..bcab8d05f69 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -10,7 +10,8 @@ Use [Redmine](https://www.redmine.org/) as the issue tracker. To enable the Redmine integration in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Redmine**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index cddb72a83b2..5ad344a7d8e 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -18,7 +18,7 @@ For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. ## Configure GitLab and Slack -Slack slash command [integrations](overview.md#accessing-integrations) +Slack slash command integrations are scoped to a project. 1. In GitLab, on the top bar, select **Menu > Projects** and find your project. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index daab24a8ab9..1e607d89e80 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,7 +15,8 @@ copy its URL. In GitLab: -1. Go to the [Integrations page](overview.md#accessing-integrations) in your project's settings. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index d37196ec114..2bf6b4bbe01 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -203,7 +203,7 @@ The `assignee` and `assignee_id` keys are deprecated and contain the first assignee only. The `escalation_status` and `escalation_policy` fields are -only available for issue types which support escalations, +only available for issue types which [support escalations](../../../operations/incident_management/paging.md#paging), such as incidents. Request header: @@ -538,6 +538,32 @@ Payload example: "iid": 1, "description": "Et voluptas corrupti assumenda temporibus. Architecto cum animi eveniet amet asperiores. Vitae numquam voluptate est natus sit et ad id.", "position": 0, + "labels": [ + { + "id": 25, + "title": "Afterpod", + "color": "#3e8068", + "project_id": null, + "created_at": "2019-06-05T14:32:20.211Z", + "updated_at": "2019-06-05T14:32:20.211Z", + "template": false, + "description": null, + "type": "GroupLabel", + "group_id": 4 + }, + { + "id": 86, + "title": "Element", + "color": "#231afe", + "project_id": 4, + "created_at": "2019-06-05T14:32:20.637Z", + "updated_at": "2019-06-05T14:32:20.637Z", + "template": false, + "description": null, + "type": "ProjectLabel", + "group_id": null + } + ], "source":{ "name":"Gitlab Test", "description":"Aut reprehenderit ut est.", diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index e823391401d..f4f5b3f545b 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -48,7 +48,7 @@ specific to a group, including: - [Group member events](webhook_events.md#group-member-events) - [Subgroup events](webhook_events.md#subgroup-events) -## Configure a webhook +## Configure a webhook in GitLab You can configure a webhook for a group or a project. @@ -60,6 +60,72 @@ You can configure a webhook for a group or a project. 1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](overview.md#ssl-verification). 1. Select **Add webhook**. +## Configure your webhook receiver endpoint + +Webhook receivers should be *fast* and *stable*. +Slow and unstable receivers may be disabled temporarily to ensure system reliability. +If you are writing your own endpoint (web server) to receive GitLab webhooks, keep in mind the following: + +- Your endpoint should send its HTTP response as fast as possible. + You should aim for sub-second response times in all circumstances. + If the response takes longer than the configured timeout, GitLab assumes the + hook failed, which can lead to retries and potentially cause duplicate + events. + To customize the timeout, see + [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). +- Your endpoint should ALWAYS return a valid HTTP response. If not, + GitLab assumes the hook failed and retries it. + Most HTTP libraries take care of the response for you automatically but if + you are writing a low-level hook, this is important to remember. +- GitLab usually ignores the HTTP status code returned by your endpoint, + unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). + +Best practices for a webhook receiver: + +- Prefer to return `200` or `201` status responses. + Only return error statuses (in the `4xx` range) to + indicate that the webhook has been misconfigured. For example, if your receiver + only supports push events, it is acceptable to return `400` if sent an issue + payload, since that is an indication that the hook has been set up + incorrectly. Alternatively, it is acceptable to ignore unrecognized event + payloads. Never return `500` status responses if the event has been handled. +- Your service should be idempotent. In some circumstances (including + timeouts), the same event may be sent twice. Be prepared to handle duplicate + events. You can reduce the chances of this by ensuring that your endpoint is + reliably fast and stable. +- Keep response payloads as short as possible. Empty responses are + fine. GitLab does not examine the response body, and it is only + stored so you can examine it later in the logs. +- Limit the number and size of response headers. Only send headers that would + help you diagnose problems when examining the web hook logs. +- To support fast response times, perform I/O or computationally intensive + operations asynchronously. You may indicate that the webhook is + asynchronous by returning `201`. + +### Failing webhooks + +> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. +The feature is not ready for production use. + +If a webhook fails repeatedly, it may be disabled automatically. + +Webhooks that return response codes in the `5xx` range are understood to be failing +intermittently, and are temporarily disabled. This lasts initially +for 10 minutes. If the hook continues to fail, the back-off period is +extended on each retry, up to a maximum disabled period of 24 hours. + +Webhooks that return failure codes in the `4xx` range are understood to be +misconfigured, and these are disabled until you manually re-enable +them. These webhooks are not automatically retried. + +See [troubleshooting](#troubleshoot-webhooks) for information on +how to see if a webhook is disabled, and how to re-enable it. + ## Test a webhook You can trigger a webhook manually, to ensure it's working properly. You can also send @@ -131,47 +197,7 @@ that the request is legitimate. Push events can be filtered by branch using a branch name or wildcard pattern to limit which push events are sent to your webhook endpoint. By default, all push events are sent to your webhook endpoint. You can configure branch filtering -in the [webhook settings](#configure-a-webhook) in your project. - -## HTTP responses for your endpoint - -If you are writing your own endpoint (web server) to receive -GitLab webhooks, keep in mind the following: - -- Your endpoint should send its HTTP response as fast as possible. If the response - takes longer than the configured timeout, GitLab assumes the hook failed and retries it. - To customize the timeout, see - [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). -- Your endpoint should ALWAYS return a valid HTTP response. If not, - GitLab assumes the hook failed and retries it. - Most HTTP libraries take care of the response for you automatically but if - you are writing a low-level hook, this is important to remember. -- GitLab usually ignores the HTTP status code returned by your endpoint, - unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). - -### Failing webhooks - -> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. -The feature is not ready for production use. - -If a webhook fails repeatedly, it may be disabled automatically. - -Webhooks that return response codes in the `5xx` range are understood to be failing -intermittently, and are temporarily disabled. This lasts initially -for 10 minutes. If the hook continues to fail, the back-off period is -extended on each retry, up to a maximum disabled period of 24 hours. - -Webhooks that return failure codes in the `4xx` range are understood to be -misconfigured, and these are disabled until you manually re-enable -them. These webhooks are not automatically retried. - -See [troubleshooting](#troubleshoot-webhooks) for information on -how to see if a webhook is disabled, and how to re-enable it. +in the [webhook settings](#configure-a-webhook-in-gitlab) in your project. ## How image URLs are displayed in the webhook body @@ -220,7 +246,7 @@ To view the table: - **Fails to connect** if it is temporarily disabled and will retry later.  - + 1. Select **Edit** for the webhook you want to view. The table includes the following details about each request: diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index eda0874ac08..6c70a5e679b 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,7 +14,8 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **YouTrack**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index e7bb5ad4eeb..e5dde0ed451 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -9,259 +9,265 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab 12.2. > - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab 12.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. +> - Design Management section in issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2, with a feature flag named `design_management_moved`. In earlier versions, designs were displayed in a separate tab. +> - Design Management section in issues [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) for new displays in GitLab 13.4. -Design Management allows you to upload design assets (including wireframes and mockups) -to GitLab issues and keep them stored in a single place, accessed by the Design -Management's page within an issue, giving product designers, product managers, and engineers a -way to collaborate on designs over a single source of truth. +With Design Management you can upload design assets (including wireframes and mockups) +to GitLab issues and keep them stored in a single place. Product designers, product managers, and +engineers can collaborate on designs with a single source of truth. -You can share mock-ups of designs with your team, or visual regressions can be +You can share mockups of designs with your team, or visual regressions can be viewed and addressed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see the video [Design Management (GitLab 12.2)](https://www.youtube.com/watch?v=CCMtCqdK_aM). +For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube.com/watch?v=CCMtCqdK_aM). ## Requirements -Design Management requires -[Large File Storage (LFS)](../../../topics/git/lfs/index.md) -to be enabled: +- [Git Large File Storage (LFS)](../../../topics/git/lfs/index.md) must be enabled: + - On GitLab.com, LFS is already enabled. + - On self-managed instances, a GitLab administrator must + [enable LFS globally](../../../administration/lfs/index.md). + - On both GitLab.com and self-managed instances, LFS must be + [enabled for the project itself](../settings/index.md#sharing-and-permissions). + If enabled globally, LFS is enabled by default for all projects. If you have + disabled it for your project, you must enable it again. -- For GitLab.com, LFS is already enabled. -- For self-managed instances, a GitLab administrator must have - [enabled LFS globally](../../../administration/lfs/index.md). -- For both GitLab.com and self-managed instances: LFS must be enabled for the project itself. - If enabled globally, LFS is enabled by default to all projects. To enable LFS on the - project level, navigate to your project's **Settings > General**, expand **Visibility, project features, permissions** - and enable **Git Large File Storage**. + Designs are stored as LFS objects. + Image thumbnails are stored as other uploads, and are not associated with a project but rather + with a specific design model. -Design Management also requires that projects are using -[hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). -Newly created projects use hashed storage by default. A GitLab administrator -can verify the storage type of a project by going to **Admin Area > Projects** -and then selecting the project in question. A project can be identified as -hashed-stored if its *Gitaly relative path* contains `@hashed`. +- Projects must use + [hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). -If the requirements are not met, the **Designs** tab displays a message to the user. + Newly created projects use hashed storage by default. -## Supported files + A GitLab administrator can verify the storage type of a project by going to **Admin Area > Projects** + and then selecting the project in question. A project can be identified as + hashed-stored if its **Gitaly relative path** contains `@hashed`. -Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, -`gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. +If the requirements are not met, you are notified in the **Designs** section. -Support for PDF is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/32811). +## Supported file types -## Limitations +You can upload files of the following types as designs: -- Design uploads are limited to 10 files at a time. -- From GitLab 13.1, Design filenames are limited to 255 characters. -- Design Management data - [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429) yet. -- Design Management data [isn't deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) - when an issue is deleted. -- From GitLab 12.7, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) +- BMP +- GIF +- ICO +- JPEG +- JPG +- PNG +- SVG +- TIFF +- WEBP + +Support for PDF files is tracked in [issue 32811](https://gitlab.com/gitlab-org/gitlab/-/issues/32811). + +## Known issues + +- Design Management data isn't deleted when: + - [A project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429). + - [An issue is deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427). +- In GitLab 12.7 and later, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). -- Only the latest version of the designs can be deleted. -- Deleted designs cannot be recovered but you can see them on previous designs versions. -## GitLab-Figma plugin +## View a design -> [Introduced](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/issues/2) in GitLab 13.2. +The **Designs** section is in the issue description. + +Prerequisites: + +- You must have at least the Guest role for the project. + +To view a design: + +1. Go to an issue. +1. In the **Designs** section, select the design image you want to view. + +The design you selected opens. You can then [zoom in](#zoom-in-on-a-design) on it or +[create a comment](#add-a-comment-to-a-design). -Connect your design environment with your source code management in a seamless workflow. The GitLab-Figma plugin makes it quick and easy to collaborate in GitLab by bringing the work of product designers directly from Figma to GitLab Issues as uploaded Designs. + -To use the plugin, install it from the [Figma Directory](https://www.figma.com/community/plugin/860845891704482356) -and connect to GitLab through a personal access token. The details are explained in the [plugin documentation](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/wikis/home). +When viewing a design, you can move to other designs. To do so, either: -## The Design Management section +- In the top-right corner, select **Go to previous design** (**{angle-left}**) or **Go to next design** (**{angle-right}**). +- Press <kbd>Left</kbd> or <kbd>Right</kbd> on your keyboard. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2. Designs are displayed directly in the issue description instead of a separate tab. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) for new displays in GitLab 13.4. +To return to the issue view, either: -You can find to the **Design Management** section in the issue description: +- In the top-left corner, select the close icon (**{close}**). +- Press <kbd>Esc</kbd> on your keyboard. - +When a design is added, a green icon (**{plus-square}**) is displayed on the image +thumbnail. When a design has been [changed](#add-a-new-version-of-a-design) in the current version, +a blue icon (**{file-modified-solid}**) is displayed. -## Adding designs +### Zoom in on a design + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. +> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. + +You can explore a design in more detail by zooming in and out of the image: + +- To control the amount of zoom, select plus (`+`) and minus (`-`) + at the bottom of the image. +- To reset the zoom level, select the redo icon (**{redo}**). + +To move around the image while zoomed in, drag the image. + +## Add a design to an issue > - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. > - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. > - Copy and paste uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. -To upload Design images, drag files from your computer and drop them in the Design Management section, -or select **click to upload** to select images from your file browser: +Prerequisites: - +- You must have at least the Developer role for the project. +- In GitLab 13.1 and later, the names of the uploaded files must be no longer than 255 characters. -You can drag and drop designs onto the dedicated drop zone to upload them. +To add a design to an issue: - +1. Go to an issue. +1. Either: + - Select **Upload designs** and then select images from your file browser. You can select up to + 10 files at once. + <!-- vale gitlab.SubstitutionWarning = NO --> + - Select **click to upload** and then select images from your file browser. You can select up to + 10 files at once. + <!-- vale gitlab.SubstitutionWarning = YES --> -You can also copy images from your file system and paste them directly on the -GitLab Design page as a new design. + - Drag a file from your file browser and drop it in the drop zone in the **Designs** section. -On macOS, you can take a screenshot and immediately copy it to the clipboard -by simultaneously pressing <kbd>Control</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>3</kbd>, -and then paste it as a design. +  -Copy-and-pasting has some limitations: + - Take a screenshot or copy a local image file into your clipboard, hover your cursor over the + drop zone, and press <kbd>Control</kbd> or <kbd>Cmd</kbd> + <kbd>V</kbd>. -- You can paste only one image at a time. When copy/pasting multiple files, only the first one is uploaded. -- All images are converted to `png` format under the hood, so when you want to copy/paste `gif` file, it results in broken animation. -- If you are pasting a screenshot from the clipboard, it is renamed to `design_<timestamp>.png` -- Copy/pasting designs is not supported on Internet Explorer. + When pasting images like this, keep the following in mind: -Designs with the same filename as an existing uploaded design create a new version -of the design, and replaces the previous version. Dropping a design on an -existing uploaded design creates a new version if the filenames are the same. - -### Skipped designs + - You can paste only one image at a time. When you paste multiple copied files, only the first + one is uploaded. + - If you are pasting a screenshot, the image is added as a PNG file with a generated name of: + `design_<timestamp>.png`. + - It's not supported in Internet Explorer. -Designs with the same filename as an existing uploaded design _and_ whose content has not changed are skipped. -This means that no new version of the design is created. When designs are skipped, you are made aware by a warning -message on the Issue. +## Add a new version of a design -## Viewing designs +As discussion on a design continues, you might want to upload a new version of a design. -Images on the Design Management page can be enlarged by selecting them. -You can navigate through designs by selecting the navigation buttons on the -top-right corner or with <kbd>Left</kbd>/<kbd>Right</kbd> keyboard buttons. +Prerequisites: -The number of discussions on a design — if any — is listed to the right -of the design filename. Selecting this number enlarges the design, -similar to clicking or tapping anywhere else in the design. -When a design is added or modified, an icon is displayed on the item -to help summarize changes between versions. +- You must have at least the Developer role for the project. -| Indicator | Example | -| --------- | ------- | -| Discussions |  | -| Modified (in the selected version) |  | -| Added (in the selected version) |  | +To do so, [add a design](#add-a-design-to-an-issue) with the same filename. -### Exploring designs by zooming +To browse all the design versions, use the dropdown list at the top of the **Designs** section. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. -> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. - -Designs can be explored in greater detail by zooming in and out of the image. -Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. -While zoomed, you can still [start new discussions](#starting-discussions-on-designs) on the image, and see any existing ones. -While zoomed in, you can drag the image to move around it. +### Skipped designs - +When you upload an image with the same filename as an existing uploaded design _and_ that is the +same, it's skipped. This means that no new version of the design is created. +When designs are skipped, a warning message is displayed. -## Deleting designs +## Archive a design > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/220964) the button from "Delete" to "Archive" in GitLab 13.3. -There are two ways to delete designs: manually delete them -individually, or select a few of them to delete at once, -as shown below. +You can archive individual designs or select a few of them to archive at once. -To delete a single design, select it to view it enlarged, -then select the trash icon on the top right corner and confirm -the deletion by selecting **Delete** in the window: +Prerequisites: - +- You must have at least the Developer role for the project. -To delete multiple designs at once, on the design's list view, -first select the designs you want to delete: +To archive a single design: - +1. Select the design to view it enlarged. +1. In the top right corner, select **Archive design** (**{archive}**). +1. Select **Archive designs**. -Select **Delete selected** to confirm the deletion: +To archive multiple designs at once: - +1. Select the checkboxes on the designs you want to archive. +1. Select **Archive selected**. NOTE: -Only the latest version of the designs can be deleted. -Deleted designs are not permanently lost; they can be -viewed by browsing previous versions. +Only the latest version of the designs can be archived. +Archived designs are not permanently lost. You can browse +[previous versions](#add-a-new-version-of-a-design). -## Reordering designs +## Reorder designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. You can change the order of designs by dragging them to a new position. -## Starting discussions on designs - -> - Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) adjusting a pin's position in GitLab 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. +## Add a comment to a design -When a design is uploaded, you can start a discussion by selecting -the image on the exact location you would like the discussion to be focused on. -A pin is added to the image, identifying the discussion's location. +> Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.8. - +You can start [discussions](../../discussions/index.md) on uploaded designs. To do so: -You can adjust a pin's position by dragging it around the image. This is useful -for when your design layout has changed between revisions, or if you need to move an -existing pin to add a new one in its place. +<!-- vale gitlab.SubstitutionWarning = NO --> +1. Go to an issue. +1. Select the design. +1. Click or tap the image. A pin is created in that spot, identifying the discussion's location. +1. Enter your message. +1. Select **Comment**. +<!-- vale gitlab.SubstitutionWarning = YES --> -Different discussions have different pin numbers: +You can adjust a pin's position by dragging it around the image. You can use this when your design's +layout has changed, or when you want to move a pin to add a new one in its place. - +New discussion threads get different pin numbers, which you can use to refer to them. In GitLab 12.5 and later, new discussions are output to the issue activity, so that everyone involved can participate in the discussion. -## Resolve Design threads +## Resolve a discussion thread on a design > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. -Discussion threads can be resolved on Designs. - -There are two ways to resolve/unresolve a Design thread: - -1. You can mark a thread as resolved or unresolved by selecting the checkmark icon for **Resolve thread** in the top-right corner of the first comment of the discussion: +When you're done discussing part of a design, you can resolve the discussion thread. -  +To mark a thread as resolved or unresolved, either: -1. Design threads can also be resolved or unresolved in their threads by using a checkbox. - When replying to a comment, you can select or clear a checkbox to resolve or unresolve - the thread after publishing: +- In the top-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). +- Add a new comment to the thread and select or clear the **Resolve thread** checkbox. -  +Resolving a discussion thread also marks any pending [to-do items](../../todos.md) related to notes +inside the thread as done. Only to-do items for the user triggering the action are affected. -Resolving a discussion thread also marks any pending to-do items related to notes -inside the thread as done. This is applicable only for to-do items owned by the user triggering the action. +Your resolved comment pins disappear from the design to free up space for new discussions. +To revisit a resolved discussion, expand **Resolved Comments** below the visible threads. -Your resolved comment pins disappear from the Design to free up space for new discussions. -However, if you need to revisit or find a resolved discussion, all of your resolved threads are -available in the **Resolved Comment** area at the bottom of the right sidebar. - -## Add to-do items for designs +## Add a to-do item for a design > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. -Add a to-do item for a design by selecting **Add a to do** on the design sidebar: - - +To add a [to-do item](../../todos.md) for a design, select **Add a to do** on the design sidebar. -## Referring to designs in Markdown +## Refer to a design in Markdown > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in GitLab 13.1. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in GitLab 13.5. -We support referring to designs in [Markdown](../../markdown.md), which is available -throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. +To refer to a design in a [Markdown](../../markdown.md) text box in GitLab, for example, in +a comment or description, paste its URL. It's then displayed as a short reference. -Full URL references are supported. For example, if we refer to a design -somewhere with: +For example, if you refer to a design somewhere with: ```markdown -See https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png +See https://gitlab.com/gitlab-org/gitlab/-/issues/13195/designs/Group_view.png. ``` -This is rendered as: +It's rendered as: -> See [#123[homescreen.png]](https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png) +> See [#13195[Group_view.png]](https://gitlab.com/gitlab-org/gitlab/-/issues/13195/designs/Group_view.png). ## Design activity records @@ -272,3 +278,15 @@ User activity events on designs (creation, deletion, and updates) are tracked by 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#view-project-activity) activity pages. + +## GitLab-Figma plugin + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/issues/2) in GitLab 13.2. + +You can use the GitLab-Figma plugin to upload your designs from Figma directly to your issues +in GitLab. + +To use the plugin in Figma, install it from the [Figma Directory](https://www.figma.com/community/plugin/860845891704482356) +and connect to GitLab through a personal access token. + +For more information, see the [plugin documentation](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/wikis/home). diff --git a/doc/user/project/issues/img/adding_note_to_design_1.png b/doc/user/project/issues/img/adding_note_to_design_1.png Binary files differdeleted file mode 100644 index 3c25fcb1241..00000000000 --- a/doc/user/project/issues/img/adding_note_to_design_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/adding_note_to_design_2.png b/doc/user/project/issues/img/adding_note_to_design_2.png Binary files differdeleted file mode 100644 index c418a0364c0..00000000000 --- a/doc/user/project/issues/img/adding_note_to_design_2.png +++ /dev/null diff --git a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png b/doc/user/project/issues/img/confirm_design_deletion_v12_4.png Binary files differdeleted file mode 100644 index 5631b6ec98e..00000000000 --- a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png b/doc/user/project/issues/img/delete_multiple_designs_v12_4.png Binary files differdeleted file mode 100644 index 40d449d5b39..00000000000 --- a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_added_v12_3.png b/doc/user/project/issues/img/design_added_v12_3.png Binary files differdeleted file mode 100644 index 92aa953db8e..00000000000 --- a/doc/user/project/issues/img/design_added_v12_3.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_comments_v12_3.png b/doc/user/project/issues/img/design_comments_v12_3.png Binary files differdeleted file mode 100644 index c01a8bb7ba7..00000000000 --- a/doc/user/project/issues/img/design_comments_v12_3.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png Binary files differindex 4ab5e184905..0225505e829 100644 --- a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png +++ b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png diff --git a/doc/user/project/issues/img/design_management_upload_v13.3.png b/doc/user/project/issues/img/design_management_upload_v13.3.png Binary files differdeleted file mode 100644 index f7b3f79fb22..00000000000 --- a/doc/user/project/issues/img/design_management_upload_v13.3.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_management_v13_2.png b/doc/user/project/issues/img/design_management_v13_2.png Binary files differdeleted file mode 100644 index 3da11c92514..00000000000 --- a/doc/user/project/issues/img/design_management_v13_2.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_management_v14_10.png b/doc/user/project/issues/img/design_management_v14_10.png Binary files differnew file mode 100644 index 00000000000..a10be15eafd --- /dev/null +++ b/doc/user/project/issues/img/design_management_v14_10.png diff --git a/doc/user/project/issues/img/design_modified_v12_3.png b/doc/user/project/issues/img/design_modified_v12_3.png Binary files differdeleted file mode 100644 index 01b752fa531..00000000000 --- a/doc/user/project/issues/img/design_modified_v12_3.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_todo_button_v13_5.png b/doc/user/project/issues/img/design_todo_button_v13_5.png Binary files differdeleted file mode 100644 index 970161a6097..00000000000 --- a/doc/user/project/issues/img/design_todo_button_v13_5.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_zooming_v12_7.png b/doc/user/project/issues/img/design_zooming_v12_7.png Binary files differdeleted file mode 100644 index 4966af06e41..00000000000 --- a/doc/user/project/issues/img/design_zooming_v12_7.png +++ /dev/null diff --git a/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png b/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png Binary files differdeleted file mode 100644 index 8791419b919..00000000000 --- a/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png b/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png Binary files differdeleted file mode 100644 index fc1fff321ba..00000000000 --- a/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/select_designs_v12_4.png b/doc/user/project/issues/img/select_designs_v12_4.png Binary files differdeleted file mode 100644 index fe1c55a4ae2..00000000000 --- a/doc/user/project/issues/img/select_designs_v12_4.png +++ /dev/null diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md deleted file mode 100644 index e9f3f4be1c3..00000000000 --- a/doc/user/project/issues/issue_data_and_actions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2022-02-24' ---- - -This file was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2022-02-24>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 58591129d97..4508ef30ac5 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -342,7 +342,7 @@ To do it: issues.each do |issue| if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project, admin_user).execute(issue, target_project) + Issues::MoveService.new(project: project, current_user: admin_user).execute(issue, target_project) else puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" end diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 9311ef590df..95a7e9387e8 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -6,20 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Sorting and ordering issue lists **(FREE)** -You can sort a list of issues several ways, including by: - -- [Blocking issues](#sorting-by-blocking-issues) -- [Created date](#sorting-by-created-date) -- [Due date](#sorting-by-due-date) -- [Label priority](#sorting-by-label-priority) -- [Last updated](#sorting-by-last-updated) -- [Manual sorting](#manual-sorting) -- [Milestone due date](#sorting-by-milestone-due-date) -- [Popularity](#sorting-by-popularity) -- [Priority](#sorting-by-priority) -- [Title](#sorting-by-title) -- [Weight](#sorting-by-weight) - +You can sort a list of issues several ways. The available sorting options can change based on the context of the list. ## Sorting by blocking issues **(PREMIUM)** @@ -51,10 +38,10 @@ For more information, see [issue 14523](https://gitlab.com/gitlab-org/gitlab/-/i To learn how to change label priority, see [Label priority](../labels.md#set-label-priority). -## Sorting by last updated +## Sorting by updated date -When you sort by **Last updated**, the issue list changes to sort by the time of a last -update. Issues changed the most recently are first. +When you sort by **Updated date**, the issue list changes to sort by the time of a last +update. Issues changed the most recently are shown first. ## Manual sorting diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 18197cd860f..2cc23b14857 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -253,6 +253,35 @@ with the old labels are assigned to the new group label. The new group label has the same ID as the previous project label. +## Promote a subgroup label to the parent group + +It's not possible to directly promote a group label to the parent group. +To achieve this, use the following workaround. + +Prerequisites: + +- There must be a group that contains subgroups ("parent group"). +- There must be a subgroup in the parent group, that has a label you want to promote. +- You must have at least the Reporter role for both groups. + +To "promote" the label to the parent group: + +1. In the parent group, [create a label](#create-a-group-label) with the same name as the original + one. We recommend making it a different color so you don't mistake the two while you're doing this. +1. In the subgroup, [view its labels](#view-group-labels). You should see the two labels and where + they come from: + +  + +1. Next to the subgroup label (the old one), select **Issues**, **Merge requests**, or **Epics**. +1. Add the new label to issues, merge requests, and epics that have the old label. + To do it faster, use [bulk editing](issues/managing_issues.md#bulk-edit-issues-from-a-group). +1. In the subgroup or the parent group, [delete the label](#delete-a-group-label) that belongs to + the lower-level group. + +You should now have a label in the parent group that is named the same as the old one, and added +to the same issues, MRs, and epics. + ## Generate default project labels If a project or its parent group has no labels, you can generate a default set of project @@ -420,6 +449,22 @@ The labels higher in the list get higher priority. To learn what happens when you sort by priority or label priority, see [Sorting and ordering issue lists](issues/sorting_issue_lists.md). +## Real-time changes to labels + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241538) in GitLab 14.10 with a [feature flag](../../administration/feature_flags.md) named `realtime_labels`, disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an +administrator to [enable the feature flag](../../administration/feature_flags.md) named `realtime_labels`. +On GitLab.com, this feature is unavailable. + +Changed labels are immediately visible to other users, without refreshing the page, on the following: + +- Epics +- Incidents +- Issues +- Merge requests + ## Troubleshooting ### Some label titles end with `_duplicate<number>` diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c3d5dca0675..ff4677eddde 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication and Authorization +group: Workspace info: 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 --- @@ -49,7 +49,7 @@ flowchart RL [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. Add users to a project so they become members and have permission -to perform actions. +to perform actions. The Owner [role](../../permissions.md#project-members-permissions) can only be added at the group level. Prerequisite: @@ -145,7 +145,10 @@ In this example: - **Administrator** is the [Owner](../../permissions.md) and member of all groups. They have inherited their role from the **demo** group. -If a user is a direct member of a project, the expiration date can be updated. If membership is inherited from a parent group, the expiration date can be updated only from the parent group itself. +If a user is a: + +- Direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. +- Inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. ## Remove a member from a project diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 0a7fbc9ee95..0ede9310393 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -146,7 +146,7 @@ You can also enforce merge request approval settings: - At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all projects. -- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups +- On a [top-level group](../../../group/index.md#group-approval-settings), which apply to all subgroups and projects. If the settings are inherited by a group or project, they cannot be changed in the group or project diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index dc13b270f17..77162aa0b83 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -13,8 +13,6 @@ merge commits. In such cases, the fast-forward merge is the perfect candidate. With fast-forward merge requests, you can retain a linear Git history and a way to accept merge requests without creating merge commits. -## Overview - When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting is enabled, no merge commits are created and all merges are fast-forwarded, @@ -22,6 +20,11 @@ which means that merging is only allowed if the branch can be fast-forwarded. When a fast-forward merge is not possible, the user is given the option to rebase. +NOTE: +Projects using the fast-forward merge strategy can't filter merge requests +[by deployment date](../../search/index.md#filtering-merge-requests-by-environment-or-deployment-date), +because no merge commit is created. + ## Enabling fast-forward merges 1. On the top bar, select **Menu > Projects** and find your project. diff --git a/doc/user/project/merge_requests/img/attention_request_list_v14_10.png b/doc/user/project/merge_requests/img/attention_request_list_v14_10.png Binary files differnew file mode 100644 index 00000000000..00427a0aa40 --- /dev/null +++ b/doc/user/project/merge_requests/img/attention_request_list_v14_10.png diff --git a/doc/user/project/merge_requests/img/attention_request_sidebar_v14_10.png b/doc/user/project/merge_requests/img/attention_request_sidebar_v14_10.png Binary files differnew file mode 100644 index 00000000000..174cf01dbb0 --- /dev/null +++ b/doc/user/project/merge_requests/img/attention_request_sidebar_v14_10.png diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png Binary files differindex f4330549a57..17ce42e7a69 100644 --- a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png +++ b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 9872bd2e936..a3b9fb52f0d 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -70,6 +70,53 @@ change and whether you need access to a development environment: - [Push changes from the command line](../../../gitlab-basics/start-using-git.md), if you are familiar with Git and the command line. +## Request attention to a merge request + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343528) in GitLab 14.10 [with a flag](../../../administration/feature_flags.md) named `mr_attention_requests`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `mr_attention_requests`. +On GitLab.com, this feature is dependent on the enablement status of the feature flag. Refer to the [enablement issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343528) for details. + +To tell a merge request's assignee or reviewer that their attention is +needed on a merge request, you can request their attention. If an assignee or a +reviewer has their attention requested on a merge request, the **Attention request** +icon (**{attention}**) is displayed as a solid icon (**{attention-solid}**) on +the merge request list page: + + + +To view a list of merge requests that need your attention: + +1. On the top bar, select **Merge requests** (**{merge-request}**). +1. Select **Attention requests**. + +To request attention from another user, use the `/attention @user` +[quick action](../quick_actions.md) or: + +1. Go to the merge request. +1. On the right sidebar, identify the user you want to request attention from. +1. Next to the user's name, select **Request attention** (**{attention}**), and the appearance + of the icon changes: + +  + +### Remove an attention request + +If your attention was requested as an assignee or reviewer, it's removed when you: + +- Manually remove the attention request by selecting **Remove attention request** (**{attention-solid}**). +- Approve the merge request. +- Add a new user as an assignee or reviewer. +- Request the attention of a different assignee or reviewer. +- Remove yourself (or are removed by someone else) as an assignee or reviewer. +- Merge or close the merge request. + +If you are both the assignee and a reviewer on a merge request, you receive +only one attention request, which is synced across both duties. If the +attention request is removed from you, either as an assignee or a reviewer, +it is removed from both your duties. + ## Close a merge request If you decide to permanently stop work on a merge request, diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 280ae07b401..512faae82a9 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -112,7 +112,13 @@ This example shows reviewers and approval rules in a merge request sidebar: ### Request a new review -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/357271) in GitLab 14.10. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/357271) +in GitLab 14.10, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/357271) in GitLab 15.0. +Use [attention requests](../index.md#request-attention-to-a-merge-request) instead. After a reviewer completes their [merge request reviews](../../../discussions/index.md), the author of the merge request can request a new review from the reviewer: diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 9868f2619ba..8e6794bcfa7 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -108,6 +108,8 @@ For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to `Addresses %{username}'s review`. +For merge requests created from forks, GitLab uses the template defined in target project. + NOTE: Custom commit messages for each applied suggestion is introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index a952c0550bc..76a67487881 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -54,6 +54,9 @@ External status checks have the following states: Support for adding a `failed` state is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338827). +If something changes outside of GitLab, you can [set the status of an external status check](../../../api/status_checks.md#set-status-of-an-external-status-check) +using the API. You don't need to wait for a merge request webhook payload to be sent first. + ## View the status checks on a project Within each project's settings, you can see a list of status checks added to the project: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index d7177208a6e..9f1e5ae7046 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -28,7 +28,7 @@ between pipeline completion and the visualization loading on the page. 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/yaml/artifacts_reports.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/artifacts_reports.md#artifactsreportscobertura-deprecated). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -156,7 +156,9 @@ test: - npx nyc --reporter cobertura mocha artifacts: reports: - cobertura: coverage/cobertura-coverage.xml + coverage_report: + coverage_format: cobertura + path: coverage/cobertura-coverage.xml ``` ### Java and Kotlin examples @@ -324,18 +326,13 @@ run tests: The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Go uses: - [`go test`](https://go.dev/doc/tutorial/add-a-test) to run tests. -- [`gocover-cobertura`](https://github.com/t-yuki/gocover-cobertura) to convert Go's coverage profile into the Cobertura XML format. +- [`gocover-cobertura`](https://github.com/boumenot/gocover-cobertura) to convert Go's coverage profile into the Cobertura XML format. -This example assumes that [Go modules](https://go.dev/ref/mod) are being used. -Using Go modules causes paths within the coverage profile to be prefixed with your -project's module identifier, which can be found in the `go.mod` file. This -prefix must be removed for GitLab to parse the Cobertura XML file correctly. You can use the following `sed` command to remove the prefix: - -```shell -sed -i 's;filename=\"<YOUR_MODULE_ID>/;filename=\";g' coverage.xml -``` - -Replace the `gitlab.com/my-group/my-project` placeholder in the following example with your own module identifier to make it work. +This example assumes that [Go modules](https://go.dev/ref/mod) +are being used. Please note that the `-covermode count` option does not work with the `-race` flag. +If you want to generate code coverage while also using the `-race` flag, you must switch to +`-covermode atomic` which is slower than `-covermode count`. See [this blog post](https://go.dev/blog/cover) +for more details. ```yaml run tests: @@ -343,9 +340,9 @@ run tests: image: golang:1.17 script: - go install - - go test . -coverprofile=coverage.txt -covermode count - - go run github.com/t-yuki/gocover-cobertura < coverage.txt > coverage.xml - - sed -i 's;filename=\"gitlab.com/my-group/my-project/;filename=\";g' coverage.xml + - go test ./... -coverprofile=coverage.txt -covermode count + - go get github.com/boumenot/gocover-cobertura + - go run github.com/boumenot/gocover-cobertura < coverage.txt > coverage.xml artifacts: reports: cobertura: coverage.xml diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 3491346f7d9..5433e02b210 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -1,7 +1,7 @@ --- type: concepts -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 4d8919090a2..d970c0f9ef4 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,7 +1,7 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index f09aea3b02a..cb22a200514 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -1,14 +1,14 @@ --- type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages integration with Let's Encrypt **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. The GitLab Pages integration with Let's Encrypt (LE) allows you to use LE certificates for your Pages website with custom domains 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 21f2dd51f70..0c848a24dec 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -1,7 +1,7 @@ --- type: concepts -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 25382778b1d..510f9332e7b 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -1,7 +1,7 @@ --- type: reference, howto -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index b43af2f0efe..71ed3134c1e 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -1,7 +1,7 @@ --- type: reference, howto -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index e0c10e27ec3..f08afc924f3 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- 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 cee10675a62..b32d71a4887 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 5773dd1f2c0..54b843945cd 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 82b1a824f7a..af49522efe2 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,7 +1,7 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index e4bc58854ef..f274338c2fd 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md deleted file mode 100644 index 7779f87b459..00000000000 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'custom_domains_ssl_tls_certification/lets_encrypt_integration.md' -remove_date: '2022-03-14' ---- - -This file was moved to [another location](custom_domains_ssl_tls_certification/lets_encrypt_integration.md). - -<!-- This redirect file can be deleted after <2022-03-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 002b234f561..9b747e04973 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index cdae1d2f837..1db404f4888 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 292530e6c9c..06396b5cd62 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -147,8 +147,8 @@ Deploy keys are not available in the **Allowed to merge** dropdown list. ## Allow force push on a protected branch -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 [with a flag](../../administration/feature_flags.md) named `allow_force_push_to_protected_branches`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. Feature flag `allow_force_push_to_protected_branches` removed. You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to protected branches. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 20dd37578fd..d04f79d11c7 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -35,7 +35,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | -| `ci.skip` | Do not create a CI pipeline for the latest push. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | +| `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | | `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index ae42d90af06..b73b381ffcd 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -55,6 +55,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | | `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | | `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | +| `/attention @user1` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | [Request attention](merge_requests/index.md#request-attention-to-a-merge-request) to a merge request from a user. | | `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | | `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | | `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index ddeef65a6b5..0e6c98457c7 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -32,7 +32,7 @@ To fork an existing project in GitLab: It must be unique in the namespace. 1. Optional. Add a **Project description**. 1. Select the **Visibility level** for your fork. For more information about - visibility levels, read [Project and group visibility](../../../public_access/public_access.md). + visibility levels, read [Project and group visibility](../../public_access.md). 1. Select **Fork project**. GitLab creates your fork, and redirects you to the new fork's page. diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index cd0c6679d8d..39b57f89ceb 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,8 +25,14 @@ GitLab. ## Cleaner diffs -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Alpha](../../../../policy/alpha-beta-support.md#alpha-features) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. +> - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. +On GitLab.com, this feature is available. +This feature is ready for production use. When commits include changes to Jupyter Notebook files, GitLab: @@ -37,6 +43,10 @@ Code suggestions are not available on diffs and merge requests for `.ipynb` file  +This feature is an [Alpha](../../../../policy/alpha-beta-support.md#alpha-features) release, +and might lead to performance degradation. On self-managed GitLab, if unexpected issues +arise, disable the feature. + ## Jupyter Git integration Jupyter can be configured as an OAuth application with repository access, acting diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index c9fa30e39a8..e1017e78437 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -7,9 +7,13 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** -You can _mirror_ a repository to and from external sources. You can select which -repository serves as the source, and modify which parts of the repository are copied. -Branches, tags, and commits can be mirrored. +You can _mirror_ a repository to and from external sources. You can select which repository +serves as the source. Branches, tags, and commits can be mirrored. + +NOTE: +SCP-style URLs are **not** supported. However, the work for implementing SCP-style URLs is tracked +in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/18993). +Subscribe to the issue to follow its progress. Several mirroring methods exist: @@ -23,11 +27,7 @@ Mirror a repository when: copy of your project at its previous home, configure your GitLab repository as a [push mirror](push.md). Changes you make to your GitLab repository are copied to the old location. -- Your GitLab project is private, but some components can be shared publicly. - Configure your primary repository as a [push mirror](push.md) and push the portions - you want to make public. With this configuration, you can open-source specific - projects, contribute back to the open-source community, and protect the sensitive - parts of your project. +- Your GitLab instance is private, but you want to open-source some projects. - You migrated to GitLab, but the canonical version of your project is somewhere else. Configure your GitLab repository as a [pull mirror](pull.md) of the other project. Your GitLab repository pulls copies of the commits, tags, and branches of project. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md deleted file mode 100644 index 8fbe5aec6a3..00000000000 --- a/doc/user/project/repository/repository_mirroring.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'mirror/index.md' -remove_date: '2022-03-22' ---- - -This document was moved to [another location](mirror/index.md). - -<!-- This redirect file can be deleted after <2022-03-22>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 4165c1828cc..6eed1717507 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -117,12 +117,19 @@ There are multiple ways to create a branch from the GitLab web interface. ### Create a new branch from an issue +> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. + If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. Once merged, the merge request closes the issue. You can see a **Create merge request** dropdown below the issue description. +NOTE: +In GitLab 14.8 and later, selecting **Create merge request** +[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) +instead of immediately creating the merge request. + The **Create merge request** button doesn't display if: - A branch with the same name already exists. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index c9cddad1a91..0259ff6ce30 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -88,7 +88,7 @@ If you have the correct version, you can proceed to configure Git. Configure Git to use your key for signing: ```shell -signingkey = $( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' ) +signingkey=$( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' ) git config --global user.signingkey $signingkey git config --global gpg.format x509 ``` diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 6abe9c08d28..8b80c494e2f 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -127,7 +127,7 @@ To search for a requirement: You can also sort the requirements list by: - Created date -- Last updated +- Updated date ## Allow requirements to be satisfied from a CI job diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 90732ba4fe2..19c3218137f 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -241,7 +241,8 @@ The configuration options are the same as for configuring ##### Microsoft Graph -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. +> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). @@ -263,6 +264,22 @@ Graph API instead of IMAP. Follow the [documentation in the incoming email secti } ``` +For Microsoft Cloud for US Government or [other Azure deployments](https://docs.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. + +- Example for Microsoft Cloud for US Government: + +```ruby + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } +} +``` + 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. #### Configuring a custom email address suffix @@ -330,20 +347,6 @@ Note that: - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. -#### Issues created on someone's behalf - -To allow third party applications and ticketing systems to interface with Service Desk, -when the email contains the `Reply-To` email header, this email address is used as the address of the -issue author. - -Because the `Reply-To` header can be set to arbitrary values, do not blindly trust that an issue -created on behalf of `someone@example.com` was indeed created by the real owner of such email address. - -For example, an email with headers `To: support@example.com` and `Reply-To:someone@example.com` -creates an issue with the following note: - -> Created (…) by `support@example.com` (reply to: `someone@example.com`) (…) - #### Privacy considerations Service Desk issues are confidential, but the project owner can diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index ae3decb8079..30261ed5082 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -72,13 +72,14 @@ The following items are exported: The following items are **not** exported: +- [Child pipeline history](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) - Build traces and artifacts - Container registry images - CI/CD variables - Pipeline triggers - Webhooks - Any encrypted tokens -- Merge Request Approvers +- Merge Request Approvers and [the number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) - Repository size limits - Deploy keys allowed to push to protected branches @@ -127,7 +128,7 @@ The following items are imported but changed slightly: associated with such merge requests are created in a project during the import/export. Thus, the number of branches in the exported project might be bigger than in the original project. - If use of the `Internal` visibility level - [is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), + [is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), all imported projects are given `Private` visibility. Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches. @@ -154,9 +155,9 @@ The default is `0` (unlimited). Imported users can be mapped by their public email addresses on self-managed instances, if an administrator (not an owner) does the import. -- Public email addresses are not set by default. Users must -[set it in their profiles](../../profile/index.md#set-your-public-email) -for mapping to work correctly. +- The project must be exported by a project or group member with the Owner role. +- Public email addresses are not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) + for mapping to work correctly. - For contributions to be mapped correctly, users must be an existing member of the namespace, or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues that are owned by the importer. - Imported users are set as [direct members](../members/index.md) @@ -237,7 +238,7 @@ and the exports between them are compatible. ### Project fails to import due to mismatch -If the [shared runners enablement](../../../ci/runners/runners_scope.md#enable-shared-runners) +If the [shared runners enablement](../../../ci/runners/runners_scope.md#enable-shared-runners-for-a-project) does not match between the exported project, and the project import, the project fails to import. Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and either: @@ -306,7 +307,7 @@ reduce the repository size for another import attempt: #### Workaround option 2 NOTE: -This workaround requires access to the rails console, which isn't available to end-users on GitLab.com. +This workaround does not account for LFS objects. Rather than attempting to push all changes at once, this workaround: @@ -383,3 +384,17 @@ s = Gitlab::ImportExport::Saver.new(exportable: p, shared:p.import_export_shared s.send(:compress_and_save) s.send(:save_upload) ``` + +### Import using the REST API fails when using a group access token + +[Group access tokens](../../group/settings/group_access_tokens.md) +don't work for project or group import operations. When a group access token initiates an import, +the import fails with this message: + +```plaintext +Error adding importer user to Project members. +Validation failed: User project bots cannot be added to other groups / projects +``` + +To use [Import REST APIs](../../../api/project_import_export.md), +pass regular user account credentials such as [personal access tokens](../../profile/personal_access_tokens.md). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 342b8d80bcf..31cda756a78 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -89,15 +89,11 @@ read-only view to discourage this behavior. Compliance framework pipelines allow group owners to define a compliance pipeline in a separate repository that gets executed in place of the local project's `gitlab-ci.yml` file. As part of this pipeline, an -`include` statement can reference the local project's `gitlab-ci.yml` file. This way, the two CI -files are merged together any time the pipeline runs. Jobs and variables defined in the compliance +`include` statement can reference the local project's `gitlab-ci.yml` file. This way, the compliance +pipeline jobs can run alongside the project-specific jobs any time the pipeline runs. +Jobs and variables defined in the compliance pipeline can't be changed by variables in the local project's `gitlab-ci.yml` file. -When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), -as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). -For details on the similarities and differences between these features, see -[Enforce scan execution](../../application_security/#enforce-scan-execution). - When you set up the compliance framework, use the **Compliance pipeline configuration** box to link the compliance framework to specific CI/CD configuration. Use the `path/file.y[a]ml@group-name/project-name` format. For example: @@ -185,6 +181,11 @@ include: # Execute individual project's configuration (if project contains .git ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch ``` +When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), +as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). +For details on the similarities and differences between these features, see +[Enforce scan execution](../../application_security/#enforce-scan-execution). + ##### Ensure compliance jobs are always run Compliance pipelines use GitLab CI/CD to give you an incredible amount of flexibility @@ -242,7 +243,7 @@ documentation, access permissions, and more. To do so from your project, go to **Settings** > **General**, and expand the **Visibility, project features, permissions** section. -You can now change the [Project visibility](../../../public_access/public_access.md). +You can now change the [Project visibility](../../public_access.md). If you set **Project Visibility** to public, you can limit access to some features to **Only Project Members**. In addition, you can select the option to [Allow users to request access](../members/index.md#request-access-to-a-project). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index a78226ac2f8..b66913b7223 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -12,17 +12,18 @@ type: reference, howto > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. -You can use a project access token to authenticate: +Project access tokens are similar to passwords, except you can [limit access to resources](#scopes-for-a-project-access-token), +select a limited role, and provide an expiry date. -- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). -- With Git, when using HTTP Basic Authentication. +Use a project access token to authenticate: -After you configure a project access token, you don't need a password when you authenticate. -Instead, you can enter any non-blank value. +- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- With Git, when using HTTP Basic Authentication, use: + - Any non-blank value as a username. + - The project access token as the password. Project access tokens are similar to [group access tokens](../../group/settings/group_access_tokens.md) -and [personal access tokens](../../profile/personal_access_tokens.md), except they are -associated with a project rather than a group or user. +and [personal access tokens](../../profile/personal_access_tokens.md). In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) as personal access tokens if the limit is set. @@ -35,6 +36,8 @@ You can use project access tokens: - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. +You cannot use project access tokens to create other access tokens. + Project access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 7c74a625b92..220623d0372 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -17,7 +17,7 @@ description: "The static site editor enables users to edit content on static web WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77246) -for use in GitLab 14.7, and is planned for +in GitLab 14.7, and is planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7351) in GitLab 14.10. Users should instead use the [Web Editor](../repository/web_editor.md) or [Web IDE](../web_ide/index.md). [Removal instructions](#remove-the-static-site-editor) for existing projects are included on this page. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index ff8a076465d..8f9486633d5 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -222,7 +222,7 @@ To edit Markdown files in the Web IDE: 1. Go to your repository, and navigate to the Markdown page you want to edit. 1. Select **Open in Web IDE**, and GitLab loads the page in a tab in the editor. -1. Make your changes to the file. GitLab supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). +1. Make your changes to the file. GitLab supports [GitLab Flavored Markdown (GLFM)](../../markdown.md). 1. When your changes are complete, select **Commit** in the left sidebar. 1. Add a commit message, select the branch you want to commit to, and select **Commit**. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 33f6c32d334..7d155ea9b06 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -327,13 +327,7 @@ to disable the wiki but toggle it on (in blue). > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345398) switching between editing experiences in GitLab 14.7 [with a flag](../../../administration/feature_flags.md) named `wiki_switch_between_content_editor_raw_markdown`. Enabled by default. - -FLAG: -On self-managed GitLab, by default this feature is available. -To hide the feature, ask an administrator to -[disable the feature flag](../../../administration/feature_flags.md) named -`wiki_switch_between_content_editor_raw_markdown`. -On GitLab.com, this feature is available. +> - Switching between editing experiences generally available in GitLab 14.10. [Feature flag `wiki_switch_between_content_editor_raw_markdown`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83760) removed. GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 19e77d18aca..03530b59e9b 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -76,13 +76,13 @@ To create a project in GitLab: - [custom template](#create-a-project-from-a-custom-template). - [HIPAA audit protocol template](#create-a-project-from-the-hipaa-audit-protocol-template). - [Import a project](../../user/project/import/index.md) - from a different repository. Contact your GitLab administrator if this option is not available. + from a different repository. Contact your GitLab administrator if this option is not available. - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). -- For a list of words that you cannot use as project names, see -[reserved project and group names](../../user/reserved_names.md). -- For a list of characters that you cannot use in project and group names, see -[limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). +- For a list of words that you cannot use as project names, see + [reserved project and group names](../../user/reserved_names.md). +- For a list of characters that you cannot use in project and group names, see + [limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). ## Create a blank project @@ -99,12 +99,12 @@ To create a blank project: - In the **Project description (optional)** field, enter the description of your project's dashboard. - In the **Project target (optional)** field, select your project's deployment target. This information helps GitLab better understand its users and their deployment requirements. - - To modify the project's [viewing and access rights](../../public_access/public_access.md) for - users, change the **Visibility Level**. + - To modify the project's [viewing and access rights](../public_access.md) for + users, change the **Visibility Level**. - To create README file so that the Git repository is initialized, has a default branch, and can be cloned, select **Initialize repository with a README**. - To analyze the source code in the project for known security vulnerabilities, - select **Enable Static Application Security Testing (SAST)**. + select **Enable Static Application Security Testing (SAST)**. 1. Select **Create project**. ## Create a project from a built-in template @@ -132,13 +132,13 @@ To create a project from a built-in template: slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - In the **Project description (optional)** field, enter the description of your project's dashboard. - - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, - change the **Visibility Level**. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. 1. Select **Create project**. ## Create a project from a custom template **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. Custom project templates are available at: @@ -158,8 +158,8 @@ Custom project templates are available at: slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - The description of your project's dashboard in the **Project description (optional)** field. - - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, - change the **Visibility Level**. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. 1. Select **Create project**. ## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** @@ -184,8 +184,8 @@ To create a project from the HIPAA Audit Protocol template: slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - In the **Project description (optional)** field, enter the description of your project's dashboard. - - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, - change the **Visibility Level**. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. 1. Select **Create project**. ## Create a new project with Git push @@ -206,8 +206,8 @@ used or renamed project, use the [UI](#create-a-project) or the [Projects API](. Prerequisites: -- To push with SSH, you must have [an SSH key](../../ssh/index.md) that is -[added to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). +- To push with SSH, you must have [an SSH key](../ssh.md) that is + [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: 1. On the top bar, select **Menu > Projects**. @@ -250,7 +250,7 @@ remote: The private project namespace/myproject was created. To view your new project, go to `https://gitlab.example.com/namespace/myproject`. Your project's visibility is set to **Private** by default. To change project visibility, adjust your -[project's settings](../../public_access/public_access.md#change-project-visibility). +[project's settings](../public_access.md#change-project-visibility). ## Star a project @@ -299,7 +299,7 @@ To delete a project: > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) in GitLab 14.9. [Feature flag `project_owners_list_project_pending_deletion`](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) removed. When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-deletion), -projects within that group are not deleted immediately, but only after a delay. +projects within that group are not deleted immediately, but only after a delay. To view a list of all projects that are pending deletion: @@ -409,9 +409,9 @@ To disable fetching: 1. Disable checksum queries in `GONOSUMDB`. - If the module name or its prefix is in `GOPRIVATE` or `GONOPROXY`, Go does not query module -proxies. + proxies. - If the module name or its prefix is in `GONOPRIVATE` or `GONOSUMDB`, Go does not query -Checksum databases. + Checksum databases. ### Fetch Go modules from Geo secondary sites diff --git a/doc/user/public_access.md b/doc/user/public_access.md new file mode 100644 index 00000000000..cca753a2830 --- /dev/null +++ b/doc/user/public_access.md @@ -0,0 +1,98 @@ +--- +stage: Manage +group: Workspace +info: 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 +--- + +# Project and group visibility **(FREE)** + +GitLab allows users with the Owner role to set a project's or group's visibility as: + +- **Public** +- **Internal** +- **Private** + +These visibility levels affect who can see the project in the public access directory (`/public` +for your GitLab instance). For example, <https://gitlab.com/public>. +You can control the visibility of individual features with +[project feature settings](permissions.md#project-features). + +## Public projects and groups + +Public projects can be cloned **without any** authentication over HTTPS. + +They are listed in the public access directory (`/public`) for all users. + +**Any signed-in user** has the Guest role on the repository. + +NOTE: +By default, `/public` is visible to unauthenticated users. However, if the +[**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) +is restricted, `/public` is visible only to signed-in users. + +## Internal projects and groups + +Internal projects can be cloned by any signed-in user except +[external users](permissions.md#external-users). + +They are also listed in the public access directory (`/public`), but only for signed-in users. + +Any signed-in users except [external users](permissions.md#external-users) have the +Guest role on the repository. + +NOTE: +From July 2019, the `Internal` visibility setting is disabled for new projects, groups, +and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` +visibility setting keep this setting. You can read more about the change in the +[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). + +## Private projects and groups + +Private projects can only be cloned and viewed by project members (except for guests). + +They appear in the public access directory (`/public`) for project members only. + +## Change project visibility + +Prerequisite: + +- You must have the Owner role for a project. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. +1. Select **Save changes**. + +## Change group visibility + +Prerequisite: + +- You must have the Owner role for a group. + +1. On the top bar, select **Menu > Groups** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Naming, visibility**. +1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. +1. Select **Save changes**. + +## Restrict use of public or internal projects **(FREE SELF)** + +You can restrict the use of visibility levels for users when they create a project or a snippet. +This is useful to prevent users from publicly exposing their repositories by accident. The +restricted visibility settings do not apply to administrators. + +For details, see [Restricted visibility levels](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels). + +<!-- ## 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/reserved_names.md b/doc/user/reserved_names.md index 33ecf252e43..45c5f53e33c 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -19,7 +19,7 @@ under the `TOP_LEVEL_ROUTES`, `PROJECT_WILDCARD_ROUTES` and `GROUP_ROUTES` lists ## Limitations on project and group names -- Special characters are not permitted at the start or end of project or group names. They are permitted in any other location of the name. +- Special characters are not permitted at the start or end of project or group names. They are permitted in any other location of the name. - Project or group names cannot end in `.git` or `.atom`. - Project or group names can only contain letters, digits, emojis, "_", ".", "+", dashes, or spaces. - Paths can only contain letters, digits, "_", "-", and "." diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index cb272b3feed..5435a9d027c 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -26,8 +26,8 @@ when searching in: - Comments - Code - Commits -- Wiki (except [group wikis](../project/wiki/group.md)) - Users +- Wiki (except [group wikis](../project/wiki/group.md)) The Advanced Search can be useful in various scenarios: @@ -46,72 +46,9 @@ The Advanced Search can be useful in various scenarios: may be connected to each other, so your developers need to instantly search throughout the GitLab instance and find the code they search for. -## Use the Advanced Search syntax - -Elasticsearch has data for the default branch only. That means that if you go -to the repository tree and switch the branch from the default to something else, -then the **Code** tab in the search result page is served by the basic -search even if Elasticsearch is enabled. - -The Advanced Search syntax supports fuzzy or exact search queries with prefixes, -boolean operators, and much more. Use the search as before and GitLab shows -you matching code from each project you have access to. - - - -Full details can be found in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/query-dsl-simple-query-string-query.html#_simple_query_string_syntax), but -here's a quick guide: - -- Searches look for all the words in a query, in any order - for example: searching - issues for [`display bug`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=display+bug&group_id=9970&project_id=278964) and [`bug display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+Display&group_id=9970&project_id=278964) return the same results. -- To find the exact phrase (stemming still applies), use double quotes: [`"display bug"`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%22display+bug%22&group_id=9970&project_id=278964) -- To find bugs not mentioning display, use `-`: [`bug -display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+-display&group_id=9970&project_id=278964) -- To find a bug in display or banner, use `|`: [`bug display | banner`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+display+%7C+banner&group_id=9970&project_id=278964) -- To group terms together, use parentheses: [`bug | (display +banner)`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) -- To match a partial word, use `*`. In this example, I want to find bugs with any 500 errors. : [`bug error 50*`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+error+50*&group_id=9970&project_id=278964) -- To use one of symbols above literally, escape the symbol with a preceding `\`: [`argument \-last`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=argument+%5C-last&group_id=9970&project_id=278964) - -## Syntax search filters - -Advanced Search also supports the use of filters. The available filters are: - -- `filename`: Filters by filename. You can use the glob (`*`) operator for fuzzy matching. -- `path`: Filters by path. You can use the glob (`*`) operator for fuzzy matching. -- `extension`: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only. -- `blob`: Filters by Git `object ID`. Exact match only. - -To use them, add them to your keyword in the format `<filter_name>:<value>` without -any spaces between the colon (`:`) and the value. When no keyword is provided, an asterisk (`*`) is used as the keyword. - -Examples: - -- Finding a file with any content named `search_results.rb`: [`* filename:search_results.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=*+filename%3Asearch_results.rb&group_id=9970&project_id=278964) -- The leading asterisk (`*`) can be ignored in the case above: [`filename:search_results.rb`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=filename%3Asearch_results.rb) -- Finding a file named `found_blob_spec.rb` with the text `CHANGELOG` inside of it: [`CHANGELOG filename:found_blob_spec.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=CHANGELOG+filename%3Afound_blob_spec.rb&group_id=9970&project_id=278964) -- Finding the text `EpicLinks` inside files with the `.rb` extension: [`EpicLinks extension:rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=EpicLinks+extension%3Arb&group_id=9970&project_id=278964) -- Finding any file with the `.yaml` extension: [`extension:yaml`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=extension%3Ayaml&group_id=9970&project_id=278964) -- Finding the text `Sidekiq` in a file, when that file is in a path that includes `elastic`: [`Sidekiq path:elastic`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=Sidekiq+path%3Aelastic&group_id=9970&project_id=278964) -- Finding any file in a path that includes `elasticsearch`: [`path:elasticsearch`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=path%3Aelasticsearch&group_id=9970&project_id=278964) -- Finding the files represented by the Git object ID `998707b421c89bd9a3063333f9f728ef3e43d101`: [`* blob:998707b421c89bd9a3063333f9f728ef3e43d101`](https://gitlab.com/search?snippets=false&scope=blobs&repository_ref=&search=*+blob%3A998707b421c89bd9a3063333f9f728ef3e43d101&group_id=9970) -- Syntax filters can be combined for complex filtering. Finding any file starting with `search` containing `eventHub` and with the `.js` extension: [`eventHub filename:search* extension:js`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=eventHub+filename%3Asearch*+extension%3Ajs&group_id=9970&project_id=278964) - -### Excluding filters - -> [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: - -- `-filename` -- `-path` -- `-extension` -- `-blob` - -Examples: +## Advanced Search syntax -- Finding `rails` in all files but `Gemfile.lock`: [`rails -filename:Gemfile.lock`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=rails+-filename%3AGemfile.lock&group_id=9970&project_id=278964) -- Finding `success` in all files excluding `.po|pot` files: [`success -filename:*.po*`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=success+-filename%3A*.po*&group_id=9970&project_id=278964) -- Finding `import` excluding minified JavaScript (`.min.js`) files: [`import -extension:min.js`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=import+-extension%3Amin.js&group_id=9970&project_id=278964) -- Finding `docs` for all files outside the `docs/` folder: [`docs -path:docs/`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=docs+-path%3Adocs%2F&group_id=9970&project_id=278964) +See the documentation on [Advanced Search syntax](global_search/advanced_search_syntax.md). ## Search by issue or merge request ID @@ -139,6 +76,7 @@ its performance: | Commits | `global_search_commits_tab` | When enabled, the global search includes commits as part of the search. | | Issues | `global_search_issues_tab` | When enabled, the global search includes issues as part of the search. | | Merge Requests | `global_search_merge_requests_tab` | When enabled, the global search includes merge requests as part of the search. | +| Users | `global_search_users_tab` | When enabled, the global search includes users as part of the search. | | Wiki | `global_search_wiki_tab` | When enabled, the global search includes wiki as part of the search. [Group wikis](../project/wiki/group.md) are not included. | ## Global Search validation diff --git a/doc/user/search/global_search/advanced_search_syntax.md b/doc/user/search/global_search/advanced_search_syntax.md new file mode 100644 index 00000000000..962aa00eea8 --- /dev/null +++ b/doc/user/search/global_search/advanced_search_syntax.md @@ -0,0 +1,49 @@ +--- +stage: Enablement +group: Global Search +info: "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 +--- + +# Advanced Search syntax **(PREMIUM)** + +With [Advanced Search](../advanced_search.md), you can perform a thorough +search through your entire GitLab instance. + +The Advanced Search syntax supports fuzzy or exact search queries with prefixes, +boolean operators, and much more. Advanced Search uses +[Elasticsearch's syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html#simple-query-string-syntax). + +WARNING: +Advanced Search searches projects' default branches only. + +See query examples on the tables below and their respective expected output. +The examples link to a search on GitLab.com to help you visualize the output. + +## General search + +| Query example | Expected output | +|---|---| +[`“display bug”`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%22display+bug%22&group_id=9970&project_id=278964) | Returns the **exact phrase** _display bug_ (stemming still applies). | +[`bug -display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+-display&group_id=9970&project_id=278964) | Results include _bug_, and **exclude** _display_. | +[<code>bug | display</code>](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+%7C+banner&group_id=9970&project_id=278964) | Results include _bug_ **or** _display_. | +[<code>bug | (display +banner)</code>](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) | Results include _bug_ **or** _display_ **and** _banner_. | +| [`bug error 50*`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+error+50*&group_id=9970&project_id=278964) | `*` finds **partial matches**. Results include _bug_, _error_, and the partial _50_ (looking for any 500 errors, for example). | +| [`bug \-display`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=argument+%5C-last&group_id=9970&project_id=278964) | `\` **scapes symbols**. Results include _bug_ **and** _-display_. | + +## Code Search + +| Query example | Expected output | Notes | +|---|---|---| +| [`filename:*spec.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=filename%3A*spec.rb&group_id=9970&project_id=278964) | Returns the specified filename. | Use `*` for fuzzy matching. | +| [`path:spec/controllers/`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=path%3Aspec%2Fcontrollers%2F&snippets=) | Returns the specified path location of the repository. | Use `*` for fuzzy matching. | +| [`extension:js`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=extension%3Ajs&snippets=) | Returns the specified file extension. | **Do not** include a leading dot. This only works with exact matches for the extension. | +| [`blob:998707b421c89b*`](https://gitlab.com/search?snippets=false&scope=blobs&repository_ref=&search=blob%3A998707b421c89b*&group_id=9970) | Returns the specified Git object ID. | This only works with exact matches. | + +## Excluding filters + +Filters can also be inverted to filter out results from the result set by prefixing the filter name with a `-` (hyphen) character. + +| Query example | Expected output | +|---|---| +| [`rails -filename:gemfile.lock`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=rails+-filename%3Agemfile.lock&snippets=) | Results include _`rails`_ in all files except the _`gemfile.lock`_ file. | diff --git a/doc/user/search/img/advanced_search_v13.10.png b/doc/user/search/img/advanced_search_v13.10.png Binary files differdeleted file mode 100644 index 39cd54fea75..00000000000 --- a/doc/user/search/img/advanced_search_v13.10.png +++ /dev/null diff --git a/doc/user/search/img/code_search_git_blame_v14_9.png b/doc/user/search/img/code_search_git_blame_v14_9.png Binary files differindex 33d4e77e3f5..eb8d14de4a4 100644 --- a/doc/user/search/img/code_search_git_blame_v14_9.png +++ b/doc/user/search/img/code_search_git_blame_v14_9.png diff --git a/doc/user/search/img/sort_projects.png b/doc/user/search/img/sort_projects.png Binary files differdeleted file mode 100644 index 9bf2770b299..00000000000 --- a/doc/user/search/img/sort_projects.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 44327af380e..de5f469498e 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -14,8 +14,12 @@ The numbers indicate how many issues, merge requests, and to-do items are assign  -- **{issues}** **Issues**: The open issues assigned to you. -- **{merge-request-open}** **Merge requests**: The [merge requests](../project/merge_requests/index.md) assigned to you. +- **{issues}** **Issues**: Issues assigned to you. +- **{merge-request-open}** **Merge requests**: Open [merge requests](../project/merge_requests/index.md). + Select the icon to show a dropdown list of merge request filters: + - [Attention requests](../project/merge_requests/index.md#request-attention-to-a-merge-request) (**{attention-solid}**) for you. + - [Review requests](../project/merge_requests/reviews/index.md) for you. + - Merge requests assigned to you. - **{todo-done}** **To-do items**: The [to-do items](../todos.md) assigned to you. You can search through **Open**, **Closed**, or **All** issues. @@ -37,6 +41,8 @@ in the search field in the upper right corner: > - Filtering by iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. > - Filtering by iterations was moved from GitLab Ultimate to GitLab Premium in 13.9. > - Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default. +> - Filtering by type was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 14.10. +> - Filtering by attention request was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343528) in GitLab 14.10 [with a flag](../../administration/feature_flags.md) named `mr_attention_requests`. Disabled by default. Follow these steps to filter the **Issues** and **Merge requests** list pages in projects and groups: @@ -44,6 +50,7 @@ groups: 1. Select **Search or filter results...**. 1. In the dropdown list that appears, select the attribute you wish to filter by: - Assignee + - [Attention requests](../project/merge_requests/index.md#request-attention-to-a-merge-request) - Author - Confidential - [Epic and child Epic](../group/epics/index.md) (available only for the group the Epic was created, not for [higher group levels](https://gitlab.com/gitlab-org/gitlab/-/issues/233729)). @@ -53,12 +60,6 @@ groups: - My-reaction - Release - Type - - FLAG: - On self-managed GitLab, by default filtering by type is not available. - To make it available per group, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `vue_issues_list`. - On GitLab.com, this feature is not available. - - Weight - Search for this text 1. Select or type the operator to use for filtering the attribute. The following operators are @@ -146,6 +147,10 @@ you can type (or select from the dropdown list) the following: - Deployed-before - Deployed-after +NOTE: +Projects using a [fast-forward merge method](../project/merge_requests/fast_forward_merge.md) +do not return results, as this method does not create a merge commit. + When filtering by an environment, a dropdown list presents all environments that you can choose from: @@ -207,10 +212,14 @@ You can also look for the projects you [starred](../project/working_with_project You can **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, through **Trending**, best rated with **Most stars**, or **All** of them. -You can also sort them by **Name**, **Last created**, **Oldest created**, **Last updated**, -**Oldest updated**, **Owner**, and choose to hide or show **archived projects**: +You can also sort them by: + +- Name +- Created date +- Updated date +- Owner - +You can also choose to hide or show archived projects. ## Groups @@ -221,7 +230,7 @@ On the field **Filter by name**, type the group name you want to find, and GitLa filters them for you as you type. You can also **Explore** all public and internal groups available in GitLab.com, -and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**. +and sort them by **Name**, **Last created**, **Oldest created**, or **Updated date**. ## Issue boards @@ -246,7 +255,7 @@ In the search bar, you can view autocomplete suggestions for: - Recently viewed issues (try and type some word from the title of a recently viewed issue) - Recently viewed merge requests (try and type some word from the title of a recently viewed merge request) - Recently viewed epics (try and type some word from the title of a recently viewed epic) -- [GitLab Flavored Markdown](../markdown.md#gitlab-specific-references) (GFM) for issues in a project (try and type a GFM reference for an issue) +- [GitLab Flavored Markdown](../markdown.md#gitlab-specific-references) (GLFM) for issues in a project (try and type a GLFM reference for an issue) ## Basic search diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index e807f251da1..e5285d63cf4 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -101,6 +101,12 @@ These shortcuts are available when viewing issues and [merge requests](project/m | <kbd>b</kbd> | Copy source branch name (merge requests only). | | <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | +Merge requests additionally support the following shortcuts: + +| macOS shortcut | Windows shortcut | Description | +|---------------------------------|---------------------|-------------| +| <kbd>Command</kbd> + <kbd>p</kbd> | <kbd>Control</kbd> + <kbd>p</kbd> | Search for, and then jump to a file for review. | + ### Project files These shortcuts are available when browsing the files in a project (go to diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 1750e2c8d10..cab18b221c1 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -22,7 +22,7 @@ using the [GitLab Workflow VS Code extension](project/repository/vscode.md). GitLab provides two types of snippets: - **Personal snippets**: Created independent of any project. - You can set a [visibility level](../public_access/public_access.md) + You can set a [visibility level](public_access.md) for your snippet: public, internal, or private. - **Project snippets**: Always related to a specific project. Project snippets can be visible publicly or to only group members. diff --git a/doc/user/ssh.md b/doc/user/ssh.md new file mode 100644 index 00000000000..54d4722ee2b --- /dev/null +++ b/doc/user/ssh.md @@ -0,0 +1,497 @@ +--- +stage: Manage +group: Authentication and Authorization +info: "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: howto, reference +--- + +# Use SSH keys to communicate with GitLab **(FREE)** + +Git is a distributed version control system, which means you can work locally, +then share or *push* your changes to a server. In this case, the server you push to is GitLab. + +GitLab uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the GitLab remote server, +you don't need to supply your username and password each time. + +## Prerequisites + +To use SSH to communicate with GitLab, you need: + +- The OpenSSH client, which comes pre-installed on GNU/Linux, macOS, and Windows 10. +- SSH version 6.5 or later. Earlier versions used an MD5 signature, which is not secure. + +To view the version of SSH installed on your system, run `ssh -V`. + +## Supported SSH key types + +To communicate with GitLab, you can use the following SSH key types: + +- [ED25519](#ed25519-ssh-keys) +- [ED25519_SK](#ed25519_sk-ssh-keys) (Available in GitLab 14.8 and later.) +- [ECDSA_SK](#ecdsa_sk-ssh-keys) (Available in GitLab 14.8 and later.) +- [RSA](#rsa-ssh-keys) +- DSA ([Deprecated](https://about.gitlab.com/releases/2018/06/22/gitlab-11-0-released/#support-for-dsa-ssh-keys) in GitLab 11.0.) +- ECDSA (As noted in [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-ecdsa), the security issues related to DSA also apply to ECDSA.) + +Administrators can [restrict which keys are permitted and their minimum lengths](../security/ssh_keys_restrictions.md). + +### ED25519 SSH keys + +The book [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-chapter-5-digital-signatures) +suggests that [ED25519](https://ed25519.cr.yp.to/) keys are more secure and performant than RSA keys. + +OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most +operating systems. + +### ED25519_SK SSH keys + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78934) in GitLab 14.8. + +To use ED25519_SK SSH keys on GitLab, your local client and GitLab server +must have [OpenSSH 8.2](https://www.openssh.com/releasenotes.html#8.2) or later installed. + +### ECDSA_SK SSH keys + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78934) in GitLab 14.8. + +To use ECDSA_SK SSH keys on GitLab, your local client and GitLab server +must have [OpenSSH 8.2](https://www.openssh.com/releasenotes.html#8.2) or later installed. + +### RSA SSH keys + +Available documentation suggests that ED25519 is more secure than RSA. + +If you use an RSA key, the US National Institute of Science and Technology in +[Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) +recommends a key size of at least 2048 bits. The default key size depends on your version of `ssh-keygen`. +Review the `man` page for your installed `ssh-keygen` command for details. + +## See if you have an existing SSH key pair + +Before you create a key pair, see if a key pair already exists. + +1. On Windows, Linux, or macOS, go to your home directory. +1. Go to the `.ssh/` subdirectory. If the `.ssh/` subdirectory doesn't exist, + you are either not in the home directory, or you haven't used `ssh` before. + In the latter case, you need to [generate an SSH key pair](#generate-an-ssh-key-pair). +1. See if a file with one of the following formats exists: + + | Algorithm | Public key | Private key | + | --------- | ---------- | ----------- | + | ED25519 (preferred) | `id_ed25519.pub` | `id_ed25519` | + | ED25519_SK | `id_ed25519_sk.pub` | `id_ed25519_sk` | + | ECDSA_SK | `id_ecdsa_sk.pub` | `id_ecdsa_sk` | + | RSA (at least 2048-bit key size) | `id_rsa.pub` | `id_rsa` | + | DSA (deprecated) | `id_dsa.pub` | `id_dsa` | + | ECDSA | `id_ecdsa.pub` | `id_ecdsa` | + +## Generate an SSH key pair + +If you do not have an existing SSH key pair, generate a new one. + +1. Open a terminal. +1. Type `ssh-keygen -t` followed by the key type and an optional comment. + This comment is included in the `.pub` file that's created. + You may want to use an email address for the comment. + + For example, for ED25519: + + ```shell + ssh-keygen -t ed25519 -C "<comment>" + ``` + + For 2048-bit RSA: + + ```shell + ssh-keygen -t rsa -b 2048 -C "<comment>" + ``` + +1. Press Enter. Output similar to the following is displayed: + + ```plaintext + Generating public/private ed25519 key pair. + Enter file in which to save the key (/home/user/.ssh/id_ed25519): + ``` + +1. Accept the suggested filename and directory, unless you are generating a [deploy key](project/deploy_keys/index.md) + or want to save in a specific directory where you store other keys. + + You can also dedicate the SSH key pair to a [specific host](#configure-ssh-to-point-to-a-different-directory). + +1. Specify a [passphrase](https://www.ssh.com/academy/ssh/passphrase): + + ```plaintext + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + ``` + +1. A confirmation is displayed, including information about where your files are stored. + +A public and private key are generated. +[Add the public SSH key to your GitLab account](#add-an-ssh-key-to-your-gitlab-account) and keep +the private key secure. + +### Configure SSH to point to a different directory + +If you did not save your SSH key pair in the default directory, +configure your SSH client to point to the directory where the private key is stored. + +1. Open a terminal and run this command: + + ```shell + eval $(ssh-agent -s) + ssh-add <directory to private SSH key> + ``` + +1. Save these settings in the `~/.ssh/config` file. For example: + + ```conf + # GitLab.com + Host gitlab.com + PreferredAuthentications publickey + IdentityFile ~/.ssh/gitlab_com_rsa + + # Private GitLab instance + Host gitlab.company.com + PreferredAuthentications publickey + IdentityFile ~/.ssh/example_com_rsa + ``` + + For more information on these settings, see the [`man ssh_config`](https://man.openbsd.org/ssh_config) page in the SSH configuration manual. + +Public SSH keys must be unique to GitLab because they bind to your account. +Your SSH key is the only identifier you have when you push code with SSH. +It must uniquely map to a single user. + +### Update your SSH key passphrase + +You can update the passphrase for your SSH key. + +1. Open a terminal and run this command: + + ```shell + ssh-keygen -p -f /path/to/ssh_key + ``` + +1. At the prompts, type the passphrase and press Enter. + +### Upgrade your RSA key pair to a more secure format + +If your version of OpenSSH is between 6.5 and 7.8, +you can save your private RSA SSH keys in a more secure +OpenSSH format. + +1. Open a terminal and run this command: + + ```shell + ssh-keygen -o -f ~/.ssh/id_rsa + ``` + + Alternatively, you can generate a new RSA key with the more secure encryption format with + the following command: + + ```shell + ssh-keygen -o -t rsa -b 4096 -C "<comment>" + ``` + +## Generate an SSH key pair for a FIDO/U2F hardware security key + +To generate ED25519_SK or ECDSA_SK SSH keys, you must use OpenSSH 8.2 or later. + +1. Insert a hardware security key into your computer. +1. Open a terminal. +1. Type `ssh-keygen -t` followed by the key type and an optional comment. + This comment is included in the `.pub` file that's created. + You may want to use an email address for the comment. + + For example, for ED25519_SK: + + ```shell + ssh-keygen -t ed25519-sk -C "<comment>" + ``` + + For ECDSA_SK: + + ```shell + ssh-keygen -t ecdsa-sk -C "<comment>" + ``` + + If your security key supports FIDO2 resident keys, you can enable this when + creating your SSH key: + + ```shell + ssh-keygen -t ed25519-sk -O resident -C "<comment>" + ``` + + `-O resident` indicates that the key should be stored on the FIDO authenticator itself. + Resident key is easier to import to a new computer because it can be loaded directly + from the security key by [`ssh-add -K`](https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/ssh-add.1#K) + or [`ssh-keygen -K`](https://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/ssh-keygen#K). + +1. Select Enter. Output similar to the following is displayed: + + ```plaintext + Generating public/private ed25519-sk key pair. + You may need to touch your authenticator to authorize key generation. + ``` + +1. Touch the button on the hardware security key. + +1. Accept the suggested filename and directory: + + ```plaintext + Enter file in which to save the key (/home/user/.ssh/id_ed25519_sk): + ``` + +1. Specify a [passphrase](https://www.ssh.com/academy/ssh/passphrase): + + ```plaintext + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + ``` + +1. A confirmation is displayed, including information about where your files are stored. + +A public and private key are generated. +[Add the public SSH key to your GitLab account](#add-an-ssh-key-to-your-gitlab-account). + +## Add an SSH key to your GitLab account + +To use SSH with GitLab, copy your public key to your GitLab account. + +1. Copy the contents of your public key file. You can do this manually or use a script. + For example, to copy an ED25519 key to the clipboard: + + **macOS:** + + ```shell + tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy + ``` + + **Linux** (requires the `xclip` package): + + ```shell + xclip -sel clip < ~/.ssh/id_ed25519.pub + ``` + + **Git Bash on Windows:** + + ```shell + cat ~/.ssh/id_ed25519.pub | clip + ``` + + Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA. + +1. Sign in to GitLab. +1. On the top bar, in the top right corner, select your avatar. +1. Select **Preferences**. +1. On the left sidebar, select **SSH Keys**. +1. In the **Key** box, paste the contents of your public key. + If you manually copied the key, make sure you copy the entire key, + which starts with `ssh-rsa`, `ssh-dss`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, + `ssh-ed25519`, `sk-ecdsa-sha2-nistp256@openssh.com`, or `sk-ssh-ed25519@openssh.com`, and may end with a comment. +1. In the **Title** box, type a description, like `Work Laptop` or + `Home Workstation`. +1. Optional. In the **Expires at** box, select an expiration date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36243) in GitLab 12.9.) + In: + - GitLab 13.12 and earlier, the expiration date is informational only. It doesn't prevent + you from using the key. Administrators can view expiration dates and use them for + guidance when [deleting keys](admin_area/credentials_inventory.md#delete-a-users-ssh-key). + - GitLab 14.0 and later, the expiration date is enforced. Administrators can + [allow expired keys to be used](admin_area/settings/account_and_limit_settings.md#allow-expired-ssh-keys-to-be-used-deprecated). + - GitLab checks all SSH keys at 02:00 AM UTC every day. It emails an expiration notice for all SSH keys that expire on the current date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.) + - GitLab checks all SSH keys at 01:00 AM UTC every day. It emails an expiration notice for all SSH keys that are scheduled to expire seven days from now. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.) +1. Select **Add key**. + +## Verify that you can connect + +Verify that your SSH key was added correctly. + +1. For GitLab.com, to ensure you're connecting to the correct server, confirm the + [SSH host keys fingerprints](gitlab_com/index.md#ssh-host-keys-fingerprints). +1. Open a terminal and run this command, replacing `gitlab.example.com` with your GitLab instance URL: + + ```shell + ssh -T git@gitlab.example.com + ``` + +1. If this is the first time you connect, you should verify the + authenticity of the GitLab host. If you see a message like: + + ```plaintext + The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established. + ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw. + Are you sure you want to continue connecting (yes/no)? yes + Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts. + ``` + + Type `yes` and press Enter. + +1. Run the `ssh -T git@gitlab.example.com` command again. You should receive a _Welcome to GitLab, `@username`!_ message. + +If the welcome message doesn't appear, you can troubleshoot by running `ssh` +in verbose mode: + +```shell +ssh -Tvvv git@gitlab.example.com +``` + +## Use different keys for different repositories + +You can use a different key for each repository. + +Open a terminal and run this command: + +```shell +git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null" +``` + +This command does not use the SSH Agent and requires Git 2.10 or later. For more information +on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`. + +## Use different accounts on a single GitLab instance + +You can use multiple accounts to connect to a single instance of GitLab. +You can do this by using the command in the [previous topic](#use-different-keys-for-different-repositories). +However, even if you set `IdentitiesOnly` to `yes`, you cannot sign in if an `IdentityFile` exists +outside of a `Host` block. + +Instead, you can assign aliases to hosts in the `~.ssh/config` file. + +- For the `Host`, use an alias like `user_1.gitlab.com` and + `user_2.gitlab.com`. Advanced configurations + are more difficult to maintain, and these strings are easier to + understand when you use tools like `git remote`. +- For the `IdentityFile`, use the path the private key. + +```conf +# User1 Account Identity +Host <user_1.gitlab.com> + Hostname gitlab.com + PreferredAuthentications publickey + IdentityFile ~/.ssh/<example_ssh_key1> + +# User2 Account Identity +Host <user_2.gitlab.com> + Hostname gitlab.com + PreferredAuthentications publickey + IdentityFile ~/.ssh/<example_ssh_key2> +``` + +Now, to clone a repository for `user_1`, use `user_1.gitlab.com` in the `git clone` command: + +```shell +git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git +``` + +To update a previously-cloned repository that is aliased as `origin`: + +```shell +git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git +``` + +NOTE: +Private and public keys contain sensitive data. Ensure the permissions +on the files make them readable to you but not accessible to others. + +## Configure two-factor authentication (2FA) + +You can set up two-factor authentication (2FA) for +[Git over SSH](../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations). We recommend using +[ED25519_SK](#ed25519_sk-ssh-keys) or [ECDSA_SK](#ecdsa_sk-ssh-keys) SSH keys. + +## Use EGit on Eclipse + +If you are using [EGit](https://www.eclipse.org/egit/), you can [add your SSH key to Eclipse](https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration). + +## Use SSH on Microsoft Windows + +If you're running Windows 10, you can either use the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) +with [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install#update-to-wsl-2) which +has both `git` and `ssh` preinstalled, or install [Git for Windows](https://gitforwindows.org) to +use SSH through PowerShell. + +The SSH key generated in WSL is not directly available for Git for Windows, and vice versa, +as both have a different home directory: + +- WSL: `/home/<user>` +- Git for Windows: `C:\Users\<user>` + +You can either copy over the `.ssh/` directory to use the same key, or generate a key in each environment. + +Alternative tools include: + +- [Cygwin](https://www.cygwin.com) +- [PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) + +## Overriding SSH settings on the GitLab server + +GitLab integrates with the system-installed SSH daemon and designates a user +(typically named `git`) through which all access requests are handled. Users +who connect to the GitLab server over SSH are identified by their SSH key instead +of their username. + +SSH *client* operations performed on the GitLab server are executed as this +user. You can modify this SSH configuration. For example, you can specify +a private SSH key for this user to use for authentication requests. However, this practice +is **not supported** and is strongly discouraged as it presents significant +security risks. + +GitLab checks for this condition, and directs you +to this section if your server is configured this way. For example: + +```shell +$ gitlab-rake gitlab:check + +Git user has default SSH configuration? ... no + Try fixing it: + mkdir ~/gitlab-check-backup-1504540051 + sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051 + sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051 + For more information see: + doc/user/ssh.md#overriding-ssh-settings-on-the-gitlab-server + Please fix the error above and rerun the checks. +``` + +Remove the custom configuration as soon as you can. These customizations +are **explicitly not supported** and may stop working at any time. + +## Troubleshooting + +### Password prompt with `git clone` + +When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`. +This indicates that something is wrong with your SSH setup. + +- Ensure that you generated your SSH key pair correctly and added the public SSH + key to your GitLab profile. +- Try to manually register your private SSH key by using `ssh-agent`. +- Try to debug the connection by running `ssh -Tv git@example.com`. + Replace `example.com` with your GitLab URL. + +### `Could not resolve hostname` error + +You may receive the following error when [verifying that you can connect](#verify-that-you-can-connect): + +```shell +ssh: Could not resolve hostname gitlab.example.com: nodename nor servname provided, or not known +``` + +If you receive this error, restart your terminal and try the command again. + +### `Key enrollment failed: invalid format` error + +You may receive the following error when [generating an SSH key pair for a FIDO/U2F hardware security key](#generate-an-ssh-key-pair-for-a-fidou2f-hardware-security-key): + +```shell +Key enrollment failed: invalid format +``` + +You can troubleshoot this by trying the following: + +- Run the `ssh-keygen` command using `sudo`. +- Verify your IDO/U2F hardware security key supports + the key type provided. +- Verify the version of OpenSSH is 8.2 or greater by + running `ssh -v`. diff --git a/doc/user/todos.md b/doc/user/todos.md index ec316d8ebe4..5cea619c830 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -119,7 +119,7 @@ Actions that dismiss to-do items include: - Closing the issue or merge request - Adding or removing a label - Commenting on the issue -- Resolving a [design discussion thread](project/issues/design_management.md#resolve-design-threads) +- Resolving a [design discussion thread](project/issues/design_management.md#resolve-a-discussion-thread-on-a-design) If someone else closes, merges, or takes action on an issue, merge request, or epic, your to-do item remains pending. |
