diff options
Diffstat (limited to 'doc/user')
170 files changed, 3151 insertions, 2296 deletions
diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md index 71b5617a4a9..931876682e0 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -17,7 +17,7 @@ GitLab is creating AI-assisted features across our DevSecOps platform. These fea | Helps you discover or recall Git commands when and where you need them. | [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | **(ULTIMATE SAAS EXPERIMENT)** | | Assists with quickly getting everyone up to speed on lengthy conversations to help ensure you are all on the same page. | [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | **(ULTIMATE SAAS EXPERIMENT)** | | Generates issue descriptions. | [Issue description generation](#summarize-an-issue-with-issue-description-generation) | **(ULTIMATE SAAS EXPERIMENT)** | -| Helps you write code more efficiently by viewing code suggestions as you type. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=hCAyCTacdAQ) | [Code Suggestions](project/repository/code_suggestions/index.md) | For SaaS: **(FREE BETA)**<br><br> For self-managed: **(ULTIMATE BETA)** | +| Helps you write code more efficiently by viewing code suggestions as you type. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=hCAyCTacdAQ) | [Code Suggestions](project/repository/code_suggestions/index.md) | For SaaS: **(FREE)**<br><br> For self-managed: **(PREMIUM)** | | Automates repetitive tasks and helps catch bugs early. | [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | **(ULTIMATE SAAS EXPERIMENT)** | | Generates a description for the merge request based on the contents of the template. | [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | **(ULTIMATE SAAS EXPERIMENT)** | | Assists in creating faster and higher-quality reviews by automatically suggesting reviewers for your merge request. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=ivwZQgh4Rxw) | [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | **(ULTIMATE SAAS)** | @@ -26,7 +26,7 @@ GitLab is creating AI-assisted features across our DevSecOps platform. These fea | Helps you remediate vulnerabilities more efficiently, boost your skills, and write more secure code. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=6sDf73QOav8) | [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | **(ULTIMATE SAAS BETA)** | | Generates a merge request containing the changes required to mitigate a vulnerability. | [Vulnerability resolution](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | **(ULTIMATE SAAS EXPERIMENT)** | | Helps you understand code by explaining it in English language. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=1izKaLmmaCA) | [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | **(ULTIMATE SAAS EXPERIMENT)** | -| Processes and generates text and code in a conversational manner. Helps you quickly identify useful information in large volumes of text in issues, epics, code, and GitLab documentation. | [GitLab Duo Chat](gitlab_duo_chat.md) | **(ULTIMATE SAAS BETA)** | +| Processes and generates text and code in a conversational manner. Helps you quickly identify useful information in large volumes of text in issues, epics, code, and GitLab documentation. | [GitLab Duo Chat](gitlab_duo_chat.md) | **(ULTIMATE BETA)** | | Assists you in determining the root cause for a pipeline failure and failed CI/CD build. | [Root cause analysis](#root-cause-analysis) | **(ULTIMATE SAAS EXPERIMENT)** | | Assists you with predicting productivity metrics and identifying anomalies across your software development lifecycle. | [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | **(ULTIMATE ALL EXPERIMENT)** | diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index 0699be4e0ad..e647dcf170a 100644 --- a/doc/user/analytics/analytics_dashboards.md +++ b/doc/user/analytics/analytics_dashboards.md @@ -55,7 +55,7 @@ With custom dashboards, you can design and create visualizations for the metrics You can create custom dashboards with the dashboard designer. - Each project can have an unlimited number of dashboards. -The only limitation might be the [repository size limit](../project/repository/reducing_the_repo_size_using_git.md#storage-limits). + The only limitation might be the [repository size limit](../project/repository/reducing_the_repo_size_using_git.md#storage-limits). - Each dashboard can reference one or more [visualizations](#define-a-chart-visualization). - Visualizations are shared across dashboards. @@ -122,12 +122,11 @@ To view the Value Streams Dashboard as an analytics dashboard for a project: ## View group dashboards -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390542) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390542) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/416970) in GitLab 16.8. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. On GitLab.com, this feature is available. Prerequisites: @@ -226,7 +225,7 @@ You can define different charts, and add visualization options to some of them: - Line chart, with the options listed in the [ECharts documentation](https://echarts.apache.org/en/option.html). - Column chart, with the options listed in the [ECharts documentation](https://echarts.apache.org/en/option.html). -- Data table, with the only option to render `links` (array of objects, each with `text` and `href` properties to specify the dimensions to be used in links). See [example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/analytics_visualization.json?ref_type=heads#L112)). +- Data table. - Single stat, with the only option to set `decimalPlaces` (number, default value is 0). To define a chart for your dashboards: @@ -304,5 +303,5 @@ If a dashboard panel displays a message that the visualization configuration is If a dashboard panel displays an error message: - Check your [Cube query](../product_analytics/index.md#product-analytics-dashboards) and [visualization](../analytics/analytics_dashboards.md#define-a-chart-visualization) -configurations, and make sure they are set up correctly. + configurations, and make sure they are set up correctly. - For [product analytics](../product_analytics/index.md), also check that your visualization's Cube query is valid. diff --git a/doc/user/analytics/contributor_statistics.md b/doc/user/analytics/contributor_statistics.md deleted file mode 100644 index b6f195e22ad..00000000000 --- a/doc/user/analytics/contributor_statistics.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'contributor_analytics.md' -remove_date: '2023-03-06' ---- - -This document was moved to [another location](contributor_analytics.md). - -<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> -<!-- 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/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index 53a25acbca5..372ea0a5807 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -121,7 +121,7 @@ GitLab calculates this as the number of incidents divided by the number of deplo - [GitLab incidents](../../operations/incident_management/incidents.md) are tracked. - 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. + more than one incident. ### How to improve change failure rate diff --git a/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png b/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png Binary files differindex 519e56acaa5..b253fe336ee 100644 --- a/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png +++ b/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index d58426bd76b..eef34214c23 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,6 +1,7 @@ --- stage: Plan group: Optimize +description: Instance, group, and project analytics. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index b8aa23a0af2..089a5636a52 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -1,63 +1,11 @@ --- -stage: Plan -group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../group/issues_analytics/index.md' +remove_date: '2024-04-05' --- -# Issue analytics for projects **(PREMIUM ALL)** +This document was moved to [another location](../group/issues_analytics/index.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in GitLab 12.9. - -Issue analytics is a bar graph which illustrates the number of issues created each month. -The default time span is 13 months, which includes the current month, and the 12 months -prior. - -To access the chart: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Analyze > Issue analytics**. - -You can also access the chart from the [Value Streams Dashboard](value_streams_dashboard.md#dashboard-metrics-and-drill-down-reports) through the **New issues** drill-down report. - -Hover over each bar to see the total number of issues. - -To narrow the scope of issues included in the graph, enter your criteria in the -**Search or filter results...** field. Criteria from the following list can be typed in or selected from a menu: - -- Author -- Assignee -- Milestone -- Label -- My reaction -- Weight - -You can change the total number of months displayed by setting a URL parameter. -For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` -shows a total of 15 months for the chart in the GitLab.org group. - - - -## Enhanced issue analytics **(ULTIMATE ALL)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233905/) in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can -[enable the feature flag](../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. On GitLab.com, this feature is not -available. This feature is not ready for production use. - -Enhanced issue analytics display the additional metric "Issues closed", which represents the total number of resolved issues in your project over a selected period. -You can use this metric to improve the overall turn-around time and value delivered to your customers. - - - -## Drill into the information - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196547) in GitLab 13.1. - -You can examine details of individual issues by browsing the table -located below the chart. - -The chart displays the top 100 issues based on the global page filters. - - +<!-- This redirect file can be deleted after <2024-04-05>. --> +<!-- 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/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 5b5b1ec002d..0d2c375f7ae 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -46,8 +46,8 @@ To view the number of merge requests merged during a specific date range: 1. Select a parameter. 1. Select a value or enter text to refine the results. 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. + - In the **From** field, select a start date. + - In the **To** field, select an end date. The **Throughput** chart shows issues closed or merge requests merged (not closed) over a period of time. @@ -75,4 +75,4 @@ To view **Mean time to merge**: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Merge request analytics**. The **Mean time to merge** number -is displayed on the dashboard. + is displayed on the dashboard. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 93171dc3136..8bc163f6f3f 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use repository analytics to view information about a project's Git repository: -- Programming languages used in the repository. +- Programming languages used in the repository's default branch. - Code coverage history from last 3 months ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1). - Commit statistics (last month). - Commits per day of month. diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index a50eab42a2d..c093fdf8cb3 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -16,7 +16,7 @@ For more information, see also the [Value Stream Management category direction p The Value Streams Dashboard is a customizable dashboard you can use to identify trends, patterns, and opportunities for digital transformation improvements. The centralized UI in Value Streams Dashboard acts as the single source of truth (SSOT), where all stakeholders can access and view the same set of metrics that are relevant to the organization. -The Value Streams Dashboard includes the following metrics: +The Value Streams Dashboard includes two panels (DevSecOps metrics comparison and DORA Performers score) that visualize the following metrics: - [DORA metrics](dora_metrics.md) - [Value Stream Analytics (VSA) - flow metrics](../group/value_stream_analytics/index.md) @@ -29,9 +29,11 @@ With the Value Streams Dashboard, you can: - Understand security exposure. - Drill down into individual projects or metrics to take actions for improvement. -The Value Streams Dashboard has a default configuration, but you can also [customize the dashboard panels](#customize-the-dashboard-panels). +## Value Streams Dashboard panels -## DevSecOps metrics comparison panel +The Value Streams Dashboard panels has a default configuration, but you can also [customize the dashboard panels](#customize-the-dashboard-panels). + +### DevSecOps metrics comparison panel The DevSecOps metrics comparison displays DORA4, vulnerability, and flow metrics for a group or project in the month-to-date, last month, the month before, and the past 180 days. @@ -46,7 +48,7 @@ that are the largest value contributors, overperforming, or underperforming. You can also drill down the metrics for further analysis. When you hover over a metric, a tooltip displays an explanation of the metric and a link to the related documentation page. -## DORA Performers score panel +### DORA Performers score panel > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386843) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `dora_performers_score_panel`. Disabled by default. @@ -73,7 +75,7 @@ For example, if a project has a high score for Deployment Frequency (Velocity), These scoring are based on Google's classifications in the [DORA 2022 Accelerate State of DevOps Report](https://cloud.google.com/blog/products/devops-sre/dora-2022-accelerate-state-of-devops-report-now-out). -### Filter by project topics +#### Filter the DORA Performers score by project topics When used in combination with a [YAML configuration](#using-yaml-configuration), you can filter the projects shown based on their assigned [topics](../project/settings/project_features_permissions.md#project-topics). @@ -90,17 +92,9 @@ If multiple topics are provided, all topics will need to match for the project t ## Enable or disable overview background aggregation **(ULTIMATE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120610) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `modify_value_stream_dashboard_settings`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120610) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `value_stream_dashboard_on_off_setting`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130704) in GitLab 16.4. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `modify_value_stream_dashboard_settings`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - -Prerequisites: - -- You must have administrator access to the instance. +> - [Feature flag `value_stream_dashboard_on_off_setting` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134619) in GitLab 16.6. To enable or disable the overview count aggregation for the Value Streams Dashboard: @@ -221,9 +215,19 @@ panels: <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview of editing label filters in the configuration file, see [GitLab Value Streams Dashboard - Label filters demo](https://www.youtube.com/watch?v=4qDAHCxCfik). +### Filter the DevSecOps metrics comparison panel by labels + Label filters are appended as query parameters to the URL of the drill-down report of each eligible metric and automatically applied. If the comparison panel from the configuration file is enabled with `filter_labels`, the drill-down links inherit the labels from the panel filter. +```yaml + - data: + namespace: group/another-project + filter_labels: + - in_development + - in_review +``` + ## Dashboard metrics and drill-down reports | Metric | Description | Drill-down report | Documentation page | ID | diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index 9c16c70c78f..01515a90653 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -105,7 +105,7 @@ responses in HAR format. #### Create a HAR file with Fiddler 1. Go to the [Fiddler home page](https://www.telerik.com/fiddler) and sign in. If you don't already -have an account, first create an account. + have an account, first create an account. 1. Browse pages that call an API. Fiddler automatically captures the requests. 1. Select one or more requests, then from the context menu, select **Export > Selected Sessions**. 1. In the **Choose Format** dropdown list select **HTTPArchive v1.2**. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 735b2356780..cab8c926def 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -498,15 +498,15 @@ The following is a summary of the variable scopes supported by the Postman Clien - **Global Environment (Global) scope** is a special pre-defined environment that is available throughout a workspace. We can also refer to the _global environment_ scope as the _global_ scope. The Postman Client allows exporting the global environment into a JSON file, which can be used with API Fuzzing. - **Environment scope** is a named group of variables created by a user in the Postman Client. -The Postman Client supports a single active environment along with the global environment. The variables defined in an active user-created environment take precedence over variables defined in the global environment. The Postman Client allows exporting your environment into a JSON file, which can be used with API Fuzzing. + The Postman Client supports a single active environment along with the global environment. The variables defined in an active user-created environment take precedence over variables defined in the global environment. The Postman Client allows exporting your environment into a JSON file, which can be used with API Fuzzing. - **Collection scope** is a group of variables declared in a given collection. The collection variables are available to the collection where they have been declared and the nested requests or collections. Variables defined in the collection scope take precedence over the _global environment_ scope and also the _environment_ scope. -The Postman Client can export one or more collections into a JSON file, this JSON file contains selected collections, requests, and collection variables. + The Postman Client can export one or more collections into a JSON file, this JSON file contains selected collections, requests, and collection variables. - **API Fuzzing Scope** is a new scope added by API Fuzzing to allow users to provide extra variables, or override variables defined in other supported scopes. This scope is not supported by Postman. The _API Fuzzing Scope_ variables are provided using a [custom JSON file format](#api-fuzzing-scope-custom-json-file-format). - Override values defined in the environment or collection - Defining variables from scripts - Define a single row of data from the unsupported _data scope_ - **Data scope** is a group of variables in which their name and values come from JSON or CSV files. A Postman collection runner like [Newman](https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/) or [Postman Collection Runner](https://learning.postman.com/docs/running-collections/intro-to-collection-runs/) executes the requests in a collection as many times as entries have the JSON or CSV file. A good use case for these variables is to automate tests using scripts in Postman. -API Fuzzing does **not** support reading data from a CSV or JSON file. + API Fuzzing does **not** support reading data from a CSV or JSON file. - **Local scope** are variables that are defined in Postman scripts. API Fuzzing does **not** support Postman scripts and by extension, variables defined in scripts. You can still provide values for the script-defined variables by defining them in one of the supported scopes, or our custom JSON format. Not all scopes are supported by API Fuzzing and variables defined in scripts are not supported. The following table is sorted by broadest scope to narrowest scope. diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 008b5b54cca..c367d647c6c 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -50,7 +50,7 @@ You can configure the following security controls: - [Dynamic Application Security Testing](../dast/index.md) (DAST) - Select **Enable DAST** to configure DAST for the current project. - Select **Manage scans** to manage the saved DAST scans, site profiles, and scanner profiles. - For more details, read [DAST on-demand scans](../dast/proxy-based.md#on-demand-scans). + For more details, read [DAST on-demand scans](../dast/on-demand_scan.md). - [Dependency Scanning](../dependency_scanning/index.md) - Select **Configure with a merge request** to create a merge request with the changes required to enable Dependency Scanning. For more information, see [Use a preconfigured merge request](../dependency_scanning/index.md#use-a-preconfigured-merge-request). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 8af262e564b..5be9e169078 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -17,7 +17,7 @@ vulnerabilities and displays them in a merge request, you can use GitLab to audi apps. - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Container Scanning](https://www.youtube.com/watch?v=C0jn2eN5MAs). + For an overview, see [Container Scanning](https://www.youtube.com/watch?v=C0jn2eN5MAs). - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a video walkthrough, see [How to set up Container Scanning using GitLab](https://youtu.be/h__mcXpil_4?si=w_BVG68qnkL9x4l1). Container Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain @@ -128,10 +128,6 @@ Setting `CS_DEFAULT_BRANCH_IMAGE` avoids duplicate vulnerability findings when a The value of `CS_DEFAULT_BRANCH_IMAGE` indicates the name of the scanned image as it appears on the default branch. For more details on how this deduplication is achieved, see [Setting the default branch image](#setting-the-default-branch-image). -## Running jobs in merge request pipelines - -See [Use security scanning tools with merge request pipelines](../index.md#use-security-scanning-tools-with-merge-request-pipelines) - ### Customizing the container scanning settings There may be cases where you want to customize how GitLab scans your containers. For example, you @@ -243,6 +239,10 @@ if [Dependency Scanning](../dependency_scanning/index.md) is enabled for your project. This happens because GitLab can't automatically deduplicate findings across different types of scanning tools. To understand which types of dependencies are likely to be duplicated, see [Dependency Scanning compared to Container Scanning](../comparison_dependency_and_container_scanning.md). +#### Running jobs in merge request pipelines + +See [Use security scanning tools with merge request pipelines](../index.md#use-security-scanning-tools-with-merge-request-pipelines). + #### Available CI/CD variables You can [configure](#customizing-the-container-scanning-settings) analyzers by using the following CI/CD variables. @@ -263,7 +263,7 @@ including a large number of false positives. | `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_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | -| `CS_IGNORE_STATUSES` | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | +| `CS_IGNORE_STATUSES`<sup><b><a href="#notes-regarding-cs-ignore-statuses">1</a></b></sup> | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | | `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | | `CS_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | 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 | @@ -275,6 +275,15 @@ including a large number of false positives. | `CS_TRIVY_JAVA_DB` | `"ghcr.io/aquasecurity/trivy-java-db"` | Specify an alternate location for the [trivy-java-db](https://github.com/aquasecurity/trivy-java-db) vulnerability database. | Trivy | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. | All | +<ol> + <li> + <a id="notes-regarding-cs-ignore-statuses"></a> + <p> + Fix status information is highly dependent on accurate fix availability data from the software vendor and container image operating system package metadata. It is also subject to interpretation by individual container scanners. In cases where a container scanner misreports the availability of a fixed package for a vulnerability, using `CS_IGNORE_STATUSES` can lead to false positive or false negative filtering of findings when this setting is enabled. + </p> + </li> +</ol> + ### Supported distributions Support depends on which scanner is used: @@ -370,6 +379,9 @@ The following options are available: | [Grype](https://github.com/anchore/grype) | `registry.gitlab.com/security-products/container-scanning/grype:6` | | Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:6` | +WARNING: +Do not use the `:latest` tag when selecting the scanner image. + ### Setting the default branch image > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. @@ -766,8 +778,7 @@ The images use data from upstream advisory databases depending on which scanner In addition to the sources provided by these scanners, GitLab maintains the following vulnerability databases: -- The proprietary -[GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). +- The proprietary [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). - The open source [GitLab Advisory Database (Open Source Edition)](https://gitlab.com/gitlab-org/advisories-community). In the GitLab Ultimate tier, the data from the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is merged in to augment the data from the external sources. In the GitLab Premium and Free tiers, the data from the [GitLab Advisory Database (Open Source Edition)](https://gitlab.com/gitlab-org/advisories-community) is merged in to augment the data from the external sources. This augmentation currently only applies to the analyzer images for the Trivy scanner. diff --git a/doc/user/application_security/continuous_vulnerability_scanning/index.md b/doc/user/application_security/continuous_vulnerability_scanning/index.md index 4d6d48012ae..7d083ea1846 100644 --- a/doc/user/application_security/continuous_vulnerability_scanning/index.md +++ b/doc/user/application_security/continuous_vulnerability_scanning/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427424) in GitLab 16.7 with an additional feature flag named `global_dependency_scanning_on_advisory_ingestion`. Enabled by default. FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flags](../../feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flags](../../feature_flags.md) named `dependency_scanning_on_advisory_ingestion`. On GitLab.com, this feature is available. Continuous Vulnerability Scanning detects new vulnerabilities outside a pipeline. diff --git a/doc/user/application_security/dast/checks/78.1.md b/doc/user/application_security/dast/checks/78.1.md index bcb655f37ae..ae0af7b1552 100644 --- a/doc/user/application_security/dast/checks/78.1.md +++ b/doc/user/application_security/dast/checks/78.1.md @@ -22,7 +22,7 @@ Ensure your application does not: - Use user-supplied information in the process name to execute. - Use user-supplied information in an OS command execution function which does -not escape shell meta-characters. + not escape shell meta-characters. - Use user-supplied information in arguments to OS commands. The application should have a hardcoded set of arguments that are to be passed diff --git a/doc/user/application_security/dast/on-demand_scan.md b/doc/user/application_security/dast/on-demand_scan.md new file mode 100644 index 00000000000..e43057aea54 --- /dev/null +++ b/doc/user/application_security/dast/on-demand_scan.md @@ -0,0 +1,409 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# DAST On Demand Scan **(ULTIMATE ALL)** + +WARNING: +Do not run DAST scans against a production server. Not only can it perform *any* function that a user can, such +as clicking buttons or submitting forms, but it may also trigger bugs, leading to modification or loss of production data. +Only run DAST scans against a test server. + +## On-demand scans + +> - Auditing for DAST profile management [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. +> - Scheduled on-demand DAST scans [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3 [with a flag](../../../administration/feature_flags.md) named `dast_on_demand_scans_scheduler`. Disabled by default. +> - Scheduled on-demand DAST scans [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. Feature flag `dast_on_demand_scans_scheduler` removed. +> - Runner tags selection [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111499) in GitLab 16.3. +> - Browser based on-demand DAST scans [deployed behind the feature flag `dast_ods_browser_based_scanner`](https://gitlab.com/gitlab-org/gitlab/-/issues/430212) in GitLab 16.8. + +An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger +the scan. You must either start it manually, or schedule it to run. For on-demand DAST scans, +a [site profile](#site-profile) defines **what** is to be scanned, and a +[scanner profile](#scanner-profile) defines **how** the application is to be scanned. + +An on-demand scan can be run in active or passive mode: + +- **Passive mode**: The default mode, which runs a [Passive Browser based scan](/ee/user/application_security/dast/browser_based.md#passive-scans). +- **Active mode**: Runs an [Active Browser based scan](/ee/user/application_security/dast/browser_based.md#active-scans) which is potentially harmful to the site being scanned. To + minimize the risk of accidental damage, running an active scan requires a + [validated site profile](#site-profile-validation). + +### View on-demand DAST scans + +To view on-demand scans: + +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Secure > On-demand scans**. + +On-demand scans are grouped by their status. The scan library contains all available on-demand +scans. + +### Run an on-demand DAST scan + +Prerequisites: + +- You must have permission to run an on-demand DAST scan against a protected branch. The default + branch is automatically protected. For more information, see + [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +To run an existing on-demand scan: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > On-demand scans**. +1. Select the **Scan library** tab. +1. In the scan's row, select **Run scan**. + + If the branch saved in the scan no longer exists, you must: + + 1. [Edit the scan](#edit-an-on-demand-scan). + 1. Select a new branch. + 1. Save the edited scan. + +The on-demand DAST scan runs, and the project's dashboard shows the results. + +#### Create an on-demand scan + +Create an on-demand scan to: + +- Run it immediately. +- Save it to be run in the future. +- Schedule it to be run at a specified schedule. + +To create an on-demand DAST scan: + +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Secure > On-demand scans**. +1. Select **New scan**. +1. Complete the **Scan name** and **Description** fields. +1. In the **Branch** dropdown list, select the desired branch. +1. Optional. Select the runner tags. +1. Select **Select scanner profile** or **Change scanner profile** to open the drawer, and either: + - Select a scanner profile from the drawer, **or** + - Select **New profile**, create a [scanner profile](#scanner-profile), then select **Save profile**. +1. Select **Select site profile** or **Change site profile** to open the drawer, and either: + - Select a site profile from the **Site profile library** drawer, or + - Select **New profile**, create a [site profile](#site-profile), then select **Save profile**. +1. To run the on-demand scan: + + - Immediately, select **Save and run scan**. + - In the future, select **Save scan**. + - On a schedule: + + - Turn on the **Enable scan schedule** toggle. + - Complete the schedule fields. + - Select **Save scan**. + +The on-demand DAST scan runs as specified and the project's dashboard shows the results. + +### View details of an on-demand scan + +To view details of an on-demand scan: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > On-demand scans**. +1. Select the **Scan library** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. + +### Edit an on-demand scan + +To edit an on-demand scan: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > On-demand scans**. +1. Select the **Scan library** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. +1. Edit the saved scan's details. +1. Select **Save scan**. + +### Delete an on-demand scan + +To delete an on-demand scan: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > On-demand scans**. +1. Select the **Scan library** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. +1. On the confirmation dialog, select **Delete**. + +## Site profile + +> - Site profile features, scan method and file URL, were [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345837) in GitLab 15.6. +> - GraphQL endpoint path feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378692) in GitLab 15.7. + +A site profile defines the attributes and configuration details of the deployed application, +website, or API to be scanned by DAST. A site profile can be referenced in `.gitlab-ci.yml` and +on-demand scans. + +A site profile contains: + +- **Profile name**: A name you assign to the site to be scanned. While a site profile is referenced + in either `.gitlab-ci.yml` or an on-demand scan, it **cannot** be renamed. +- **Site type**: The type of target to be scanned, either website or API scan. +- **Target URL**: The URL that DAST runs against. +- **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. +- **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. +- **Authentication**: + - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. + - **Username**: The username used to authenticate to the website. + - **Password**: The password used to authenticate to the website. + - **Username form field**: The name of username field at the sign-in HTML form. + - **Password form field**: The name of password field at the sign-in HTML form. + - **Submit form field**: The `id` or `name` of the element that when selected submits the sign-in HTML form. + +- **Scan method**: A type of method to perform API testing. The supported methods are OpenAPI, Postman Collections, HTTP Archive (HAR), or GraphQL. + - **GraphQL endpoint path**: The path to the GraphQL endpoint. This path is concatenated with the target URL to provide the URI for the scan to test. The GraphQL endpoint must support introspection queries. + - **File URL**: The URL of the OpenAPI, Postman Collection, or HTTP Archive file. + +When an API site type is selected, a host override is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. + +When configured, request headers and password fields are encrypted using [`aes-256-gcm`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) before being stored in the database. +This data can only be read and decrypted with a valid secrets file. + +### Site profile validation + +> Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. + +Site profile validation reduces the risk of running an active scan against the wrong website. A site +must be validated before an active scan can run against it. Each of the site validation methods are +equivalent in functionality, so use whichever is most suitable: + +- **Text file validation**: Requires a text file be uploaded to the target site. The text file is + allocated a name and content that is unique to the project. The validation process checks the + file's content. +- **Header validation**: Requires the header `Gitlab-On-Demand-DAST` be added to the target site, + with a value unique to the project. The validation process checks that the header is present, and + checks its value. +- **Meta tag validation**: Requires the meta tag named `gitlab-dast-validation` be added to the + target site, with a value unique to the project. Make sure it's added to the `<head>` section of + the page. The validation process checks that the meta tag is present, and checks its value. + +### Create a site profile + +To create a site profile: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select **New > Site profile**. +1. Complete the fields then select **Save profile**. + +The site profile is saved, for use in an on-demand scan. + +### Edit a site profile + +NOTE: +If a site profile is linked to a security policy, you cannot edit the profile from this page. See +[Scan execution policies](../policies/scan-execution-policies.md) for more information. + +NOTE: +If a site profile's Target URL or Authenticated URL is updated, the request headers and password fields associated with that profile are cleared. + +When a validated site profile's file, header, or meta tag is edited, the site's +[validation status](#site-profile-validation) is revoked. + +To edit a site profile: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Site Profiles** tab. +1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. +1. Edit the fields then select **Save profile**. + +### Delete a site profile + +NOTE: +If a site profile is linked to a security policy, a user cannot delete the profile from this page. +See [Scan execution policies](../policies/scan-execution-policies.md) for more information. + +To delete a site profile: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Site Profiles** tab. +1. In the profile's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. +1. Select **Delete** to confirm the deletion. + +### Validate a site profile + +Validating a site is required to run an active scan. + +Prerequisites: + +- A runner must be available in the project to run a validation job. +- The GitLab server's certificate must be trusted and must not use a self-signed certificate. + +To validate a site profile: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Site Profiles** tab. +1. In the profile's row, select **Validate**. +1. Select the validation method. + 1. For **Text file validation**: + 1. Download the validation file listed in **Step 2**. + 1. Upload the validation file to the host, to the location in **Step 3** or any location you + prefer. + 1. If required, edit the file location in **Step 3**. + 1. Select **Validate**. + 1. For **Header validation**: + 1. Select the clipboard icon in **Step 2**. + 1. Edit the header of the site to validate, and paste the clipboard content. + 1. Select the input field in **Step 3** and enter the location of the header. + 1. Select **Validate**. + 1. For **Meta tag validation**: + 1. Select the clipboard icon in **Step 2**. + 1. Edit the content of the site to validate, and paste the clipboard content. + 1. Select the input field in **Step 3** and enter the location of the meta tag. + 1. Select **Validate**. + +The site is validated and an active scan can run against it. A site profile's validation status is +revoked only when it's revoked manually, or its file, header, or meta tag is edited. + +### Retry a failed validation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. +> - [Deployed behind the `dast_failed_site_validations` flag](../../../administration/feature_flags.md), enabled by default. +> - [Feature flag `dast_failed_site_validations` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323961) in GitLab 14.4. + +Failed site validation attempts are listed on the **Site profiles** tab of the **Manage profiles** +page. + +To retry a site profile's failed validation: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Site Profiles** tab. +1. In the profile's row, select **Retry validation**. + +### Revoke a site profile's validation status + +WARNING: +When a site profile's validation status is revoked, all site profiles that share the same URL also +have their validation status revoked. + +To revoke a site profile's validation status: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Beside the validated profile, select **Revoke validation**. + +The site profile's validation status is revoked. + +### Validated site profile headers + +The following are code samples of how you can provide the required site profile header in your +application. + +#### Ruby on Rails example for on-demand scan + +Here's how you can add a custom header in a Ruby on Rails application: + +```ruby +class DastWebsiteTargetController < ActionController::Base + def dast_website_target + response.headers['Gitlab-On-Demand-DAST'] = '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c' + head :ok + end +end +``` + +#### Django example for on-demand scan + +Here's how you can add a +[custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields): + +```python +class DastWebsiteTargetView(View): + def head(self, *args, **kwargs): + response = HttpResponse() + response['Gitlab-On-Demand-DAST'] = '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c' + + return response +``` + +#### Node (with Express) example for on-demand scan + +Here's how you can add a +[custom header in Node (with Express)](https://expressjs.com/en/5x/api.html#res.append): + +```javascript +app.get('/dast-website-target', function(req, res) { + res.append('Gitlab-On-Demand-DAST', '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c') + res.send('Respond to DAST ping') +}) +``` + +## Scanner profile + +> - Deprecated AJAX Spider option with the [introduction of Browser based on-demand DAST scans behind feature flag `dast_ods_browser_based_scanner`](https://gitlab.com/gitlab-org/gitlab/-/issues/430210). +> - Renamed spider timeout to crawl timeout with the [introduction of Browser based on-demand DAST scans behind feature flag `dast_ods_browser_based_scanner`](https://gitlab.com/gitlab-org/gitlab/-/issues/430210). + +A scanner profile defines the configuration details of a security scanner. A scanner profile can be +referenced in `.gitlab-ci.yml` and on-demand scans. + +A scanner profile contains: + +- **Profile name:** A name you give the scanner profile. For example, "Spider_15". While a scanner + profile is referenced in either `.gitlab-ci.yml` or an on-demand scan, it **cannot** be renamed. +- **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. +- **Crawl timeout:** The maximum number of minutes allowed for the crawler to traverse the site. +- **Target timeout:** The maximum number of seconds DAST waits for the site to be available before + starting the scan. +- **Debug messages:** Include debug messages in the DAST console output. + +### Create a scanner profile + +To create a scanner profile: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select **New > Scanner profile**. +1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). +1. Select **Save profile**. + +### Edit a scanner profile + +NOTE: +If a scanner profile is linked to a security policy, you cannot edit the profile from this page. +For more information, see [Scan execution policies](../policies/scan-execution-policies.md). + +To edit a scanner profile: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Scanner profiles** tab. +1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. +1. Edit the form. +1. Select **Save profile**. + +### Delete a scanner profile + +NOTE: +If a scanner profile is linked to a security policy, a user cannot delete the profile from this +page. For more information, see [Scan execution policies](../policies/scan-execution-policies.md). + +To delete a scanner profile: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Scanner profiles** tab. +1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. +1. Select **Delete**. + +## Auditing + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. + +The creation, updating, and deletion of DAST profiles, DAST scanner profiles, +and DAST site profiles are included in the [audit log](../../../administration/audit_events.md). diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 6127866b0a9..447babb0ad4 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -168,9 +168,9 @@ To configure DAST using the UI: 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 - scanner profile. For more details, see [scanner profiles](#scanner-profile). + scanner profile. For more details, see [scanner profiles](../dast/on-demand_scan.md#scanner-profile). 1. Select the desired **Site profile**, or select **Create site profile** and save a site - profile. For more details, see [site profiles](#site-profile). + profile. For more details, see [site profiles](../dast/on-demand_scan.md#site-profile). 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you selected. 1. Do one of the following: @@ -466,403 +466,6 @@ variables: The DAST job does not require the project's repository to be present when running, so by default [`GIT_STRATEGY`](../../../ci/runners/configure_runners.md#git-strategy) is set to `none`. -## On-demand scans - -> - Auditing for DAST profile management [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. -> - Scheduled on-demand DAST scans [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3 [with a flag](../../../administration/feature_flags.md) named `dast_on_demand_scans_scheduler`. Disabled by default. -> - Scheduled on-demand DAST scans [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. Feature flag `dast_on_demand_scans_scheduler` removed. -> - Runner tags selection [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111499) in GitLab 16.3. - -WARNING: -On-demand scans are not available when GitLab is running in FIPS mode. - -An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger -the scan. You must either start it manually, or schedule it to run. For on-demand DAST scans, -a [site profile](#site-profile) defines **what** is to be scanned, and a -[scanner profile](#scanner-profile) defines **how** the application is to be scanned. - -An on-demand scan can be run in active or passive mode: - -- **Passive mode**: The default mode, which runs a ZAP Baseline Scan. -- **Active mode**: Runs a ZAP Full Scan which is potentially harmful to the site being scanned. To - minimize the risk of accidental damage, running an active scan requires a - [validated site profile](#site-profile-validation). - -### View on-demand DAST scans - -To view on-demand scans: - -1. On the left sidebar, select **Search or go to** and find your project or group. -1. Select **Secure > On-demand scans**. - -On-demand scans are grouped by their status. The scan library contains all available on-demand -scans. - -### Run an on-demand DAST scan - -Prerequisites: - -- You must have permission to run an on-demand DAST scan against a protected branch. The default - branch is automatically protected. For more information, see - [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - -To run an existing on-demand scan: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > On-demand scans**. -1. Select the **Scan library** tab. -1. In the scan's row, select **Run scan**. - - If the branch saved in the scan no longer exists, you must: - - 1. [Edit the scan](#edit-an-on-demand-scan). - 1. Select a new branch. - 1. Save the edited scan. - -The on-demand DAST scan runs, and the project's dashboard shows the results. - -#### Create an on-demand scan - -Create an on-demand scan to: - -- Run it immediately. -- Save it to be run in the future. -- Schedule it to be run at a specified schedule. - -To create an on-demand DAST scan: - -1. On the left sidebar, select **Search or go to** and find your project or group. -1. Select **Secure > On-demand scans**. -1. Select **New scan**. -1. Complete the **Scan name** and **Description** fields. -1. In the **Branch** dropdown list, select the desired branch. -1. Optional. Select the runner tags. -1. Select **Select scanner profile** or **Change scanner profile** to open the drawer, and either: - - Select a scanner profile from the drawer, **or** - - Select **New profile**, create a [scanner profile](#scanner-profile), then select **Save profile**. -1. Select **Select site profile** or **Change site profile** to open the drawer, and either: - - Select a site profile from the **Site profile library** drawer, or - - Select **New profile**, create a [site profile](#site-profile), then select **Save profile**. -1. To run the on-demand scan: - - - Immediately, select **Save and run scan**. - - In the future, select **Save scan**. - - On a schedule: - - - Turn on the **Enable scan schedule** toggle. - - Complete the schedule fields. - - Select **Save scan**. - -The on-demand DAST scan runs as specified and the project's dashboard shows the results. - -### View details of an on-demand scan - -To view details of an on-demand scan: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > On-demand scans**. -1. Select the **Scan library** tab. -1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. - -### Edit an on-demand scan - -To edit an on-demand scan: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > On-demand scans**. -1. Select the **Scan library** tab. -1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -1. Edit the saved scan's details. -1. Select **Save scan**. - -### Delete an on-demand scan - -To delete an on-demand scan: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > On-demand scans**. -1. Select the **Scan library** tab. -1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. -1. On the confirmation dialog, select **Delete**. - -## Site profile - -> - Site profile features, scan method and file URL, were [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345837) in GitLab 15.6. -> - GraphQL endpoint path feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378692) in GitLab 15.7. - -A site profile defines the attributes and configuration details of the deployed application, -website, or API to be scanned by DAST. A site profile can be referenced in `.gitlab-ci.yml` and -on-demand scans. - -A site profile contains: - -- **Profile name**: A name you assign to the site to be scanned. While a site profile is referenced - in either `.gitlab-ci.yml` or an on-demand scan, it **cannot** be renamed. -- **Site type**: The type of target to be scanned, either website or API scan. -- **Target URL**: The URL that DAST runs against. -- **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. -- **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. -- **Authentication**: - - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. - - **Username**: The username used to authenticate to the website. - - **Password**: The password used to authenticate to the website. - - **Username form field**: The name of username field at the sign-in HTML form. - - **Password form field**: The name of password field at the sign-in HTML form. - - **Submit form field**: The `id` or `name` of the element that when selected submits the sign-in HTML form. - -- **Scan method**: A type of method to perform API testing. The supported methods are OpenAPI, Postman Collections, HTTP Archive (HAR), or GraphQL. - - **GraphQL endpoint path**: The path to the GraphQL endpoint. This path is concatenated with the target URL to provide the URI for the scan to test. The GraphQL endpoint must support introspection queries. - - **File URL**: The URL of the OpenAPI, Postman Collection, or HTTP Archive file. - -When an API site type is selected, a host override is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. - -When configured, request headers and password fields are encrypted using [`aes-256-gcm`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) before being stored in the database. -This data can only be read and decrypted with a valid secrets file. - -### Site profile validation - -> Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. - -Site profile validation reduces the risk of running an active scan against the wrong website. A site -must be validated before an active scan can run against it. Each of the site validation methods are -equivalent in functionality, so use whichever is most suitable: - -- **Text file validation**: Requires a text file be uploaded to the target site. The text file is - allocated a name and content that is unique to the project. The validation process checks the - file's content. -- **Header validation**: Requires the header `Gitlab-On-Demand-DAST` be added to the target site, - with a value unique to the project. The validation process checks that the header is present, and - checks its value. -- **Meta tag validation**: Requires the meta tag named `gitlab-dast-validation` be added to the - target site, with a value unique to the project. Make sure it's added to the `<head>` section of - the page. The validation process checks that the meta tag is present, and checks its value. - -### Create a site profile - -To create a site profile: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select **New > Site profile**. -1. Complete the fields then select **Save profile**. - -The site profile is saved, for use in an on-demand scan. - -### Edit a site profile - -NOTE: -If a site profile is linked to a security policy, you cannot edit the profile from this page. See -[Scan execution policies](../policies/scan-execution-policies.md) for more information. - -NOTE: -If a site profile's Target URL or Authenticated URL is updated, the request headers and password fields associated with that profile are cleared. - -When a validated site profile's file, header, or meta tag is edited, the site's -[validation status](#site-profile-validation) is revoked. - -To edit a site profile: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select the **Site Profiles** tab. -1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. -1. Edit the fields then select **Save profile**. - -### Delete a site profile - -NOTE: -If a site profile is linked to a security policy, a user cannot delete the profile from this page. -See [Scan execution policies](../policies/scan-execution-policies.md) for more information. - -To delete a site profile: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select the **Site Profiles** tab. -1. In the profile's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. -1. Select **Delete** to confirm the deletion. - -### Validate a site profile - -Validating a site is required to run an active scan. - -Prerequisites: - -- A runner must be available in the project to run a validation job. -- The GitLab server's certificate must be trusted and must not use a self-signed certificate. - -To validate a site profile: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select the **Site Profiles** tab. -1. In the profile's row, select **Validate**. -1. Select the validation method. - 1. For **Text file validation**: - 1. Download the validation file listed in **Step 2**. - 1. Upload the validation file to the host, to the location in **Step 3** or any location you - prefer. - 1. If required, edit the file location in **Step 3**. - 1. Select **Validate**. - 1. For **Header validation**: - 1. Select the clipboard icon in **Step 2**. - 1. Edit the header of the site to validate, and paste the clipboard content. - 1. Select the input field in **Step 3** and enter the location of the header. - 1. Select **Validate**. - 1. For **Meta tag validation**: - 1. Select the clipboard icon in **Step 2**. - 1. Edit the content of the site to validate, and paste the clipboard content. - 1. Select the input field in **Step 3** and enter the location of the meta tag. - 1. Select **Validate**. - -The site is validated and an active scan can run against it. A site profile's validation status is -revoked only when it's revoked manually, or its file, header, or meta tag is edited. - -### Retry a failed validation - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. -> - [Deployed behind the `dast_failed_site_validations` flag](../../../administration/feature_flags.md), enabled by default. -> - [Feature flag `dast_failed_site_validations` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323961) in GitLab 14.4. - -Failed site validation attempts are listed on the **Site profiles** tab of the **Manage profiles** -page. - -To retry a site profile's failed validation: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select the **Site Profiles** tab. -1. In the profile's row, select **Retry validation**. - -### Revoke a site profile's validation status - -WARNING: -When a site profile's validation status is revoked, all site profiles that share the same URL also -have their validation status revoked. - -To revoke a site profile's validation status: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Beside the validated profile, select **Revoke validation**. - -The site profile's validation status is revoked. - -### Validated site profile headers - -The following are code samples of how you can provide the required site profile header in your -application. - -#### Ruby on Rails example for on-demand scan - -Here's how you can add a custom header in a Ruby on Rails application: - -```ruby -class DastWebsiteTargetController < ActionController::Base - def dast_website_target - response.headers['Gitlab-On-Demand-DAST'] = '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c' - head :ok - end -end -``` - -#### Django example for on-demand scan - -Here's how you can add a -[custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields): - -```python -class DastWebsiteTargetView(View): - def head(self, *args, **kwargs): - response = HttpResponse() - response['Gitlab-On-Demand-DAST'] = '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c' - - return response -``` - -#### Node (with Express) example for on-demand scan - -Here's how you can add a -[custom header in Node (with Express)](https://expressjs.com/en/5x/api.html#res.append): - -```javascript -app.get('/dast-website-target', function(req, res) { - res.append('Gitlab-On-Demand-DAST', '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c') - res.send('Respond to DAST ping') -}) -``` - -## Scanner profile - -A scanner profile defines the configuration details of a security scanner. A scanner profile can be -referenced in `.gitlab-ci.yml` and on-demand scans. - -A scanner profile contains: - -- **Profile name:** A name you give the scanner profile. For example, "Spider_15". While a scanner - profile is referenced in either `.gitlab-ci.yml` or an on-demand scan, it **cannot** be renamed. -- **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. -- **Spider timeout:** The maximum number of minutes allowed for the spider to traverse the site. -- **Target timeout:** The maximum number of seconds DAST waits for the site to be available before - starting the scan. -- **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. -- **Debug messages:** Include debug messages in the DAST console output. - -### Create a scanner profile - -To create a scanner profile: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select **New > Scanner profile**. -1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). -1. Select **Save profile**. - -### Edit a scanner profile - -NOTE: -If a scanner profile is linked to a security policy, you cannot edit the profile from this page. -For more information, see [Scan execution policies](../policies/scan-execution-policies.md). - -To edit a scanner profile: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select the **Scanner profiles** tab. -1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. -1. Edit the form. -1. Select **Save profile**. - -### Delete a scanner profile - -NOTE: -If a scanner profile is linked to a security policy, a user cannot delete the profile from this -page. For more information, see [Scan execution policies](../policies/scan-execution-policies.md). - -To delete a scanner profile: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Security configuration**. -1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. -1. Select the **Scanner profiles** tab. -1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. -1. Select **Delete**. - -## Auditing - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. - -The creation, updating, and deletion of DAST profiles, DAST scanner profiles, -and DAST site profiles are included in the [audit log](../../../administration/audit_events.md). - ## Reports The DAST tool outputs a `gl-dast-report.json` report file containing details of the scan and its results. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index df8fbff720b..e69734403ea 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Perform Dynamic Application Security Testing (DAST) of web APIs to help discover bugs and potential security issues that other QA processes may miss. Use DAST API tests in addition to other [GitLab Secure](../index.md) security scanners and your own test processes. You can run DAST -API tests either as part your CI/CD workflow, [on-demand](../dast/proxy-based.md#on-demand-scans), or both. +API tests either as part your CI/CD workflow, [on-demand](../dast/on-demand_scan.md), or both. WARNING: Do not run DAST API testing against a production server. Not only can it perform _any_ function that @@ -417,15 +417,15 @@ The following is a summary of the variable scopes supported by the Postman Clien - **Global Environment (Global) scope** is a special pre-defined environment that is available throughout a workspace. We can also refer to the _global environment_ scope as the _global_ scope. The Postman Client allows exporting the global environment into a JSON file, which can be used with DAST API. - **Environment scope** is a named group of variables created by a user in the Postman Client. -The Postman Client supports a single active environment along with the global environment. The variables defined in an active user-created environment take precedence over variables defined in the global environment. The Postman Client allows exporting your environment into a JSON file, which can be used with DAST API. + The Postman Client supports a single active environment along with the global environment. The variables defined in an active user-created environment take precedence over variables defined in the global environment. The Postman Client allows exporting your environment into a JSON file, which can be used with DAST API. - **Collection scope** is a group of variables declared in a given collection. The collection variables are available to the collection where they have been declared and the nested requests or collections. Variables defined in the collection scope take precedence over the _global environment_ scope and also the _environment_ scope. -The Postman Client can export one or more collections into a JSON file, this JSON file contains selected collections, requests, and collection variables. + The Postman Client can export one or more collections into a JSON file, this JSON file contains selected collections, requests, and collection variables. - **DAST API Scope** is a new scope added by DAST API to allow users to provide extra variables, or override variables defined in other supported scopes. This scope is not supported by Postman. The _DAST API Scope_ variables are provided using a [custom JSON file format](#dast-api-scope-custom-json-file-format). - Override values defined in the environment or collection - Defining variables from scripts - Define a single row of data from the unsupported _data scope_ - **Data scope** is a group of variables in which their name and values come from JSON or CSV files. A Postman collection runner like [Newman](https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/) or [Postman Collection Runner](https://learning.postman.com/docs/running-collections/intro-to-collection-runs/) executes the requests in a collection as many times as entries have the JSON or CSV file. A good use case for these variables is to automate tests using scripts in Postman. -DAST API does **not** support reading data from a CSV or JSON file. + DAST API does **not** support reading data from a CSV or JSON file. - **Local scope** are variables that are defined in Postman scripts. DAST API does **not** support Postman scripts and by extension, variables defined in scripts. You can still provide values for the script-defined variables by defining them in one of the supported scopes, or our custom JSON format. Not all scopes are supported by DAST API and variables defined in scripts are not supported. The following table is sorted by broadest scope to narrowest scope. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 9d898ec0266..2570ce03005 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -69,11 +69,11 @@ WARNING: Dependency Scanning does not support runtime installation of compilers and interpreters. - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Dependency Scanning](https://www.youtube.com/watch?v=TBnfbGk4c4o) + For an overview, see [Dependency Scanning](https://www.youtube.com/watch?v=TBnfbGk4c4o) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an interactive reading and how-to demo of this Dependency Scanning documentation, see [How to use dependency scanning tutorial hands-on GitLab Application Security part 3](https://youtu.be/ii05cMbJ4xQ?feature=shared) + For an interactive reading and how-to demo of this Dependency Scanning documentation, see [How to use dependency scanning tutorial hands-on GitLab Application Security part 3](https://youtu.be/ii05cMbJ4xQ?feature=shared) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For other interactive reading and how-to demos, see [Get Started With GitLab Application Security Playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0KrUrjDoefSkgZLx5aJYFaF9) + For other interactive reading and how-to demos, see [Get Started With GitLab Application Security Playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0KrUrjDoefSkgZLx5aJYFaF9) ## Supported languages and package managers @@ -277,7 +277,10 @@ The following languages and dependency managers are supported: <li> <a id="notes-regarding-supported-languages-and-package-managers-7"></a> <p> - Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. + <ul> + <li>Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9.</li> + <li>Support for sbt 1.0.x was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/415835">deprecated in GitLab 16.8</a>.</li> + </ul> </p> </li> </ol> @@ -305,22 +308,22 @@ the project first. When a supported dependency file is detected, all dependencies, including transitive dependencies are analyzed. There is no limit to the depth of nested or transitive dependencies that are analyzed. -### Dependency analyzers +### Analyzers -Dependency Scanning supports the following official analyzers: +Dependency Scanning supports the following official +[Gemnasium-based](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) analyzers: - `gemnasium` - `gemnasium-maven` - `gemnasium-python` -Each of these supported Gemnasium-based Dependency Scanning analyzers exist in the following project: - -- [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) - -The analyzers are published as Docker images, which Dependency Scanning uses -to launch dedicated containers for each analysis. You can also integrate a custom +The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated +containers for each analysis. You can also integrate a custom [security scanner](../../../development/integrations/secure.md). +Each analyzer is updated as new versions of Gemnasium are released. For more information, see the +analyzer [Release Process documentation](../../../development/sec/analyzer_development_guide.md#versioning-and-release-process). + ### How analyzers obtain dependency information GitLab analyzers obtain dependency information using one of the following two methods: @@ -675,10 +678,6 @@ Support for additional languages, dependency managers, and dependency files are | ------------------- | --------- | --------------- | ---------- | ----- | | [Poetry](https://python-poetry.org/) | Python | `pyproject.toml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | [GitLab#32774](https://gitlab.com/gitlab-org/gitlab/-/issues/32774) | -## Contribute your scanner - -The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. - ## Configuration Enable the dependency scanning analyzer to ensure it scans your application's dependencies for known @@ -712,7 +711,10 @@ To enable dependency scanning: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipeline editor**. -1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file: +1. If no `.gitlab-ci.yml` file exists, select **Configure pipeline**, then delete the example + content. +1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file. If an `include` line + already exists, add only the `template` line below it. ```yaml include: @@ -721,14 +723,14 @@ To enable dependency scanning: 1. Select the **Validate** tab, then select **Validate pipeline**. - Continue if you see the message **Simulation completed successfully**. That indicates the file is - valid. + The message **Simulation completed successfully** confirms the file is valid. 1. Select the **Edit** tab. 1. Complete the fields. Do not use the default branch for the **Branch** field. -1. Select **Commit changes**. -1. Select **Code > Merge requests**. -1. Select the merge request just created. -1. Review the merge request, then select **Merge**. +1. Select the **Start a new merge request with these changes** checkbox, then select **Commit + changes**. +1. Complete the fields according to your standard workflow, then select **Create + merge request**. +1. Review and edit the merge request according to your standard workflow, then select **Merge**. Pipelines now include a dependency scanning job. @@ -804,10 +806,10 @@ The following variables allow configuration of global dependency scanning settin | CI/CD variables | Description | | ----------------------------|------------ | -| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | -| `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](#dependency-analyzers). | +| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certificates to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. For more details, see [Custom TLS certificate authority](#custom-tls-certificate-authority). | +| `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Analyzers](#analyzers). | | `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), 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. (Introduced in GitLab 14.10. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796`). Automatically set to `"-fips"` when FIPS mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) | +| `DS_IMAGE_SUFFIX` | Suffix added to the image name. (GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796`). Automatically set to `"-fips"` when FIPS mode is enabled. | | `DS_MAX_DEPTH` | Defines how many directory levels deep that the analyzer should search for supported files to scan. A value of `-1` scans all directories regardless of depth. Default: `2`. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). | @@ -816,29 +818,29 @@ The following variables allow configuration of global dependency scanning settin The following variables configure the behavior of specific dependency scanning analyzers. | CI/CD variable | Analyzer | Default | Description | -|--------------------------------------| ------------------ | ---------------------------- |------------ | +|--------------------------------------|--------------------|------------------------------|-------------| | `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. | -| `GEMNASIUM_DB_UPDATE_DISABLED` | `gemnasium` | `"false"` | Disable automatic updates for the `gemnasium-db` advisory database (For usage see: [examples](#hosting-a-copy-of-the-gemnasium_db-advisory-database))| +| `GEMNASIUM_DB_UPDATE_DISABLED` | `gemnasium` | `"false"` | Disable automatic updates for the `gemnasium-db` advisory database. For usage see [Hosting a copy of the Gemnasium advisory database](#hosting-a-copy-of-the-gemnasium_db-advisory-database). | | `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"`, `"false"` in FIPS mode | Enable automatic remediation of vulnerable dependencies. Not supported in FIPS mode. | -| `DS_REMEDIATE_TIMEOUT` | `gemnasium` | `5m` | Timeout for auto-remediation. | +| `DS_REMEDIATE_TIMEOUT` | `gemnasium` | `5m` | Timeout for auto-remediation. | | `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries. For now, `gemnasium` leverages [`Retire.js`](https://github.com/RetireJS/retire.js) to do this job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350512) in GitLab 14.8. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`, `21` | +| `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only projects using Composer, npm, pnpm, Pipenv or Poetry are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. | +| `GOOS` | `gemnasium` | `"linux"` | The operating system for which to compile Go code. | +| `GOARCH` | `gemnasium` | `"amd64"` | The architecture of the processor for which to compile Go code. | +| `GOFLAGS` | `gemnasium` | | The flags passed to the `go build` tool. | +| `GOPRIVATE` | `gemnasium` | | A list of glob patterns and prefixes to be fetched from source. For more information, see the Go private modules [documentation](https://go.dev/ref/mod#private-modules). | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`, `21`. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | | `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. | | `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. **Warning:** Read [the following security consideration](#python-projects) when using this environment variable. | -| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | +| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. This is a filename and not a path. When this environment variable is set only the specified file is scanned. | | `PIPENV_PYPI_MIRROR` | `gemnasium-python` | | If set, overrides the PyPi index used by Pipenv with a [mirror](https://github.com/pypa/pipenv/blob/v2022.1.8/pipenv/environments.py#L263). | -| `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | -| `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | -| `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only Composer, NPM, and Poetry projects are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. | -| `GOOS` | `gemnasium` | `"linux"` | The operating system for which to compile Go code. | -| `GOARCH` | `gemnasium` | `"amd64"` | The architecture of the processor for which to compile Go code. | -| `GOFLAGS` | `gemnasium` | | The flags passed to the `go build` tool. | -| `GOPRIVATE` | `gemnasium` | | A list of glob patterns and prefixes to be fetched from source. Read the Go private modules [documentation](https://go.dev/ref/mod#private-modules) for more information. | +| `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. | +| `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. | #### Other variables @@ -869,9 +871,26 @@ If one does not work and you need it we suggest [submitting a feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed&issue[title]=Docs%20feedback%20-%20feature%20proposal:%20Write%20your%20title) or [contributing to the code](../../../development/index.md) to enable it to be used. -### Using a custom SSL CA certificate authority +### Custom TLS certificate authority -You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: +Dependency Scanning allows for use of custom TLS certificates for SSL/TLS connections instead of the +default shipped with the analyzer container image. + +Support for custom certificate authorities was introduced in the following versions. + +| Analyzer | Version | +|--------------------|--------------------------------------------------------------------------------------------------------| +| `gemnasium` | [v2.8.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/releases/v2.8.0) | +| `gemnasium-maven` | [v2.9.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/releases/v2.9.0) | +| `gemnasium-python` | [v2.7.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/releases/v2.7.0) | + +#### Using a custom TLS certificate authority + +To use a custom TLS certificate authority, assign the +[text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1) +to the CI/CD variable `ADDITIONAL_CA_CERT_BUNDLE`. + +For example, to configure the certificate in the `.gitlab-ci.yml` file: ```yaml variables: @@ -883,8 +902,6 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. - ### Using private Maven repositories If your private Maven repository requires login credentials, @@ -892,144 +909,50 @@ 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 +### FIPS-enabled images -> Introduced in GitLab 14.10. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796` +> - Introduced in GitLab 14.10. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796` +> - Introduced in GitLab 15.0 - Gemnasium uses FIPS-enabled images when FIPS mode is enabled. 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. +versions of the Gemnasium images. When FIPS mode is enabled in the GitLab instance, Gemnasium +scanning jobs automatically use the FIPS-enabled images. To manually switch to FIPS-enabled images, +set the variable `DS_IMAGE_SUFFIX` to `"-fips"`. -Gemnasium scanning jobs automatically use FIPS-enabled image when FIPS mode is enabled in the GitLab instance. -([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) +Dependency scanning for Gradle projects and auto-remediation for Yarn projects are not supported in FIPS mode. -To manually switch to FIPS-enabled images, set the variable `DS_IMAGE_SUFFIX` to `"-fips"`. +## Output -Dependency scanning for Gradle projects and auto-remediation for Yarn projects are not supported in FIPS mode. +Dependency Scanning produces the following output: -## Reports JSON format +- **Dependency scanning report**: Contains details of all vulnerabilities detected in dependencies. +- **CycloneDX Software Bill of Materials**: Software Bill of Materials (SBOM) for each supported + lock or build file detected. -The dependency scanning tool emits a JSON report file. For more information, see the -[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json). +### Dependency scanning report -Here's an example dependency scanning report: +Dependency scanning outputs a report containing details of all vulnerabilities. The report is +processed internally and the results are shown in the UI. The report is also output as an artifact +of the dependency scanning job, named `gl-dependency-scanning-report.json`. -```json -{ - "version": "2.0", - "vulnerabilities": [ - { - "id": "51e83874-0ff6-4677-a4c5-249060554eae", - "category": "dependency_scanning", - "name": "Regular Expression Denial of Service", - "message": "Regular Expression Denial of Service in debug", - "description": "The debug module is vulnerable to regular expression denial of service when untrusted user input is passed into the `o` formatter. It takes around 50k characters to block for 2 seconds making this a low severity issue.", - "severity": "Unknown", - "solution": "Upgrade to latest versions.", - "scanner": { - "id": "gemnasium", - "name": "Gemnasium" - }, - "location": { - "file": "yarn.lock", - "dependency": { - "package": { - "name": "debug" - }, - "version": "1.0.5" - } - }, - "identifiers": [ - { - "type": "gemnasium", - "name": "Gemnasium-37283ed4-0380-40d7-ada7-2d994afcc62a", - "value": "37283ed4-0380-40d7-ada7-2d994afcc62a", - "url": "https://deps.sec.gitlab.com/packages/npm/debug/versions/1.0.5/advisories" - } - ], - "links": [ - { - "url": "https://nodesecurity.io/advisories/534" - }, - { - "url": "https://github.com/visionmedia/debug/issues/501" - }, - { - "url": "https://github.com/visionmedia/debug/pull/504" - } - ] - }, - { - "id": "5d681b13-e8fa-4668-957e-8d88f932ddc7", - "category": "dependency_scanning", - "name": "Authentication bypass via incorrect DOM traversal and canonicalization", - "message": "Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js", - "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment, therefore, has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.", - "severity": "Unknown", - "solution": "Upgrade to fixed version.\r\n", - "scanner": { - "id": "gemnasium", - "name": "Gemnasium" - }, - "location": { - "file": "yarn.lock", - "dependency": { - "package": { - "name": "saml2-js" - }, - "version": "1.5.0" - } - }, - "identifiers": [ - { - "type": "gemnasium", - "name": "Gemnasium-9952e574-7b5b-46fa-a270-aeb694198a98", - "value": "9952e574-7b5b-46fa-a270-aeb694198a98", - "url": "https://deps.sec.gitlab.com/packages/npm/saml2-js/versions/1.5.0/advisories" - }, - { - "type": "cve", - "name": "CVE-2017-11429", - "value": "CVE-2017-11429", - "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-11429" - } - ], - "links": [ - { - "url": "https://github.com/Clever/saml2/commit/3546cb61fd541f219abda364c5b919633609ef3d#diff-af730f9f738de1c9ad87596df3f6de84R279" - }, - { - "url": "https://github.com/Clever/saml2/issues/127" - }, - { - "url": "https://www.kb.cert.org/vuls/id/475445" - } - ] - } - ], - "remediations": [ - { - "fixes": [ - { - "id": "5d681b13-e8fa-4668-957e-8d88f932ddc7", - } - ], - "summary": "Upgrade saml2-js", - "diff": "ZGlmZiAtLWdpdCBhL...OR0d1ZUc2THh3UT09Cg==" // some content is omitted for brevity - } - ] -} -``` +For more details of the dependency scanning report, see: + +- [Example dependency scanning report](#example-vulnerability-report). +- [Dependency scanning report schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json). ### CycloneDX Software Bill of Materials > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/experiment-beta-support.md#beta). > - Generally available in GitLab 15.7. -In addition to the [JSON report file](#reports-json-format), the [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) -Dependency Scanning tool outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) for -each supported lock or build file it detects. These CycloneDX SBOMs are named -`gl-sbom-<package-type>-<package-manager>.cdx.json`, and are saved in the same directory -as the detected lock or build files. +Dependency Scanning outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) +for each supported lock or build file it detects. + +The CycloneDX SBOMs are: + +- Named `gl-sbom-<package-type>-<package-manager>.cdx.json`. +- Available as job artifacts of the dependency scanning job. +- Saved in the same directory as the detected lock or build files. For example, if your project has the following structure: @@ -1063,12 +986,16 @@ Then the Gemnasium scanner generates the following CycloneDX SBOMs: └── gl-sbom-go-go.cdx.json ``` -You can download CycloneDX SBOMs [the same way as other job artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts). +#### Merging multiple CycloneDX SBOMs -### Merging multiple CycloneDX SBOMs +You can use a CI/CD job to merge the multiple CycloneDX SBOMs into a single SBOM. GitLab uses +[CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store) to store +implementation-specific details in the metadata of each CycloneDX SBOM, such as the location of +build and lock files. If multiple CycloneDX SBOMs are merged together, this information is removed +from the resulting merged file. -You can use a CI/CD job to merge multiple CycloneDX SBOMs into a single SBOM. -For example: +For example, the following `.gitlab-ci.yml` extract demonstrates how the Cyclone SBOM files can be +merged, and the resulting file validated. ```yaml stages: @@ -1110,15 +1037,6 @@ merge cyclonedx sboms: - gl-sbom-all.cdx.json ``` -GitLab uses [CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store) -to store implementation-specific details in the metadata of each CycloneDX SBOM, -such as the location of build and lock files. If multiple CycloneDX SBOMs are merged together, -this information is removed from the resulting merged file. - -## Versioning and release process - -Check the [Release Process documentation](../../../development/sec/analyzer_development_guide.md#versioning-and-release-process). - ## Contributing to the vulnerability database To find a vulnerability, you can search the [`GitLab Advisory Database`](https://advisories.gitlab.com/). @@ -1170,16 +1088,6 @@ For details on saving and transporting Docker images as a file, see the Docker d [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -#### Support for Custom Certificate Authorities - -Support for custom certificate authorities was introduced in the following versions. - -| Analyzer | Version | -| -------- | ------- | -| `gemnasium` | [v2.8.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/releases/v2.8.0) | -| `gemnasium-maven` | [v2.9.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/releases/v2.9.0) | -| `gemnasium-python` | [v2.7.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/releases/v2.7.0) | - ### Set dependency scanning CI/CD job variables to use local dependency scanning analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of @@ -1332,3 +1240,114 @@ environment variable due to a possible exploit documented by [CVE-2018-20225](ht intended to obtain a private package from a private index. This only affects use of the `PIP_EXTRA_INDEX_URL` option, and exploitation requires that the package does not already exist in the public index (and thus the attacker can put the package there with an arbitrary version number). + +## Example vulnerability report + +The following is an example vulnerability report output by dependency scanning: + +```json +{ + "version": "2.0", + "vulnerabilities": [ + { + "id": "51e83874-0ff6-4677-a4c5-249060554eae", + "category": "dependency_scanning", + "name": "Regular Expression Denial of Service", + "message": "Regular Expression Denial of Service in debug", + "description": "The debug module is vulnerable to regular expression denial of service when untrusted user input is passed into the `o` formatter. It takes around 50k characters to block for 2 seconds making this a low severity issue.", + "severity": "Unknown", + "solution": "Upgrade to latest versions.", + "scanner": { + "id": "gemnasium", + "name": "Gemnasium" + }, + "location": { + "file": "yarn.lock", + "dependency": { + "package": { + "name": "debug" + }, + "version": "1.0.5" + } + }, + "identifiers": [ + { + "type": "gemnasium", + "name": "Gemnasium-37283ed4-0380-40d7-ada7-2d994afcc62a", + "value": "37283ed4-0380-40d7-ada7-2d994afcc62a", + "url": "https://deps.sec.gitlab.com/packages/npm/debug/versions/1.0.5/advisories" + } + ], + "links": [ + { + "url": "https://nodesecurity.io/advisories/534" + }, + { + "url": "https://github.com/visionmedia/debug/issues/501" + }, + { + "url": "https://github.com/visionmedia/debug/pull/504" + } + ] + }, + { + "id": "5d681b13-e8fa-4668-957e-8d88f932ddc7", + "category": "dependency_scanning", + "name": "Authentication bypass via incorrect DOM traversal and canonicalization", + "message": "Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js", + "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment, therefore, has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.", + "severity": "Unknown", + "solution": "Upgrade to fixed version.\r\n", + "scanner": { + "id": "gemnasium", + "name": "Gemnasium" + }, + "location": { + "file": "yarn.lock", + "dependency": { + "package": { + "name": "saml2-js" + }, + "version": "1.5.0" + } + }, + "identifiers": [ + { + "type": "gemnasium", + "name": "Gemnasium-9952e574-7b5b-46fa-a270-aeb694198a98", + "value": "9952e574-7b5b-46fa-a270-aeb694198a98", + "url": "https://deps.sec.gitlab.com/packages/npm/saml2-js/versions/1.5.0/advisories" + }, + { + "type": "cve", + "name": "CVE-2017-11429", + "value": "CVE-2017-11429", + "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-11429" + } + ], + "links": [ + { + "url": "https://github.com/Clever/saml2/commit/3546cb61fd541f219abda364c5b919633609ef3d#diff-af730f9f738de1c9ad87596df3f6de84R279" + }, + { + "url": "https://github.com/Clever/saml2/issues/127" + }, + { + "url": "https://www.kb.cert.org/vuls/id/475445" + } + ] + } + ], + "remediations": [ + { + "fixes": [ + { + "id": "5d681b13-e8fa-4668-957e-8d88f932ddc7", + } + ], + "summary": "Upgrade saml2-js", + "diff": "ZGlmZiAtLWdpdCBhL...OR0d1ZUc2THh3UT09Cg==" // some content is omitted for brevity + } + ] +} +``` diff --git a/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md index 77579a04c7e..83004459051 100644 --- a/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md +++ b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md @@ -65,10 +65,6 @@ Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). -## Getting warning message `gl-dependency-scanning-report.json: no matching files` - -For information, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). - ## Limitation when using rules:exists The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) @@ -129,7 +125,7 @@ The lock file is cached during the build phase and passed to the dependency scan scan occurs. Because the cache is downloaded before the analyzer run occurs, the existence of a lock file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. -To prevent this warning, lock files should be committed. +To prevent this warning, lock files should be committed. ## You no longer get the latest Docker image after setting `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index e31877d195a..6441f74a41b 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -247,10 +247,8 @@ Security scan information appears in multiple locations and formats: ### Merge request **(FREE ALL)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. -> - Report download dropdown list [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249550) in GitLab 13.9. +Output of all enabled application security tools is shown in a merge request widget. You can use +this information to manage the risk of any issues identified in the source branch. #### All tiers @@ -284,17 +282,25 @@ The merge request security widget displays only a subset of the vulnerabilities From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. -For each security report type, the widget displays the first 25 added and 25 fixed findings, sorted by severity. To see all -findings, select **View full report** to go directly to the **Security** tab in the latest branch pipeline. +For each security report type, the widget displays the first 25 added and 25 fixed findings, sorted by severity. +This is determined by comparing the security reports from the source branch and target branch pipelines. + +As an example, consider two pipelines with these scan results: + +- The source branch pipeline detects two vulnerabilities identified as `V1` and `V2`. +- The target branch pipeline detects two vulnerabilities identified as `V1` and `V3`. +- `V2` will show on the merge request widget as "added". +- `V3` will show on the merge request widget as "fixed". +- `V1` exists on both branches and is not shown on the merge request widget. + +To see all findings on the source branch of the merge request, select **View full report** to go directly to the **Security** tab in the latest source branch pipeline.  ### Pipeline security tab -A pipeline's security tab lists all findings in the current branch. It includes findings introduced -by this branch and vulnerabilities already present in the base branch. These results likely do not -match the findings displayed in the Merge Request security widget, as those do not include the -existing vulnerabilities. For more information see +A pipeline's security tab lists all findings from the security reports in the pipeline's +job artifacts. For more information see [Vulnerabilities in a pipeline](vulnerability_report/pipeline.md). ### Security dashboard diff --git a/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png b/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png Binary files differindex d2f5466e383..ac3164842a4 100644 --- a/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png +++ b/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index f299a38dff1..9a6f7581876 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -46,6 +46,10 @@ to remove the `test` stage, jobs will run in the `scan-policies` stage instead. - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a video walkthrough, see [How to set up Security Scan Policies in GitLab](https://youtu.be/ZBcqGmEwORA?si=aeT4EXtmHjosgjBY). - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Enforcing scan execution policies on projects with no GitLab CI/CD configuration](https://www.youtube.com/watch?v=sUfwQQ4-qHs). +## Requirements and limitations + +- The maximum number of scan execution policies is five per security policy project. + ## Scan execution policy editor NOTE: @@ -201,27 +205,22 @@ The keys for a schedule rule are: ## `scan` action type -> - Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. -> - The `custom` scan action type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126457) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. On GitLab.com, this feature is not available. On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. +> Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. [Feature flag removed in GitLab 16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/435727). This action executes the selected `scan` with additional parameters when conditions for at least one rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning`, `custom` | The action's type. | -| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/proxy-based.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | -| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/proxy-based.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| +| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning` | The action's type. | +| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/on-demand_scan.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | +| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/on-demand_scan.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| | `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | | `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs are run by runner with the specified tags. | -| `ci_configuration` <sup>1</sup> | `string` | | GitLab CI YAML as formatted as string. | -| `ci_configuration_path` <sup>1</sup> | object | Object with project path and file name pointing to a CI configuration. | - -1. For `custom` scans, you must specify one of `ci_configuration` or `ci_configuration_path`. Note the following: -- You must create the [site profile](../dast/proxy-based.md#site-profile) and [scanner profile](../dast/proxy-based.md#scanner-profile) +- You must create the [site profile](../dast/on-demand_scan.md#site-profile) and [scanner profile](../dast/on-demand_scan.md#scanner-profile) with selected names for each project that is assigned to the selected Security Policy Project. Otherwise, the policy is not applied and a job with an error message is created instead. - Once you associate the site profile and scanner profile by name in the policy, it is not possible @@ -237,16 +236,6 @@ Note the following: - A container scanning scan that is configured for the `pipeline` rule type ignores the agent defined in the `agents` object. The `agents` object is only considered for `schedule` rule types. An agent with a name provided in the `agents` object must be created and configured for the project. - Variables defined in a Scan Execution Policy follow the standard [CI/CD variable precedence](../../../ci/variables/index.md#cicd-variable-precedence). -- `custom` scans are be executed for scheduled rules. -- Jobs variables and stages definitions from `custom` scans take precedence over the project's CI/CD configuration. - -### `ci_configuration_path` object - -| Field | Type | Description | -|-------|------|-------------| -| `project` | `string` | A project namespace path. | -| `file` | `string` | The filename of the CI/CD YAML file. | -| `ref` | `string` (optional) | The branch name, tag name, or commit SHA. | ## Example security policies project @@ -267,12 +256,6 @@ scan_execution_policy: - scan: dast scanner_profile: Scanner Profile A site_profile: Site Profile B - - scan: custom - ci_configuration: |- - test job: - stage: test - script: - - echo "Hello World" - name: Enforce DAST and secret detection scans every 10 minutes description: This policy enforces DAST and secret detection scans to run every 10 minutes enabled: true @@ -306,7 +289,6 @@ In this example: - For every pipeline executed on branches that match the `release/*` wildcard (for example, branch `release/v1.2.1`) - DAST scans run with `Scanner Profile A` and `Site Profile B`. - - A `test job` is injected into the `test` stage of the pipeline, printing `Hello World`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. - Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` @@ -340,3 +322,155 @@ this case, two SAST jobs run in the pipeline, one with the developer's variables If you want to avoid running duplicate scans, you can either remove the scans from the project's `.gitlab-ci.yml` file or disable your local jobs by setting `SAST_DISABLED: "true"`. Disabling jobs this way does not prevent the security jobs defined by scan execution policies from running. + +## Experimental features **(EXPERIMENT)** + +These experimental features have limitations: + +1. Enforcing pipeline execution using the pipeline execution action in projects + without a `.gitlab-ci.yml` is not supported. +1. The pipeline execution action cannot be used with a scheduled trigger type. + +### Pipeline execution policy action + +> The `custom` scan action type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126457) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. + +FLAG: +On self-managed GitLab, by default this feature is available. +To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. +On GitLab.com, this feature is available. + +The pipeline execution policy action introduces a new scan action type into +scan execution policies for creating and enforcing custom CI in your target +development projects. + +This custom scan type uses a remote CI configuration file to define the custom +CI you want enforced. Scan execution policies then merge this file with the +project's `.gitlab-ci.yml` to execute the compliance jobs for each project +enforced by the policy. + +#### `ci_configuration_path` object + +| Field | Type | Required | Description | +|-----------|---------------------|----------|-------------| +| `project` | `string` | true | A project namespace path. | +| `file` | `string` | true | The file name of the CI/CD YAML file. | +| `ref` | `string` | false | The branch name, tag name, or commit SHA. If not specified, uses the default branch. | + +#### `scan` action type + +This action executes the selected `scan` with additional parameters when +conditions for at least one rule in the defined policy are met. + +| Field | Type | Possible values | Description | +|-------------------------|----------|-----------------|-------------| +| `scan` | `string` | `custom` | The action's type. | +| `ci_configuration` | `string` | | GitLab CI YAML as formatted as string. | +| `ci_configuration_path` | object | | Object with project path and file name pointing to a CI configuration. | + +Note the following: + +- For `custom` scans, you must specify one of `ci_configuration` or `ci_configuration_path`. +- `custom` scans are being executed for triggered rules only. +- Jobs variables and stages definitions from `custom` scans take precedence over the project's CI/CD configuration. + +#### Example 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 +--- +scan_execution_policy: +- name: Create a custom scan that injects test job + description: This policy enforces pipeline configuration to have a job with DAST scan for release branches + enabled: true + rules: + - type: pipeline + branches: + - release/* + actions: + - scan: custom + ci_configuration: |- + test job: + stage: test + script: + - echo "Hello World" +``` + +In this example a `test job` is injected into the `test` stage of the pipeline, printing `Hello World`. + +### Security policy scopes + +> The `policy_scope` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135398) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_policy_scope`. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +an administrator can [disable the feature flag](../../../administration/feature_flags.md) +named `security_policies_policy_scope`. +On GitLab.com, this feature is available. + +Security policy enforcement depends first on establishing a link between the group, subgroup, or +project on which you want to enforce policies, and the security policy project that contains the +policies. For example, if you are linking policies to a group, a group owner must create the link to +the security policy project. Then, all policies in the security policy project are inherited by all +projects in the group. + +You can refine a security policy's scope to: + +- _Include_ only projects containing a compliance framework label. +- _Include_ or _exclude_ selected projects from enforcement. + +#### Policy scope schema + +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `policy_scope` | `object` | false | `compliance_frameworks`, `projects` | Scopes the policy based on compliance framework labels or projects you define. | + +#### `policy_scope` scope type + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `compliance_frameworks` | `object` | `ids` | List of IDs of the compliance frameworks in scope of enforcement, in an `ids` array. | +| `projects` | `object` | `including`, `excluding` | Use `excluding:` or `including:` then list the IDs of the projects you wish to include or exclude, in an `ids` array. | + +#### Example `policy.yml` with security policy scopes + +```yaml +--- +scan_execution_policy: +- name: Enforce DAST in every release pipeline + description: This policy enforces pipeline configuration to have a job with DAST scan for release branches + enabled: true + rules: + - type: pipeline + branches: + - release/* + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B + policy_scope: + compliance_frameworks: + ids: + - 2 + - 11 +- name: Enforce Secret Detection and Container Scanning in every default branch pipeline + description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch + enabled: true + rules: + - type: pipeline + branches: + - main + actions: + - scan: secret_detection + - scan: sast + variables: + SAST_EXCLUDED_ANALYZERS: brakeman + policy_scope: + projects: + excluding: + ids: + - 24 + - 27 +``` diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 0fadd761fe4..e2ec6b8ae56 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -31,7 +31,7 @@ The following video gives you an overview of GitLab scan result policies: - You must add the respective [security scanning tools](../index.md#application-coverage). Otherwise, scan result policies do not have any effect. -- The maximum number of policies is five. +- The maximum number of scan result policies is five per security policy project. - Each policy can have a maximum of five rules. - All configured scanners must be present in the merge request's latest pipeline. If not, approvals are required even if some vulnerability criteria have not been met. - Scan result policies evaluate findings and determine approval requirements based on the job artifact reports published in a completed pipeline. However, scan result policies do not check the integrity or authenticity of the scan results generated in the artifact reports. @@ -45,10 +45,10 @@ A project can have multiple pipeline types configured. A single commit can initi pipelines, each of which may contain a security scan. - In GitLab 16.3 and later, the results of all completed pipelines for the latest commit in -the merge request's source and target branch are evaluated and used to enforce the scan result policy. -Parent-child pipelines and on-demand DAST pipelines are not considered. + the merge request's source and target branch are evaluated and used to enforce the scan result policy. + Parent-child pipelines and on-demand DAST pipelines are not considered. - In GitLab 16.2 and earlier, only the results of the latest completed pipeline were evaluated -when enforcing scan result policies. + when enforcing scan result policies. ## Scan result policy editor @@ -92,9 +92,6 @@ the following sections and tables provide an alternative. > The `approval_settings` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. -FLAG: -On self-managed GitLab, by default the `approval_settings` field is available. To hide the feature, an administrator can [disable the feature flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request` and `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. On GitLab.com, the `approval_settings` field is available. - | Field | Type | Required | Possible values | Description | |---------------------|--------------------|----------|-----------------|----------------------------------------------------------| | `name` | `string` | true | | Name of the policy. Maximum of 255 characters. | @@ -121,7 +118,7 @@ This rule enforces the defined actions based on security scan findings. | `scanners` | `array` of `string` | true | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. `sast` includes results from both SAST and SAST IaC scanners. | | `vulnerabilities_allowed` | `integer` | true | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | true | `info`, `unknown`, `low`, `medium`, `high`, `critical` | The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | true | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed`, `new_needs_triage`, `new_dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline and necessary security scans are complete. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br> The `new_needs_triage` option considers the status<br><br> • Detected<br><br> The `new_dismissed` option considers the status<br><br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | +| `vulnerability_states` | `array` of `string` | true | `[]` or `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed`, `new_needs_triage`, `new_dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline and necessary security scans are complete. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br> The `new_needs_triage` option considers the status<br><br> • Detected<br><br> The `new_dismissed` option considers the status<br><br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. <br><br>An empty array, `[]`, covers the same statuses as `newly_detected`. It is equivalent to specifying `['new_needs_triage', 'new_dismissed']`. | | `vulnerability_attributes` | `object` | false | `{false_positive: boolean, fix_available: boolean}` | All vulnerability findings are considered by default. But filters can be applied for attributes to consider only vulnerability findings: <br><br> • With a fix available (`fix_available: true`)<br><br> • With no fix available (`fix_available: false`)<br> • That are false positive (`false_positive: true`)<br> • That are not false positive (`false_positive: false`)<br> • Or a combination of both. For example (`fix_available: true, false_positive: false`) | | `vulnerability_age` | `object` | false | N/A | Filter pre-existing vulnerability findings by age. A vulnerability's age is calculated as the time since it was detected in the project. The criteria are `operator`, `value`, and `interval`.<br>- The `operator` criterion specifies if the age comparison used is older than (`greater_than`) or younger than (`less_than`).<br>- The `value` criterion specifies the numeric value representing the vulnerability's age.<br>- The `interval` criterion specifies the unit of measure of the vulnerability's age: `day`, `week`, `month`, or `year`.<br><br>Example: `operator: greater_than`, `value: 30`, `interval: day`. | @@ -179,6 +176,7 @@ the defined policy. ## `approval_settings` +> - The `block_group_branch_modification` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420724) in GitLab 16.8 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_block_group_branch_modification`. Disabled by default. > - The `block_unprotecting_branches` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423101) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. Disabled by default. > - The `scan_result_policy_settings` feature flag was replaced by the `scan_result_policies_block_unprotecting_branches` feature flag in 16.4. > - The `block_unprotecting_branches` field was [replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137153) by `block_branch_modification` field in GitLab 16.7. @@ -187,25 +185,26 @@ the defined policy. > - The `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. Disabled by default. > - The above fields were [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.6. > - The above fields were [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.7. +> - Feature flag `scan_result_any_merge_request` [was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/432127) in GitLab 16.8. > - The `prevent_pushing_and_force_pushing` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420629) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. Disabled by default. > - The above field was [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.6. > - The above field was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.7. FLAG: On self-managed GitLab, by default the `block_branch_modification` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`. On GitLab.com, this feature is available. -On self-managed GitLab, by default the `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields are available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. On GitLab.com, this feature is available. On self-managed GitLab, by default the `prevent_pushing_and_force_pushing` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. On GitLab.com, this feature is available. The settings set in the policy overwrite settings in the project. -| Field | Type | Required | Possible values | Applicable rule type | Description | -|-------------------------------------|-----------|----------|-----------------|----------------------|-------------| -| `block_branch_modification` | `boolean` | false | `true`, `false` | All | When enabled, prevents a user from removing a branch from the protected branches list, deleting a protected branch, or changing the default branch if that branch is included in the security policy. This ensures users cannot remove protection status from a branch to merge vulnerable code. | -| `prevent_approval_by_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, merge request authors cannot approve their own MRs. This ensures code authors cannot introduce vulnerabilities and approve code to merge. | -| `prevent_approval_by_commit_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, users who have contributed code to the MR are ineligible for approval. This ensures code committers cannot introduce vulnerabilities and approve code to merge. | -| `remove_approvals_with_new_commit` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, if an MR receives all necessary approvals to merge, but then a new commit is added, new approvals are required. This ensures new commits that may include vulnerabilities cannot be introduced. | -| `require_password_to_approve` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, there will be password confirmation on approvals. Password confirmation adds an extra layer of security. | -| `prevent_pushing_and_force_pushing` | `boolean` | false | `true`, `false` | All | When enabled, prevents users from pushing and force pushing to a protected branch if that branch is included in the security policy. This ensures users do not bypass the merge request process to add vulnerable code to a branch. | +| Field | Type | Required | Possible values | Applicable rule type | Description | +|-------------------------------------|-----------------------|----------|---------------------------------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `block_branch_modification` | `boolean` | false | `true`, `false` | All | When enabled, prevents a user from removing a branch from the protected branches list, deleting a protected branch, or changing the default branch if that branch is included in the security policy. This ensures users cannot remove protection status from a branch to merge vulnerable code. | +| `block_group_branch_modification` | `boolean` or `object` | false | `true`, `false`, `{ enabled: boolean, exceptions: [string] }` | All | When enabled, prevents a user from removing group-level protected branches on every group the policy applies to. If `block_branch_modification` is `true`, implicitly defaults to `true`. | +| `prevent_approval_by_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, merge request authors cannot approve their own MRs. This ensures code authors cannot introduce vulnerabilities and approve code to merge. | +| `prevent_approval_by_commit_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, users who have contributed code to the MR are ineligible for approval. This ensures code committers cannot introduce vulnerabilities and approve code to merge. | +| `remove_approvals_with_new_commit` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, if an MR receives all necessary approvals to merge, but then a new commit is added, new approvals are required. This ensures new commits that may include vulnerabilities cannot be introduced. | +| `require_password_to_approve` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, there will be password confirmation on approvals. Password confirmation adds an extra layer of security. | +| `prevent_pushing_and_force_pushing` | `boolean` | false | `true`, `false` | All | When enabled, prevents users from pushing and force pushing to a protected branch if that branch is included in the security policy. This ensures users do not bypass the merge request process to add vulnerable code to a branch. | ## Example security scan result policies project @@ -300,10 +299,20 @@ actions: ## Understanding scan result policy approvals +> The branch comparison logic for `scan_finding` was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/428518) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `scan_result_policy_merge_base_pipeline`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `scan_result_policy_merge_base_pipeline`. +On GitLab.com, this feature is not available. + ### Scope of scan result policy comparison -- To determine when approval is required on a merge request, we compare the latest completed pipelines for each supported pipeline source for the source and target branch (for example, `feature`/`main`). This ensures the most comprehensive evaluation of scan results. -- We compare findings from the latest completed pipelines that ran on `HEAD` of the source and target branch. +- To determine when approval is required on a merge request, we compare completed pipelines for each supported pipeline source for the source and target branch (for example, `feature`/`main`). This ensures the most comprehensive evaluation of scan results. +- For the source branch, the comparison pipeline is its latest completed `HEAD` pipeline. +- For `license_finding` rules, we compare to a common ancestor's latest completed pipeline. +- For `scan_finding` rules, the comparison pipeline may differ: + - If the `scan_result_policy_merge_base_pipeline` feature flag is enabled, we compare to a common ancestor's latest completed pipeline. + - Otherwise, we compare to the target branch's latest completed `HEAD` pipeline. - Scan result policies considers all supported pipeline sources (based on the [`CI_PIPELINE_SOURCE` variable](../../../ci/variables/predefined_variables.md)) when comparing results from both the source and target branches when determining if a merge request requires approval. Pipeline sources `webide` and `parent_pipeline` are not supported. ### Accepting risk and ignoring vulnerabilities in future merge requests @@ -352,6 +361,78 @@ We have identified in [epic 11020](https://gitlab.com/groups/gitlab-org/-/epics/ - Findings or errors that cause approval to be required on a scan result policy may not be evident in the Security MR Widget. By using `merge base` in [issue 428518](https://gitlab.com/gitlab-org/gitlab/-/issues/428518) some cases will be addressed. We will additionally be [displaying more granular details](https://gitlab.com/groups/gitlab-org/-/epics/11185) about what caused security policy violations. - Security policy violations are distinct compared to findings displayed in the MR widgets. Some violations may not be present in the MR widget. We are working to harmonize our features in [epic 11020](https://gitlab.com/groups/gitlab-org/-/epics/11020) and to display policy violations explicitly in merge requests in [epic 11185](https://gitlab.com/groups/gitlab-org/-/epics/11185). +## Experimental features **(EXPERIMENT)** + +### Security policy scopes + +> The `policy_scope` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135398) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_policy_scope`. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +an administrator can [disable the feature flag](../../../administration/feature_flags.md) +named `security_policies_policy_scope`. +On GitLab.com, this feature is available. + +Security policy enforcement depends first on establishing a link between the group, subgroup, or +project on which you want to enforce policies, and the security policy project that contains the +policies. For example, if you are linking policies to a group, a group owner must create the link to +the security policy project. Then, all policies in the security policy project are inherited by all +projects in the group. + +You can refine a security policy's scope to: + +- _Include_ only projects containing a compliance framework label. +- _Include_ or _exclude_ selected projects from enforcement. + +#### Policy scope schema + +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `policy_scope` | `object` | false | `compliance_frameworks`, `projects` | Scopes the policy based on compliance framework labels or projects you define. | + +#### `policy_scope` scope type + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `compliance_frameworks` | `object` | `ids` | List of IDs of the compliance frameworks in scope of enforcement, in an `ids` array. | +| `projects` | `object` | `including`, `excluding` | Use `excluding:` or `including:` then list the IDs of the projects you wish to include or exclude, in an `ids` array. | + +#### Example `policy.yml` with security policy scopes + +```yaml +--- +scan_result_policy: +- name: critical vulnerability CS approvals + description: critical severity level only for container scanning + enabled: true + rules: + - type: scan_finding + branches: + - main + scanners: + - container_scanning + vulnerabilities_allowed: 1 + severity_levels: + - critical + vulnerability_states: + - newly_detected + actions: + - type: require_approval + approvals_required: 1 + user_approvers: + - adalberto.dare + policy_scope: + compliance_frameworks: + ids: + - 2 + - 11 + projects: + including: + ids: + - 24 + - 27 +``` + ## Troubleshooting ### Merge request rules widget shows a scan result policy is invalid or duplicated **(ULTIMATE SELF)** diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index a813ac9888d..1f5340758c6 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -54,7 +54,7 @@ support the following features: - [Scan projects](index.md#supported-languages-and-frameworks) - [Multi-project support](index.md#multi-project-support) - [Offline support](index.md#running-sast-in-an-offline-environment) -- [Emits JSON report format](index.md#reports-json-format) +- [Output results in JSON report format](index.md#output) - [SELinux support](index.md#running-sast-in-selinux) ## Post analyzers diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 992e99f1cc7..a9ef89077ca 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -28,7 +28,7 @@ You can disable predefined rules for any SAST analyzer. When you disable a rule: -- Most analyzers still scan for the vulnerability. The results are removed as a processing step after the scan completes, and they don't appear in the [`gl-sast-report.json` artifact](index.md#reports-json-format). +- Most analyzers still scan for the vulnerability. The results are removed as a processing step after the scan completes, and they don't appear in the [`gl-sast-report.json` artifact](index.md#output). - Findings for the disabled rule no longer appear in the [pipeline security tab](../index.md#pipeline-security-tab). - Existing findings for the disabled rule on the default branch are marked as [`No longer detected`](../vulnerability_report/index.md#activity-filter) in the [vulnerability report](../index.md#vulnerability-report). @@ -196,7 +196,7 @@ rule that you wish to modify. | `value` | The value of the identifier used by the predefined rule. | You can look up the correct values for `type` and `value` by viewing the -[`gl-sast-report.json`](index.md#reports-json-format) produced by the analyzer. +[`gl-sast-report.json`](index.md#output) produced by the analyzer. You can download this file as a job artifact from the analyzer's CI job. For example, the snippet below shows a finding from a `semgrep` rule with three diff --git a/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png b/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png Binary files differindex c86f536afc4..582e55f1d0a 100644 --- a/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png +++ b/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png diff --git a/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png b/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png Binary files differindex 199f8b6d322..b293989ae21 100644 --- a/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png +++ b/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index ab6d5212227..cddd6a1f14d 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -54,36 +54,39 @@ For more information about our plans for language support in SAST, see the [cate | Language / framework | [Analyzer](analyzers.md) used for scanning | Minimum supported GitLab version | |------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| -| .NET (all versions, C# only) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 15.4 | +| .NET (all versions, C# only) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 15.4 | | Apex (Salesforce) | [PMD](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | 12.1 | -| C | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.2 | +| C | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 14.2 | | C/C++ | [Flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | 11.1 | -| Go | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.4 | +| Go | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 14.4 | | Groovy<sup>1</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.3 (Gradle) & 11.9 (Maven, SBT) | | Helm Charts | [Kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | 13.1 | -| Java (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.10 | +| Java (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 14.10 | | Java (Android) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | -| JavaScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | +| JavaScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 13.10 | | Kotlin (Android) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | Kotlin (General)<sup>1</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 13.11 | | Kubernetes manifests | [Kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | 12.6 | | Node.js | [NodeJsScan](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | 11.1 | | Objective-C (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | PHP | [phpcs-security-audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | 10.8 | -| Python | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.9 | -| React | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | +| Python | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 13.9 | +| React | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 13.10 | | Ruby | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 13.9 | | Ruby on Rails | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 10.3 | -| Scala (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 16.0 | -| Scala<sup>1</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.0 (SBT) & 11.9 (Gradle, Maven) | +| Scala (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 16.0 | +| Scala <sup>1</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.0 (SBT) & 11.9 (Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | -| TypeScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | +| TypeScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/#sast-rules) | 13.10 | -1. The SpotBugs-based analyzer supports [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/). It can also be used with variants like the -[Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), -[Grails](https://grails.org/), -and the [Maven wrapper](https://github.com/takari/maven-wrapper). However, SpotBugs has [limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/350801) when used against [Ant](https://ant.apache.org/)-based projects. We recommend using the Semgrep-based analyzer for Ant-based Java or Scala projects. +<html> +<small>Footnotes: + <ol> + <li>The SpotBugs-based analyzer supports [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/). It can also be used with variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), [Grails](https://grails.org/), and the [Maven wrapper](https://github.com/takari/maven-wrapper). However, SpotBugs has [limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/350801) when used against [Ant](https://ant.apache.org/)-based projects. We recommend using the Semgrep-based analyzer for Ant-based Java or Scala projects.</li> + </ol> +</small> +</html> ## End of supported analyzers @@ -220,7 +223,7 @@ as shown in the following table: | Automatically scan code with [appropriate analyzers](#supported-languages-and-frameworks) | **{check-circle}** | **{check-circle}** | | [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}** | +| Download [SAST output](#output) | **{check-circle}** | **{check-circle}** | | See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | | See new findings in merge request changes | **{dotted-circle}** | **{check-circle}** | | [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -230,25 +233,38 @@ as shown in the following table: | [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | | [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** | +## Output + +SAST outputs the file `gl-sast-report.json` as a job artifact. The file contains details of all +detected vulnerabilities. You can +[download](../../../ci/jobs/job_artifacts.md#download-job-artifacts) the file for processing +outside GitLab. + +For more information, see: + +- [SAST report file schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json) +- [Example SAST report file](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/qa/expect/js/default/gl-sast-report.json) + ## View SAST results -SAST results are shown in the: +The [SAST report file](#output) is processed by GitLab and the details are shown in the UI: - Merge request widget - Merge request changes view -- Vulnerability Report +- Vulnerability report ### Merge request widget **(ULTIMATE ALL)** SAST results display in the merge request widget area if a report from the target -branch is available for comparison. The merge request widget displays SAST findings and resolutions that +branch is available for comparison. The merge request widget displays SAST results and resolutions that were introduced by the changes made in the merge request.  ### Merge request changes view **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10959) in GitLab 16.6 with a [flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. Disabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10959) in GitLab 16.6 with a [flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. Disabled by default. +> - Enabled by default in GitLab 16.8. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. @@ -303,10 +319,6 @@ When downloading, you always receive the most recent SAST artifact available. You can enable and configure SAST by using the UI, either with the default settings or with customizations. The method you can use depends on your GitLab license tier. -### Running jobs in merge request pipelines - -See [Use security scanning tools with merge request pipelines](../index.md#use-security-scanning-tools-with-merge-request-pipelines) - #### Configure SAST with customizations **(ULTIMATE ALL)** > [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410013) individual SAST analyzers configuration options from the UI in GitLab 16.2. @@ -505,6 +517,10 @@ spotbugs-sast: sast: gl-sast-report.json ``` +### Running jobs in merge request pipelines + +See [Use security scanning tools with merge request pipelines](../index.md#use-security-scanning-tools-with-merge-request-pipelines). + ### Available CI/CD variables SAST can be configured using the [`variables`](../../../ci/yaml/index.md#variables) parameter in @@ -593,6 +609,7 @@ Some analyzers can be customized with CI/CD variables. | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | | `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://semgrep.dev). Default: `true`. Introduced in GitLab 14.0. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/330565`. | | `SAST_SCANNER_ALLOWED_CLI_OPTS` | Semgrep | CLI options (arguments with value, or flags) that are passed to the underlying security scanner when running scan operation. Only a limited set of [options](#security-scanner-configuration) are accepted. Separate a CLI option and its value using either a blank space or equals (`=`) character. For example: `name1 value1` or `name1=value1`. Multiple options must be separated by blank spaces. For example: `name1 value1 name2 value2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368565) in GitLab 15.3. | +| `SAST_RULESET_GIT_REFERENCE` | Semgrep and nodejs-scan | Defines a path to a custom ruleset configuration. If a project has a `.gitlab/sast-ruleset.toml` file committed, that local configuration takes precedence and the file from `SAST_RULESET_GIT_REFERENCE` isn’t used. This variable is available for the Ultimate tier only. | #### Security scanner configuration @@ -646,21 +663,6 @@ variables: SAST_EXPERIMENTAL_FEATURES: "true" ``` -## Reports JSON format - -SAST outputs a report file in JSON format. The report file contains details of all found vulnerabilities. -To download the report file, you can either: - -- Download the file from the CI/CD pipelines page. -- In the pipelines tab on merge requests, set [`artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. - -For information, see [Download job artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts). - -For details of the report file's schema, see -[SAST report file schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). - -For an example SAST report file, see [`gl-sast-report.json`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/qa/expect/js/default/gl-sast-report.json) example. - ## Running SAST in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index bf7375a58d7..9e2d67237d3 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -56,17 +56,17 @@ If you operate a cloud or SaaS product and you're interested in partnering with Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/). -| Capability | In Free & Premium | In Ultimate | -|:---------------------------------------------------------------- |:-----------------------|:-----------------------| -| [Configure Secret Detection scanner](#enable-secret-detection) | **{check-circle}** Yes | **{check-circle}** Yes | -| [Customize Secret Detection settings](#configure-scan-settings) | **{check-circle}** Yes | **{check-circle}** Yes | -| Download [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** Yes | **{check-circle}** Yes | +| Capability | In Free & Premium | In Ultimate | +|:-----------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------| +| [Configure Secret Detection scanner](#enable-secret-detection) | **{check-circle}** Yes | **{check-circle}** Yes | +| [Customize Secret Detection settings](#configure-scan-settings) | **{check-circle}** Yes | **{check-circle}** Yes | +| Download [SAST output](../sast/index.md#output) | **{check-circle}** Yes | **{check-circle}** Yes | | [Check text for potential secrets](#warnings-for-potential-leaks-in-text-content) before it's posted | **{check-circle}** Yes | **{check-circle}** Yes | -| See new findings in the merge request widget | **{dotted-circle}** No | **{check-circle}** Yes | -| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** No | **{check-circle}** Yes | -| [Manage vulnerabilities](../vulnerability_report/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** No | **{check-circle}** Yes | +| See new findings in the merge request widget | **{dotted-circle}** No | **{check-circle}** Yes | +| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** No | **{check-circle}** Yes | +| [Manage vulnerabilities](../vulnerability_report/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** No | **{check-circle}** Yes | ## Coverage @@ -110,17 +110,13 @@ Secret Detection can detect if a secret was added in one commit and removed in a [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). Secret Detection's results are only available after the pipeline is completed. -## Running jobs in merge request pipelines - -See [Use security scanning tools with merge request pipelines](../index.md#use-security-scanning-tools-with-merge-request-pipelines) - ## Enable Secret Detection Prerequisites: - Linux-based GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or -[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the -shared runners on GitLab.com, this is enabled by default. + [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the + shared runners on GitLab.com, this is enabled by default. - Windows Runners are not supported. - CPU architectures other than amd64 are not supported. - If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See @@ -265,6 +261,10 @@ For example: "A personal token for GitLab will look like glpat-JUST20LETTERSANDNUMB" #gitleaks:allow ``` +### Running jobs in merge request pipelines + +See [Use security scanning tools with merge request pipelines](../index.md#use-security-scanning-tools-with-merge-request-pipelines). + ### Available CI/CD variables Secret Detection can be customized by defining available CI/CD variables: diff --git a/doc/user/application_security/secret_detection/pre_receive.md b/doc/user/application_security/secret_detection/pre_receive.md index 1e7ea4aaaeb..8bb56644926 100644 --- a/doc/user/application_security/secret_detection/pre_receive.md +++ b/doc/user/application_security/secret_detection/pre_receive.md @@ -29,7 +29,9 @@ Prerequisites: ## Limitations -This feature only scans non-binary blobs under 1 MiB in size. Binary blobs and blobs larger than 1 MiB are not scanned. +- This feature only scans non-binary blobs under 1 MiB in size. Binary blobs and blobs larger than 1 MiB are not scanned. +- The scan does not analyze the content of a commit if it is identical to the content of another file already present in the source code. +- The scan skips analyzing files that are renamed, deleted, or moved, unless their content is modified in the same commit. ## Resolve a blocked push @@ -53,15 +55,7 @@ If the blocked secret appears earlier in your Git history: ## Skip secret detection -In some cases, it may be necessary to skip pre-receive secret detection. For example, a developer may need to commit a placeholder secret for testing, or a user may want to bypass secret detection due to a Git operation timeout. To skip secret detection for a particular secret, add `# gitleaks:allow` to the end of the line. To skip secret detection for all commits in a push, add `[skip secret detection]` to one of the commit messages. For example: - -```ruby -# This secret will be skipped due to gitleaks:allow. -FAKE_TOKEN = allowfaketoken123 # gitleaks:allow - -# This secret will be scanned, and the push will be rejected. -REAL_TOKEN = rejectrealtoken123 -``` +In some cases, it may be necessary to skip pre-receive secret detection. For example, a developer may need to commit a placeholder secret for testing, or a user may want to bypass secret detection due to a Git operation timeout. To skip secret detection for all commits in a push, add `[skip secret detection]` to one of the commit messages. For example: ```shell # These commits are in the same push. Both will not be scanned. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md index b35de7827e8..095796f3dc4 100644 --- a/doc/user/application_security/secure_your_application.md +++ b/doc/user/application_security/secure_your_application.md @@ -1,6 +1,7 @@ --- stage: Secure group: Static Analysis +description: Container, dependency, and vulnerability scans. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 405017ab023..e9f3a3a2c0b 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -20,6 +20,12 @@ The data provided by the Security Dashboards can be used supply to insight on wh <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Security Dashboard](https://www.youtube.com/watch?v=Uo-pDns1OpQ). +## Vulnerability metrics in the Value Streams Dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383697) in GitLab 16.0. + +You can view vulnerability metrics also in the [Value Streams Dashboard](../../../user/analytics/value_streams_dashboard.md) comparison panel, which helps you understand security exposure in the context of your organization's software delivery workflows. + ## Prerequisites To view the Security Dashboards, the following is required: diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 23454bf387a..620d8c75e52 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -133,6 +133,10 @@ The content of the Project filter depends on the current level: ### Activity filter +> Introduced in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `activity_filter_has_remediations`. Disabled by default. + +FLAG: +On self-managed GitLab, by default the Solution Available filter is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `activity_filter_has_remediations`. On GitLab.com, this feature is not available. This feature is not ready for production use. The activity filter behaves differently from the other filters. You can select only one value in each category. To remove a filter, from the activity filter dropdown list select the filter you want to remove. @@ -141,7 +145,7 @@ Selection behavior when using the activity filter: - **Activity** - **All activity**: Vulnerabilities with any activity status (same as ignoring this filter). Selecting this deselects all other activity filter options. - **Detection** - - **Still detected**: Vulnerabilities that are still detected in the latest pipeline scan of the `default` branch. + - **Still detected** (default): Vulnerabilities that are still detected in the latest pipeline scan of the `default` branch. - **No longer detected**: Vulnerabilities that are no longer detected in the latest pipeline scan of the `default` branch. - **Issue** - **Has issues**: Vulnerabilities with one or more associated issues. @@ -149,6 +153,9 @@ Selection behavior when using the activity filter: - **Merge request** - **Has merge request**: Vulnerabilities with one or more associated merge requests. - **Does not have merge request**: Vulnerabilities without an associated merge request. +- **Solution available** + - **Has a solution**: Vulnerabilities with an available solution. + - **Does not have a solution**: Vulnerabilities without an available solution. ## View details of a vulnerability @@ -181,10 +188,13 @@ To change the status of vulnerabilities: - One or more vulnerabilities, select the checkbox beside each vulnerability. - All vulnerabilities on the page, select the checkbox in the table header. 1. In the **Set status** dropdown list, select the desired status. -1. If the **Dismissed** status is chosen, select the desired reason in the **Set dismissal reason** dropdown list. -1. In the **Add a comment** input, you can provide a comment. For the **Dismissed** status, a comment is required. +1. If the **Dismiss** status is chosen, select the desired reason in the **Set dismissal reason** dropdown list. +1. In the **Add a comment** input, you can provide a comment. For the **Dismiss** status, a comment is required. 1. Select **Change status**. +The status of the selected vulnerabilities is updated and the content of the vulnerability report is +refreshed. +  ## Sort vulnerabilities by date detected @@ -195,6 +205,8 @@ To sort vulnerabilities by the date each vulnerability was detected, select the ## Export vulnerability details +> Added "Dismissal Reason" as a column in the CSV export [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434076) in GitLab 16.8. + You can export details of the vulnerabilities listed in the Vulnerability Report. The export format is CSV (comma separated values). All vulnerabilities are included because filters do not apply to the export. @@ -219,6 +231,7 @@ Fields included are: - Comments - Full Path - CVSS Vectors +- [Dismissal Reason](../vulnerabilities/index.md#vulnerability-dismissal-reasons) NOTE: Full details are available through our diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index e60ac7d4c21..41cc323f3e1 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -101,6 +101,29 @@ To view findings, either: NOTE: This does not apply for the vulnerabilities existing on the default branch. +## Change status of findings + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331408) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `pipeline_security_dashboard_graphql`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `pipeline_security_dashboard_graphql`. +On GitLab.com, this feature is not available. + +To change the status of findings to **Dismiss** or **Needs triage**: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Build > Pipelines**. +1. Select a pipeline and select the **Security** tab. +1. To select: + - One or more findings, select the checkbox beside each finding. + - All findings on the page, select the checkbox in the table header. +1. In the **Set status** dropdown list, select the desired status. +1. If the **Dismiss** status is chosen, select the desired reason in the **Set dismissal reason** dropdown list. +1. In the **Add a comment** input, you can provide a comment. For the **Dismiss** status, a comment is required. +1. Select **Change status**. + +The status of the selected findings is updated and the content of the security tab is refreshed. + ## Deduplication process When a pipeline contains jobs that produce multiple security reports of the same type, it is possible that the same @@ -159,7 +182,7 @@ appear in a report. - Deduplication result: duplicates because all criteria match, and type identifiers are ignored. Only one identifier needs to match, in this case CVE-2022-25510. -The examples above don't include the raw location values. Each scan type defines its own -`fingerprint_data`, which is used to generate a `SHA1` hash that is used as the `location_fingerprint`. -You can find definitions for each scan type [`gitlab/lib/gitlab/ci/reports/security/locations`](https://gitlab.com/gitlab-org/gitlab/-/tree/01c69e97340b7c1c7e30c0caec8506910b6503c8/lib/gitlab/ci/reports/security/locations) -and [`gitlab/ee/lib/gitlab/ci/reports/security/locations`](https://gitlab.com/gitlab-org/gitlab/-/tree/01c69e97340b7c1c7e30c0caec8506910b6503c8/ee/lib/gitlab/ci/reports/security/locations). +You can find definitions for each scan type [`gitlab/lib/gitlab/ci/reports/security/locations`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/reports/security/locations) +and [`gitlab/ee/lib/gitlab/ci/reports/security/locations`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/lib/gitlab/ci/reports/security/locations). + +For instance, for `container_scanning` type the location is defined by Docker image name without tag. However if the image tag contains at least one letter and/or is longer than 8 characters, it isn't considered a duplicate. So, locations `registry.gitlab.com/group-name/project-name/image1:12345019:libcrypto3` and `registry.gitlab.com/group-name/project-name/image1:libcrypto3` are treated as identical while `registry.gitlab.com/group-name/project-name/image1:v19202021:libcrypto3` and `registry.gitlab.com/group-name/project-name/image1:libcrypto3` are considered different. diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md deleted file mode 100644 index 09f7b4c77fa..00000000000 --- a/doc/user/award_emojis.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'emoji_reactions.md' -remove_date: '2023-12-20' ---- - -This document was moved to [another location](emoji_reactions.md). - -<!-- This redirect file can be deleted after <2023-12-20>. --> -<!-- 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 (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/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 66e67f56172..a764d0006a1 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -63,9 +63,9 @@ GitLab in a Kubernetes cluster, you might need a different version of Kubernetes You can upgrade your Kubernetes version to a supported version at any time: -- 1.27 (support ends on July 18, 2024 or when 1.30 becomes supported) -- 1.26 (support ends on March 21, 2024 or when 1.29 becomes supported) -- 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported) +- 1.28 (support ends when GitLab version 17.5 is released or when 1.31 becomes supported) +- 1.27 (support ends when GitLab version 17.2 is released or when 1.30 becomes supported) +- 1.26 (support ends when GitLab version 16.10 is released or when 1.29 becomes supported) GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor versions at any given time. diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 5b07dbd56d9..b8caf6d0837 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -137,7 +137,7 @@ By default, the Helm installation command generated by GitLab: - 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. -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). +To see the full list of customizations available, see the Helm chart's [README](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/blob/main/README.md#values). ##### Use the agent when KAS is behind a self-signed certificate @@ -224,13 +224,19 @@ For the best experience, the version of the agent installed in your cluster shou ### Update the agent version +NOTE: +Instead of using `--reuse-values`, you should specify all needed values. +If you use `--reuse-values`, you might miss new defaults or use deprecated values. +To retrieve previous `--set` arguments, use `helm get values <release name>`. +You can save the values to a file with `helm get values gitlab-agent > agent.yaml`, and pass the file to Helm with `-f`: +`helm upgrade gitlab-agent gitlab/gitlab-agent -f agent.yaml`. This safely replaces the behavior of `--reuse-values`. + To update the agent to the latest version, you can run: ```shell helm repo update helm upgrade --install gitlab-agent gitlab/gitlab-agent \ --namespace gitlab-agent \ - --reuse-values ``` To set a specific version, you can override the `image.tag` value. For example, to install version `v14.9.1`, run: @@ -238,7 +244,6 @@ To set a specific version, you can override the `image.tag` value. For example, ```shell helm upgrade gitlab-agent gitlab/gitlab-agent \ --namespace gitlab-agent \ - --reuse-values \ --set image.tag=v14.9.1 ``` diff --git a/doc/user/clusters/agent/kas_glossary.md b/doc/user/clusters/agent/kas_glossary.md new file mode 100644 index 00000000000..d2d4065f3fb --- /dev/null +++ b/doc/user/clusters/agent/kas_glossary.md @@ -0,0 +1,20 @@ +--- +stage: Deploy +group: Environments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Kubernetes integration glossary **(FREE ALL)** + +This glossary provides definitions for terms related to the GitLab Kubernetes integration. + +| Term | Definition | Scope | +| --- | --- | --- | +| GitLab agent for Kubernetes | The overall offering, including related features and the underlying components `agentk` and `kas`. | GitLab, Kubernetes, Flux | +| `agentk` | The cluster-side component that maintains a secure connection to GitLab for Kubernetes management and deployment automation. | GitLab | +| GitLab agent server for Kubernetes (`kas`) | The GitLab-side component of GitLab that handles operations and logic for the Kubernetes agent integration. Manages the connection and communication between GitLab and Kubernetes clusters. | GitLab | +| Pull-based deployment | A deployment method where Flux checks for changes in a Git repository and automatically applies these changes to the cluster. | GitLab, Kubernetes | +| Push-based deployment | A deployment method where updates are sent from GitLab CI/CD pipelines to the Kubernetes cluster. | GitLab | +| Flux | An open-source GitOps tool that integrates with the agent for pull-based deployments. | GitOps, Kubernetes | +| GitOps | A set of practices that involve using Git for version control and collaboration in the management and automation of cloud and Kubernetes resources. | DevOps, Kubernetes | +| Kubernetes namespace | A logical partition in a Kubernetes cluster that divides cluster resources between multiple users or environments. | Kubernetes | diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 178f1bd7705..2c748712fe5 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -47,7 +47,7 @@ Management projects are restricted to the following: To use a cluster management project to manage your cluster: 1. Create a new project to serve as the cluster management project -for your cluster. + for your cluster. 1. [Associate the cluster with the management project](#associate-the-cluster-management-project-with-the-cluster). 1. [Configure your cluster's pipelines](#configuring-your-pipeline). 1. [Set the environment scope](#setting-the-environment-scope). @@ -66,12 +66,12 @@ To associate a cluster management project with your cluster: 1. Select **Kubernetes**. 1. Expand **Advanced settings**. 1. From the **Cluster management project** dropdown list, select the cluster management project -you created in the previous step. + you created in the previous step. ### Configuring your pipeline After designating a project as the management project for the cluster, -write a [`.gitlab-ci.yml`](../../ci/yaml/index.md) in that project. For example: +add a [`.gitlab-ci.yml` file](../../ci/index.md#the-gitlab-ciyml-file) in that project. For example: ```yaml configure cluster: @@ -99,7 +99,7 @@ to a management project: | Production | `production` | The environments set in the -[`.gitlab-ci.yml`](../../ci/yaml/index.md) file deploy to the Development, Staging, and Production cluster. +[`.gitlab-ci.yml` file](../../ci/index.md#the-gitlab-ciyml-file) deploy to the Development, Staging, and Production cluster. ```yaml stages: diff --git a/doc/user/compliance/compliance_center/index.md b/doc/user/compliance/compliance_center/index.md index 63b4560a498..da65cc9ef6e 100644 --- a/doc/user/compliance/compliance_center/index.md +++ b/doc/user/compliance/compliance_center/index.md @@ -71,6 +71,29 @@ To update the adherence status for these projects, the group-level or the projec To comply with GitLab standard, you must have at least two users approve a merge request to get it merged. For more information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). +### Export standards adherence report for projects in a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413736) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `compliance_standards_adherence_csv_export`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) +named `compliance_standards_adherence_csv_export`. On GitLab.com, this feature is not available. The feature is not ready for production use. + +Exports the contents of a standards adherence report for projects in a group. Reports are truncated at 15 MB to avoid a large email attachment. + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To export the standards adherence report for projects in a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export standards adherence report**. + +A report is compiled and delivered to your email inbox as an attachment. + ## Compliance violations report > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in GitLab 12.8 as Compliance Dashboard. @@ -391,10 +414,11 @@ Repeat this process to filter by multiple attributes. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422973) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `compliance_framework_report_ui`. Disabled by default. > - In GitLab 16.4 and earlier, **Compliance frameworks report** referred to what is now called **Compliance projects report**. The formally-named **Compliance frameworks report** was [renamed to **Compliance projects report**](https://gitlab.com/gitlab-org/gitlab/-/issues/422963) in GitLab 16.5. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140825) in GitLab 16.8. 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_framework_report_ui`. On GitLab.com, this feature is not available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature an administrator to [disable the feature flag](../../../administration/feature_flags.md) named +`compliance_framework_report_ui`. On GitLab.com, this feature is available. With compliance frameworks report, you can see all the compliance frameworks in a group. Each row of the report shows: diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md index 43d76845ffa..3bfc5612db9 100644 --- a/doc/user/compliance/license_list.md +++ b/doc/user/compliance/license_list.md @@ -4,9 +4,13 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# License list **(ULTIMATE ALL)** +<!--- start_remove The following content will be removed on remove_date: '2024-08-15' --> -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. +# License list (deprecated) **(ULTIMATE ALL)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/436100) in GitLab 16.8 +and is planned for removal in 17.0. Use the [Dependency List](../application_security/dependency_list/index.md) instead. The License list allows you to see your project's licenses and key details about them. @@ -32,3 +36,5 @@ The licenses are displayed, where: - **Policy Violation:** The license has a [license policy](license_approval_policies.md) marked as **Deny**.  + +<!--- end_remove --> diff --git a/doc/user/custom_roles.md b/doc/user/custom_roles.md index 1f3628efa39..07e14494ada 100644 --- a/doc/user/custom_roles.md +++ b/doc/user/custom_roles.md @@ -1,21 +1,15 @@ --- stage: Govern -group: Authentication +group: Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom roles **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`. +> - [Custom roles feature introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114524) in GitLab 15.10. -> - The ability for a custom role to view a vulnerability report [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10160) in GitLab 16.1 [with a flag](../administration/feature_flags.md) named `custom_roles_vulnerability`. -> - Ability to view a vulnerability report [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123835) in GitLab 16.1. -> - [Feature flag `custom_roles_vulnerability` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124049) in GitLab 16.2. > - Ability to create and remove a custom role with the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393235) in GitLab 16.4. -> - Ability to manage group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) in GitLab 16.5. -> - Ability to manage project access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `manage_project_access_tokens`. -> - Ability to archive projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.7. > - Ability to use the UI to add a user to your group with a custom role, change a user's custom role, or remove a custom role from a group member [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393239) in GitLab 16.7. Custom roles allow group Owners or instance administrators to create roles @@ -26,6 +20,10 @@ For a demo of the custom roles feature, see [[Demo] Ultimate Guest can view code You can discuss individual custom role and permission requests in [issue 391760](https://gitlab.com/gitlab-org/gitlab/-/issues/391760). +## Available permissions + +For more information on available permissions, see [custom abilities](custom_roles/abilities.md). + ## Create a custom role Prerequisites: @@ -96,26 +94,6 @@ In **Settings > Roles and Permissions**, the list of all custom roles displays t To create a custom role, you can also [use the API](../api/member_roles.md#add-a-member-role-to-a-group). -### Available permissions - -The following permissions are available. You can add these permissions in any combination -to a base role to create a custom role. - -Some permissions require having other permissions enabled first. For example, administration of vulnerabilities (`admin_vulnerability`) can only be enabled if reading vulnerabilities (`read_vulnerability`) is also enabled. - -These requirements are documented in the `Required permission` column in the following table. - -| Permission | Version | Required permission | Description | -| ------------------------------- | -----------------------| -------------------- | ----------- | -| `read_code` | GitLab 15.7 and later | Not applicable | View project code. Does not include the ability to pull code. | -| `read_vulnerability` | GitLab 16.1 and later | Not applicable | View [vulnerability reports](application_security/vulnerability_report/index.md). | -| `admin_vulnerability` | GitLab 16.1 and later | `read_vulnerability` | Change the [status of vulnerabilities](application_security/vulnerabilities/index.md#vulnerability-status-values). | -| `read_dependency` | GitLab 16.3 and later | Not applicable | View [project dependencies](application_security/dependency_list/index.md). | -| `admin_merge_request` | GitLab 16.4 and later | Not applicable | View and approve [merge requests](project/merge_requests/index.md), revoke merge request approval, and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules. | -| `manage_project_access_tokens` | GitLab 16.5 and later | Not applicable | Create, delete, and list [project access tokens](project/settings/project_access_tokens.md). | -| `admin_group_member` | GitLab 16.5 and later | Not applicable | Add or remove [group members](group/manage.md). | -| `archive_project` | GitLab 16.6 and later | Not applicable | Archive and unarchive [projects](project/settings/migrate_projects.md#archive-a-project). | - ## Billing and seat usage When you enable a custom role for a user with the Guest role, that user has @@ -219,8 +197,8 @@ To remove a custom role from a group member: 1. Select the **Max role** dropdown list for the member you want to remove a custom role from. 1. On the **Change role** dialog, select a static role. -You can update or remove a custom role from a group member also with the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project). -and pass an empty `member_role_id` value: +You can also use the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) +to update or remove a custom role from a group member by passing an empty `member_role_id` value: ```shell # to update a project membership diff --git a/doc/user/custom_roles/abilities.md b/doc/user/custom_roles/abilities.md new file mode 100644 index 00000000000..d117a495798 --- /dev/null +++ b/doc/user/custom_roles/abilities.md @@ -0,0 +1,65 @@ +--- +stage: Govern +group: Authorization +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" +--- + +<!--- + This documentation is auto generated by a Rake task. + + Please do not edit this file directly. To update this file, run: + bundle exec rake gitlab:custom_roles:compile_docs + + To make changes to the output of the Rake task, + edit `tooling/custom_roles/docs/templates/custom_abilities.md.erb`. +---> + +# Available custom abilities + +The following abilities are available. You can add these abilities in any combination +to a base role to create a custom role. + +Some abilities require having other abilities enabled first. For example, administration of vulnerabilities (`admin_vulnerability`) can only be enabled if reading vulnerabilities (`read_vulnerability`) is also enabled. + +These requirements are documented in the `Required ability` column in the following table. + +## Code review workflow + +| Name | Required permission | Description | Introduced in | Feature flag | Enabled in | +|:-----|:------------|:------------------|:---------|:--------------|:---------| +| [`admin_merge_request`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128302) | | Allows approval of merge requests. | GitLab [16.4](https://gitlab.com/gitlab-org/gitlab/-/issues/412708) | | | +| [`read_code`](https://gitlab.com/gitlab-org/gitlab/-/issues/376180) | | Allows read-only access to the source code. | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/20277) | `customizable_roles` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) | + +## Group and projects + +| Name | Required permission | Description | Introduced in | Feature flag | Enabled in | +|:-----|:------------|:------------------|:---------|:--------------|:---------| +| [`admin_group_member`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131914) | | Allows admin of group members. | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) | `admin_group_member` | GitLab [16.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136247) | + +## Groups and projects + +| Name | Required permission | Description | Introduced in | Feature flag | Enabled in | +|:-----|:------------|:------------------|:---------|:--------------|:---------| +| [`archive_project`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134998) | | Allows archiving of projects. | GitLab [16.6](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) | `archive_project` | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139260) | +| [`remove_project`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139696) | | Allows deletion of projects. | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/425959) | | | + +## Infrastructure as code + +| Name | Required permission | Description | Introduced in | Feature flag | Enabled in | +|:-----|:------------|:------------------|:---------|:--------------|:---------| +| [`admin_terraform_state`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140759) | | Allows to admin terraform state | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/421789) | | | + +## System access + +| Name | Required permission | Description | Introduced in | Feature flag | Enabled in | +|:-----|:------------|:------------------|:---------|:--------------|:---------| +| [`manage_group_access_tokens`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140115) | | Allows manage access to the group access tokens. | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/428353) | | | +| [`manage_project_access_tokens`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132342) | | Allows manage access to the project access tokens. | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) | `manage_project_access_tokens` | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141294) | + +## Vulnerability management + +| Name | Required permission | Description | Introduced in | Feature flag | Enabled in | +|:-----|:------------|:------------------|:---------|:--------------|:---------| +| [`admin_vulnerability`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121534) | read_vulnerability | Allows admin access to the vulnerability reports. | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/412536) | | | +| [`read_dependency`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126247) | | Allows read-only access to the dependencies. | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/415255) | | | +| [`read_vulnerability`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120704) | | Allows read-only access to the vulnerability reports. | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/399119) | | | diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 034e2e45127..dfcbc8a171d 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -163,7 +163,7 @@ To lock an issue or merge request: 1. On the left sidebar, select **Search or go to** and find your project. 1. For merge requests, select **Code > Merge requests**, and find your merge request. 1. For issues, select **Plan > Issues**, and find your issue. -1. On the top right, select **Merge request actions** or **Issue actions** (**{ellipsis_v}**), then select **Lock discussion**. +1. In the upper-right corner, select **Merge request actions** or **Issue actions** (**{ellipsis_v}**), then select **Lock discussion**. A system note is added to the page details. diff --git a/doc/user/emoji_reactions.md b/doc/user/emoji_reactions.md index 10385da7cdc..a72c15bb229 100644 --- a/doc/user/emoji_reactions.md +++ b/doc/user/emoji_reactions.md @@ -15,8 +15,7 @@ and thumbs-ups. React with emoji on: - [Issues](project/issues/index.md). - [Tasks](tasks.md). -- [Merge requests](project/merge_requests/index.md), -[snippets](snippets.md). +- [Merge requests](project/merge_requests/index.md), [snippets](snippets.md). - [Epics](../user/group/epics/index.md). - [Objectives and key results](okrs.md). - Anywhere else you can have a comment thread. diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index 83e2926e8e3..ccce9e9f9b4 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -1,8 +1,8 @@ --- stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" -description: "View a list of all the flags available in the GitLab application." +description: Complete list of flags. +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments layout: 'feature_flags' --- diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 70ac1f737e6..75d0c8fdd12 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -232,9 +232,8 @@ this limit. Repository limits apply to both public and private projects. ## Default import sources -> Disabling all importers by default for new GitLab self-managed installations [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118970) in GitLab 16.0. - -The import sources that are available by default depend on which GitLab you use: +The [import sources](../project/import/index.md#supported-import-sources) that are available to you by default depend on +which GitLab you use: - GitLab.com: all available import sources are enabled by default. - GitLab self-managed: no import sources are enabled by default and must be @@ -246,14 +245,12 @@ The import sources that are available by default depend on which GitLab you use: | [Bitbucket Server](../project/import/bitbucket_server.md) | **{check-circle}** Yes | **{dotted-circle}** No | | [FogBugz](../project/import/fogbugz.md) | **{check-circle}** Yes | **{dotted-circle}** No | | [Gitea](../project/import/gitea.md) | **{check-circle}** Yes | **{dotted-circle}** No | -| [GitLab by direct transfer](../group/import/index.md#migrate-groups-by-direct-transfer-recommended) | **{check-circle}** Yes | **{dotted-circle}** No | +| [GitLab by direct transfer](../group/import/index.md) | **{check-circle}** Yes | **{dotted-circle}** No | | [GitLab using file exports](../project/settings/import_export.md) | **{check-circle}** Yes | **{dotted-circle}** No | | [GitHub](../project/import/github.md) | **{check-circle}** Yes | **{dotted-circle}** No | | [Manifest file](../project/import/manifest.md) | **{check-circle}** Yes | **{dotted-circle}** No | | [Repository by URL](../project/import/repo_by_url.md) | **{check-circle}** Yes | **{dotted-circle}** No | -[Other importers](../project/import/index.md#available-project-importers) are available. - ## IP range GitLab.com uses the IP ranges `34.74.90.64/28` and `34.74.226.0/24` for traffic from its Web/API @@ -457,7 +454,7 @@ To help avoid abuse, the following are rate limited: For more information, see: - [Project import/export rate limits](../../user/project/settings/import_export.md#rate-limits). -- [Group import/export rate limits](../../user/group/import/index.md#rate-limits). +- [Group import/export rate limits](../../user/project/settings/import_export.md#rate-limits-1). ### Non-configurable limits diff --git a/doc/user/gitlab_duo_chat.md b/doc/user/gitlab_duo_chat.md index ebcb4c69e64..deb908444c3 100644 --- a/doc/user/gitlab_duo_chat.md +++ b/doc/user/gitlab_duo_chat.md @@ -4,37 +4,78 @@ group: Duo Chat info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Answer questions with GitLab Duo Chat **(ULTIMATE SAAS BETA)** +# GitLab Duo Chat **(ULTIMATE ALL BETA)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117695) as an [Experiment](../policy/experiment-beta-support.md#experiment) for SaaS in GitLab 16.0. +> - Changed to [Beta](../policy/experiment-beta-support.md#beta) for SaaS in GitLab 16.6. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11251) as a [Beta](../policy/experiment-beta-support.md#beta) for self-managed in GitLab 16.8. + +GitLab Duo Chat is your personal AI-powered assistant for boosting productivity. +It can assist various tasks of your daily work with the AI-generated content. +Here are the examples of use cases: + +| Feature | Use case example | Supported interfaces | Supported deployments | +| ------------------------------------- | ---------------- | -------------------------- | --------------------- | +| [Ask about GitLab](#ask-about-gitlab) | I want to know how to create an issue in GitLab. | GitLab, VS Code, and Web IDE | GitLab.com | +| [Ask about a specific issue](#ask-about-a-specific-issue) | I want to summarize this issue. | GitLab, VS Code, and Web IDE | GitLab.com, self-managed, and GitLab Dedicated | +| [Ask about a specific epic](#ask-about-a-specific-epic) | I want to summarize this epic. | GitLab, VS Code, and Web IDE | GitLab.com, self-managed, and GitLab Dedicated | +| [Ask about code](#ask-about-code) | I want to understand how this code works. | GitLab, VS Code, and Web IDE | GitLab.com, self-managed, and GitLab Dedicated | +| [Ask about CI/CD](#ask-about-cicd) | I want to create a new CI/CD pipeline configuration. | GitLab, VS Code, and Web IDE | GitLab.com, self-managed, and GitLab Dedicated | +| [Explain code in the IDE](#explain-code-in-the-ide) | I want to understand how this code works. | VS Code and Web IDE | GitLab.com, self-managed, and GitLab Dedicated | +| [Refactor code in the IDE](#explain-code-in-the-ide) | I want to write a test for this code. | VS Code and Web IDE | GitLab.com, self-managed, and GitLab Dedicated | +| [Write tests in the IDE](#write-tests-in-the-ide) | I want to refactor this code. | VS Code and Web IDE | GitLab.com, self-managed, and GitLab Dedicated | + +<div class="video-fallback"> + <a href="https://youtu.be/l6vsd1HMaYA?si=etXpFbj1cBvWyj3_">View how to setup and use GitLab Duo Chat</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/l6vsd1HMaYA?si=etXpFbj1cBvWyj3_" frameborder="0" allowfullscreen> </iframe> +</figure> -> Introduced in GitLab 16.6 as a [Beta](../policy/experiment-beta-support.md#beta). - -You can get AI-generated support from GitLab Duo Chat about: - -- How to use GitLab. -- The contents of an issue or issue. -- The contents of a code or CI/CD configuration file. - -You can also use GitLab Duo Chat to create code and CI/CD files. +NOTE: +This is a Beta feature. We're continuously extending the capabilities and reliability of the responses. -When you get an answer, you can ask follow-up questions to learn more. +## Features -This is a Beta feature. We're continuously extending the capabilities and reliability of the responses. +### Ask about GitLab -## Ask about GitLab +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117695) for SaaS in GitLab 16.0. You can ask questions about how GitLab works. Things like: - `Explain the concept of a 'fork' in a concise manner.` - `Provide step-by-step instructions on how to reset a user's password.` -## Ask about your work +NOTE: +This feature is not currently supported in self-managed instances. +See [this epic](https://gitlab.com/groups/gitlab-org/-/epics/11600) for more infomation. -You can ask about GitLab issues and epics. For example: +### Ask about a specific issue + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for SaaS in GitLab 16.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for self-managed in GitLab 16.8. + +You can ask about a specific GitLab issue. For example: - `Generate a summary for the issue identified via this link: <link to your issue>` -- `Generate a concise summary of the current issue.` +- When you are viewing an issue in GitLab, you can ask `Generate a concise summary of the current issue.` +- `How can I improve the description of <link to your issue> so that readers understand the value and problems to be solved?` + +### Ask about a specific epic + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128487) for SaaS in GitLab 16.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128487) for self-managed in GitLab 16.8. + +You can ask about a specific GitLab epic. For example: + +- `Generate a summary for the epic identified via this link: <link to your epic>` +- `Generate a concise summary of the opened epic.` +- `What are the unique use cases raised by commenters in <link to your epic>?` -## Ask about code +### Ask about code + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for SaaS in GitLab 16.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for self-managed in GitLab 16.8. You can also ask GitLab Duo Chat to generate code: @@ -45,13 +86,52 @@ And you can ask GitLab Duo Chat to explain code: - `Provide a clear explanation of the given Ruby code: def sum(a, b) a + b end. Describe what this code does and how it works.` -## Ask about CI/CD +### Ask about CI/CD + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423524) for SaaS in GitLab 16.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423524) for self-managed in GitLab 16.8. You can ask GitLab Duo Chat to create a CI/CD configuration: - `Create a .gitlab-ci.yml configuration file for testing and building a Ruby on Rails application in a GitLab CI/CD pipeline.` -## Ask follow up questions +### Explain code in the IDE + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for SaaS in GitLab 16.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for self-managed in GitLab 16.8. + +NOTE: +This feature is available in VS Code and the Web IDE only. + +`/explain` is a special command to explain the selected code in your editor. +You can also add additional instructions to be considered, for example: `/explain the performance` +See [Use GitLab Duo Chat in VS Code](#use-gitlab-duo-chat-in-vs-code) for more information. + +### Refactor code in the IDE + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for SaaS in GitLab 16.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for self-managed in GitLab 16.8. + +NOTE: +This feature is available in VS Code and the Web IDE only. + +`/refactor` is a special command to generate a refactoring suggestion for the selected code in your editor. +You can also add additional instructions to be considered, for example: `/refactor with ActiveRecord` +See [Use GitLab Duo Chat in the VS Code](#use-gitlab-duo-chat-in-vs-code) for more information. + +### Write tests in the IDE + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for SaaS in GitLab 16.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for self-managed in GitLab 16.8. + +NOTE: +This feature is available in VS Code and the Web IDE only. + +`/tests` is a special command to generate a testing suggestion for the selected code in your editor. +You can also add additional instructions to be considered, for example: `/tests using the Boost.Test framework` +See [Use GitLab Duo Chat in the VS Code](#use-gitlab-duo-chat-in-vs-code) for more information. + +### Ask follow up questions You can ask follow-up questions to delve deeper into the topic or task at hand. This helps you get more detailed and precise responses tailored to your specific needs, @@ -63,10 +143,43 @@ A follow-up to the question `Write a Ruby function that prints 'Hello, World!' w ## Enable GitLab Duo Chat +### For SaaS users + To use this feature, at least one group you're a member of must have the [experiment and beta features setting](group/manage.md#enable-experiment-and-beta-features) enabled. -## Use GitLab Duo Chat +### For self-managed users + +NOTE: +Usage of GitLab Duo Chat is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +Learn about [data usage when using GitLab Duo Chat](ai_features.md#data-usage). + +Prerequisites: + +- You are using GitLab version 16.8 or later. +- The Ultimate license is activated in your GitLab instance by using [cloud Licensing](https://about.gitlab.com/pricing/licensing-faq/cloud-licensing/). +- All of the users in your instance have the latest version of their IDE extension. +- You are an administrator. + +To enable GitLab Duo Chat for your self-managed GitLab instance: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. +1. Expand **AI-powered features** and select **Enable Experiment and Beta AI-powered features**. +1. Select **Save changes**. +1. To make sure GitLab Duo Chat works immediately, you must + [manually synchronize your subscription](#manually-synchronize-your-subscription). + +#### Manually synchronize your subscription + +You must [manually synchronize your subscription](../subscriptions/self_managed/index.md#manually-synchronize-your-subscription-details) if either: + +- You have just purchased a subscription for the Ultimate tier and have upgraded to GitLab 16.8. +- You already have a subscription for the Ultimate tier and have upgraded to GitLab 16.8. + +Without the manual synchronization, it might take up to 24 hours to activate GitLab Duo Chat on your instance. + +## Use GitLab Duo Chat in the GitLab UI 1. In the lower-left corner, select the **Help** icon. The [new left sidebar must be enabled](../tutorials/left_sidebar/index.md). @@ -84,13 +197,11 @@ To delete all previous conversations: 1. In the text box, type `/clean` and select **Send**. -## Use GitLab Duo Chat in the Web IDE and VS Code **(ULTIMATE SAAS EXPERIMENT)** +## Use GitLab Duo Chat in the Web IDE **(ULTIMATE EXPERIMENT)** > Introduced in GitLab 16.6 as an [EXPERIMENT](../policy/experiment-beta-support.md#experiment). -### Web IDE - -To use GitLab Duo Chat in the Web IDE on GitLab.com: +To use GitLab Duo Chat in the Web IDE on GitLab: 1. Open the Web IDE: 1. On the left sidebar, select **Search or go to** and find your project. @@ -107,9 +218,11 @@ To use GitLab Duo Chat in the Web IDE on GitLab.com: If you have selected code in the editor, this selection is sent along with your question to the AI. This way you can ask questions about this code selection. For instance, `Could you simplify this?`. -### GitLab Workflow extension for VS Code +## Use GitLab Duo Chat in VS Code **(ULTIMATE EXPERIMENT)** + +> Introduced in GitLab 16.6 as an [EXPERIMENT](../policy/experiment-beta-support.md#experiment). -To use GitLab Duo Chat in VS Code: +To use GitLab Duo Chat in GitLab Workflow extension for VS Code: 1. Install and set up the Workflow extension for VS Code: 1. In VS Code, download and Install the [GitLab Workflow extension for VS Code](../editor_extensions/visual_studio_code/index.md#download-the-extension). @@ -125,18 +238,26 @@ To use GitLab Duo Chat in VS Code: If you have selected code in the editor, this selection is sent along with your question to the AI. This way you can ask questions about this code selection. For instance, `Could you simplify this?`. -### Disable Chat in Web IDE and VS Code +### Perform standard task in the IDE from the context menu or by using slash commands + +Get code explained, code refactored or get tests generated for code. To do so: + +1. Select code in your editor in VS Code or in the Web IDE. +1. Type one the following slash commands into the chat field: [`/explain`](#explain-code-in-the-ide), [`/refactor`](#refactor-code-in-the-ide) or [`/tests`](#write-tests-in-the-ide). Alternatively, use the context menu to perform these tasks. -To disable GitLab Duo Chat in the Web IDE and VS Code: +When you use one of the slash commands you can also add additional instructions to be considered, for example: `/tests using the Boost.Test framework` + +### Disable Chat in VS Code + +To disable GitLab Duo Chat in VS Code: 1. Go to **Settings > Extensions > GitLab Workflow (GitLab VSCode Extension)**. 1. Clear the **Enable GitLab Duo Chat assistant** checkbox. ## Give feedback -Your feedback is important to us as we continually enhance your GitLab Duo Chat experience: - -- **Enhance Your Experience**: Leaving feedback helps us customize the Chat for your needs and improve its performance for everyone. +Your feedback is important to us as we continually enhance your GitLab Duo Chat experience. +Leaving feedback helps us customize the Chat for your needs and improve its performance for everyone. To give feedback about a specific response, use the feedback buttons in the response message. Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/430124). diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index e08cfea7095..4628b7be9ce 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -63,8 +63,8 @@ address. This top-level group setting applies to: - The GitLab UI, including subgroups, projects, and issues. It does not apply to GitLab Pages. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. - In self-managed installations of GitLab 15.1 and later, you can also configure -[globally-allowed IP address ranges](../../administration/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) -at the group level. + [globally-allowed IP address ranges](../../administration/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) + at the group level. Administrators can combine restricted access by IP address with [globally-allowed IP addresses](../../administration/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges). @@ -118,7 +118,7 @@ To allow runner downloading, add the [outbound runner CIDR ranges](../gitlab_com > - Support for restricting access to projects in the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. > - Support for restricting group memberships to groups with a subset of the allowed email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/354791) in GitLab 15.1.1 -You can prevent users with email addresses in specific domains from being added to a group and its projects. You can define an email domain allowlist at the top-level namespace only. Subgroups do not offer the ability to define an alternative allowlist. +To ensure only users with email addresses in specific domains are added to a group and its projects, define an email domain allowlist at the top-level namespace. Subgroups do not offer the ability to define an alternative allowlist. To restrict group access by domain: diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index ded99f7c936..bbd53c09352 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -129,7 +129,7 @@ For example, if your project has the following Kubernetes clusters: | Test | `test` | Group | | Development| `*` | Group | -And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/index.md): +And the following environments are set in the [`.gitlab-ci.yml` file](../../../ci/index.md#the-gitlab-ciyml-file): ```yaml stages: diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index cdb11bb0548..978c893a0ec 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -21,9 +21,9 @@ DevOps Adoption shows you how groups in your organization adopt and use the most 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. + their DevOps journey. - Find subgroups that have adopted certain features, and provide guidance to other subgroups on -how to use those features. + how to use those features. - Verify if you are getting the return on investment that you expected from GitLab.  @@ -43,11 +43,11 @@ To view DevOps Adoption: 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 | +| 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 | ## Feature adoption diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 9cdebdd7d9d..286a1c474da 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -11,10 +11,6 @@ to them. ## Create an epic -> - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in GitLab 13.2. -> - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. -> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty roadmap. - Prerequisites: - You must have at least the Reporter role for the epic's group. @@ -175,6 +171,9 @@ To do so, either: - In the upper-right corner, select **epic actions** (**{ellipsis_v}**) and then **Reopen epic** - Use the `/reopen` [quick action](../../project/quick_actions.md). +You can also create an epic by +[promoting an issue](../../project/issues/managing_issues.md#promote-an-issue-to-an-epic). + ## Go to an epic from an issue If an issue belongs to an epic, you can go to the parent epic with the @@ -453,40 +452,6 @@ To move an issue to another epic: 1. Go to the **Child issues and epics** section. 1. Drag issues into the desired parent epic in the visible hierarchy. -### Promote an issue to an epic - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. - -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). - -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 and downvotes. -- Participants. -- Group labels that the issue already has. -- Parent epic. - ### Use an epic template for repeating issues You can create a spreadsheet template to manage a pattern of consistently repeating issues. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 28878855098..28e77a942a6 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -4,7 +4,14 @@ group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Migrating GitLab groups **(FREE ALL)** +# Migrate GitLab groups and projects by using direct transfer **(FREE ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 for group resources [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. +> - Group items [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 for project resources [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. +> - New application setting `bulk_import_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. `bulk_import` feature flag removed. +> - `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10. You can migrate GitLab groups: @@ -16,19 +23,10 @@ You can migrate GitLab groups: You can migrate groups in two ways: - By direct transfer (recommended). -- By uploading an export file. +- By [uploading an export file](../../project/settings/import_export.md). If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. -## Migrate groups by direct transfer (recommended) - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 for group resources [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. -> - Group items [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 for project resources [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. -> - New application setting `bulk_import_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. `bulk_import` feature flag removed. -> - `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10. - On self-managed GitLab, by default [migrating group items](#migrated-group-items) is not available. To show the feature, an administrator can [enable it in application settings](../../../administration/settings/import_and_export_settings.md#enable-migration-of-groups-and-projects-by-direct-transfer). @@ -59,12 +57,12 @@ We invite you to leave your feedback about migrating by direct transfer in If you want to move groups instead of copying groups, you can [transfer groups](../manage.md#transfer-a-group) if the groups are in the same GitLab instance. Transferring groups is a faster and more complete option. -### Known issues +## Known issues See [epic 6629](https://gitlab.com/groups/gitlab-org/-/epics/6629) for a list of known issues for migrating by direct transfer. -### Estimating migration duration +## Estimating migration duration Estimating the duration of migration by direct transfer is difficult. The following factors affect migration duration: @@ -111,7 +109,7 @@ There's no exact formula to reliably estimate a migration. However, the average If you are migrating large projects and encounter problems with timeouts or duration of the migration, see [Reducing migration duration](#reducing-migration-duration). -### Limits +## Limits > Eight hour time limit on migrations [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/429867) in GitLab 16.7. @@ -138,7 +136,7 @@ You can test the maximum relation size limit using these APIs: If either API produces files larger than the maximum relation size limit, group migration by direct transfer fails. -### Visibility rules +## Visibility rules After migration: @@ -154,7 +152,7 @@ After migration: If you used a private network on your source instance to hide content from the general public, make sure to have a similar setup on the destination instance, or to import into a private group. -### Prerequisites +## Prerequisites > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. @@ -181,7 +179,7 @@ To migrate groups by direct transfer: - [Configure `proxy_download`](../../../administration/object_storage.md#configure-the-common-parameters). - Ensure that the destination GitLab instance has access to the object storage of the source GitLab instance. -### Prepare user accounts +## Prepare user accounts To ensure GitLab maps users and their contributions correctly: @@ -196,7 +194,7 @@ To ensure GitLab maps users and their contributions correctly: 1. If users already exist on the destination instance and you use [SAML SSO for GitLab.com groups](../../group/saml_sso/index.md), all users must [link their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#link-saml-to-your-existing-gitlabcom-account). -### Connect the source GitLab instance +## Connect the source GitLab instance Create the group you want to import to and connect the source GitLab instance: @@ -209,7 +207,7 @@ Create the group you want to import to and connect the source GitLab instance: 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. -### Select the groups and projects to import +## Select the groups and projects to import > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects. @@ -228,7 +226,7 @@ WARNING: Importing groups with projects is in [Beta](../../../policy/experiment-beta-support.md#beta). This feature is not ready for production use. -### Group import history +## Group import history > **Partially completed** status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394727) in GitLab 16.7. @@ -248,16 +246,17 @@ To view group import history: 1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, select **See failures** to see their details. -### Review results of the import +## Review results of the import -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429109) in GitLab 16.6 [with a flag](../../feature_flags.md) named `bulk_import_details_page`. Enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429109) in GitLab 16.6 [with a flag](../../feature_flags.md) named `bulk_import_details_page`. Enabled by default. +> - Feature flag `bulk_import_details_page` removed in GitLab 16.8. To review the results of an import: 1. Go to the [Group import history page](#group-import-history). 1. To see the details of a failed import, select the **See failures** link on any import with a **Failed** or **Partially completed** status. -### Migrated group items +## Migrated group items The group items that are migrated depend on the version of GitLab you use on the destination. To determine if a specific group item is migrated: @@ -304,14 +303,14 @@ Group items that are migrated to the destination GitLab instance include: - Already exists in the destination GitLab instance. - Has a public email in the source GitLab instance that matches a confirmed email in the destination GitLab instance. -#### Excluded items +### Excluded items Some group items are excluded from migration because they either: - May contain sensitive information: CI/CD variables, webhooks, and deploy tokens. - Are not supported: push rules. -### Migrated project items **(BETA)** +## Migrated project items **(BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. @@ -384,7 +383,7 @@ Project items that are migrated to the destination GitLab instance include: </small> </html> -#### Issue-related items +### Issue-related items Issue-related project items that are migrated to the destination GitLab instance include: @@ -397,7 +396,7 @@ Issue-related project items that are migrated to the destination GitLab instance | Merge request URL references | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/267947) | | Time tracking | [GitLab 14.4](https://gitlab.com/gitlab-org/gitlab/-/issues/267946) | -#### Merge request-related items +### Merge request-related items Merge request-related project items that are migrated to the destination GitLab instance include: @@ -411,7 +410,7 @@ Merge request-related project items that are migrated to the destination GitLab | Issue URL references | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/267947) | | Time tracking | [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/339403) | -#### Setting-related items +### Setting-related items Setting-related project items that are migrated to the destination GitLab instance include: @@ -422,7 +421,7 @@ Setting-related project items that are migrated to the destination GitLab instan | Project properties | [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75898) | | Service Desk | [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75653) | -#### Excluded items +### Excluded items Some project items are excluded from migration because they either: @@ -443,7 +442,7 @@ Some project items are excluded from migration because they either: - Pages domains - Remote mirrors -### Troubleshooting +## Troubleshooting 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: @@ -468,7 +467,7 @@ entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :s You can also see all migrated entities with any failures related to them using an [API endpoint](../../../api/bulk_imports.md#list-all-group-or-project-migrations-entities). -#### Stale imports +### Stale imports > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352985) in GitLab 14.10. @@ -483,7 +482,7 @@ import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) import.status #=> 3 means that the import timed out. ``` -#### Error: `404 Group Not Found` +### Error: `404 Group Not Found` If you attempt to import a group that has a path comprised of only numbers (for example, `5000`), GitLab attempts to find the group by ID instead of the path. This causes a `404 Group Not Found` error in GitLab 15.4 and earlier. @@ -499,7 +498,7 @@ To solve this, you must change the source group path to include a non-numerical - The [Groups API](../../../api/groups.md#update-group). -#### Other `404` errors +### Other `404` errors You can receive other `404` errors when importing a group, for example: @@ -511,7 +510,7 @@ You can receive other `404` errors when importing a group, for example: This error indicates a problem transferring from the _source_ instance. To solve this, check that you have met the [prerequisites](#prerequisites) on the source instance. -#### Reducing migration duration +### Reducing migration duration A single direct transfer migration runs 5 entities (groups or projects) per import at a time, independent of the number of workers available on the destination instance. That said, having more workers on the destination instance speeds up migration by decreasing the time it takes to import each entity. @@ -529,157 +528,6 @@ Distributing projects in different groups helps to avoid timeouts. If several la The GitLab UI can only migrate top-level groups. Using the API, you can also migrate subgroups. -## Migrate groups by uploading an export file (deprecated) - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. -> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6. - -WARNING: -This feature was [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6 and replaced by -[migrating groups by direct transfer](#migrate-groups-by-direct-transfer-recommended). However, this feature is still recommended for migrating groups between -offline systems. To follow progress on an alternative solution for [offline environments](../../application_security/offline_deployments/index.md), see -[the relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/8985). - -Prerequisites: - -- Owner role on the group to migrate. - -Using file exports, you can: - -- Export any group to a file and upload that file to another GitLab instance or to another location on the same instance. -- Use either the GitLab UI or the [API](../../../api/group_import_export.md). -- Migrate groups one by one, then export and import each project for the groups one by one. - -GitLab maps user contributions correctly when an admin access token is used to perform the import. GitLab does not map -user contributions correctly when you are importing from a self-managed instance to GitLab.com. Correct mapping of user -contributions when importing from a self-managed instance to GitLab.com can be preserved with paid involvement of -Professional Services team. - -Note the following: - -- Exports are stored in a temporary directory and are deleted every 24 hours by a specific worker. -- To preserve group-level relationships from imported projects, export and import groups first so that projects can - be imported into the desired group structure. -- Imported groups are given a `private` visibility level, unless imported into a parent group. -- If imported into a parent group, a subgroup inherits the same level of visibility unless otherwise restricted. -- You can export groups from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) - and vice versa. The Enterprise Edition retains some group data that isn't part of the Community Edition. If you're - exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, - see [downgrading from EE to CE](../../../index.md). - -### Compatibility - -> Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/383682) in GitLab 15.8. - -Group file exports are in NDJSON format. - -You can import group file exports that were exported from a version of GitLab up to two -[minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for -[security releases](../../../policy/maintenance.md#security-releases). - -For example: - -| Destination version | Compatible source versions | -|:--------------------|:---------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | - -### Exported contents - -The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) -file for groups lists items exported and imported when migrating groups using file exports. View this file in the branch -for your version of GitLab to check which items can be imported to the destination GitLab instance. For example, -[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/group/import_export.yml). - -Group items that are exported include: - -- Milestones -- Group Labels (_without_ associated label priorities) -- Boards and Board Lists -- Badges -- Subgroups (including all the aforementioned data) -- Epics - - Epic resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) -- Events -- [Wikis](../../project/wiki/group.md) - ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9) -- Iterations cadences ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95372) in 15.4) - -Items that are **not** exported include: - -- Projects -- Runner tokens -- SAML discovery tokens - -### Preparation - -- To preserve the member list and their respective permissions on imported groups, review the users in these groups. Make -sure these users exist before importing the desired groups. -- Users must set a public email in the source GitLab instance that matches their confirmed primary email in the destination GitLab instance. Most users receive an email asking them to confirm their email address. - -### Enable export for a group - -Prerequisites: - -- You must have the Owner role for the group. - -To enable import and export for a group: - -1. On the left sidebar, at the bottom, select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Visibility and access controls**. -1. In the **Import sources** section, select the checkboxes for the sources you want. - -### Export a group - -Prerequisites: - -- You must have the Owner role for the group. - -To export the contents of a group: - -1. On the left sidebar, select **Search or go to** and find your group. -1. Select **Settings > General**. -1. In the **Advanced** section, select **Export group**. -1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) - in a compressed tar archive, with contents in NDJSON format. -1. Alternatively, you can download the export from the UI: - - 1. Return to your group's **Settings > General** page. - 1. In the **Advanced** section, select **Download export**. - You can also generate a new file by selecting **Regenerate export**. - -You can also export a group [using the API](../../../api/group_import_export.md). - -### Import the group - -1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New subgroup**. -1. Select the **import an existing group** link. -1. Enter your group name. -1. Accept or modify the associated group URL. -1. Select **Choose file...**. -1. Select the file that you exported in the [Export a group](#export-a-group) section. -1. To begin importing, select **Import**. - -Your newly imported group page appears after the operation completes. - -NOTE: -The maximum import file size can be set by the administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the -[Application settings API](../../../api/settings.md#change-application-settings) or the -[Admin Area](../../../administration/settings/account_and_limit_settings.md). -Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to 0 in GitLab 13.8. - -### Rate limits - -To help avoid abuse, by default, users are rate limited to: - -| Request Type | Limit | -| ---------------- | ---------------------------------------- | -| Export | 6 groups per minute | -| Download export | 1 download per group per minute | -| Import | 6 groups per minute | - ## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v15_4.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v15_4.png Binary files differdeleted file mode 100644 index f7963c170e1..00000000000 --- a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v15_4.png +++ /dev/null diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 6ca37cb9a2c..0cb1ad093a5 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,94 +1,11 @@ --- -stage: Plan -group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../../project/insights/index.md' +remove_date: '2024-04-20' --- -# Insights for groups **(ULTIMATE ALL)** +This document was moved to [another location](../../project/insights/index.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. - -Configure insights to explore data about you group's activity, such as -triage hygiene, issues created or closed in a given period, and average time for merge -requests to be merged. -You can also create custom insights reports that are relevant for your group. - -## View group insights - -Prerequisites: - -- You must have [permission](../../permissions.md#group-members-permissions) to view the group. -- You must have access to a project to view information about its merge requests and issues, - and permission to view them if they are confidential. - -To access your group's insights: - -1. On the left sidebar, select **Search or go to** and find your group. -1. Select **Analyze > Insights**. - -## Interact with insights charts - -You can interact with the insights charts to view details about your group's activity. - - - -### Display different reports - -To display one of the available reports on the insights page, from the **Select report** dropdown list, -select the report you want to display. - -### View bar chart annotations - -To view annotations, hover over each bar in the chart. - -### Zoom in on chart - -Insights display data from the last 90 days. You can zoom in to display data only from a subset of the 90-day range. - -To do this, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: - -- To change the start date, slide the left pause icon to the left or right. -- To change the end date, slide the right pause icon to the left or right. - -### Exclude dimensions from charts - -By default, insights display all available dimensions on the chart. - -To exclude a dimension, from the legend below the chart, select the name of the dimension. - -### Drill down on charts - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372215/) in GitLab 16.7. - -You can drill down into the data of the **Bugs created per month by priority** and **Bugs created per month by severity** charts from the [default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). - -To view a drill-down report of the data for a specific priority or severity in a month: - -- On the chart, select the bar stack you want to drill down on. - -## Configure group insights - -GitLab reads insights from the -[default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). - -To configure group insights: - -1. Create a new file [`.gitlab/insights.yml`](../../project/insights/index.md#configure-project-insights) -in a project that belongs to your group. -1. On the left sidebar, select **Search or go to** and find your group. -1. Select **Settings > General**. -1. Expand **Analytics** and find the **Insights** section. -1. Select the project that contains your `.gitlab/insights.yml` configuration file. -1. Select **Save changes**. - -<!-- ## 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, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> +<!-- 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/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png b/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png Binary files differindex 519e56acaa5..b253fe336ee 100644 --- a/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png +++ b/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 28f4026b3e3..efd4a46c710 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -4,17 +4,18 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Issue analytics for groups **(PREMIUM ALL)** +# Issue analytics **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. +> - Issue analytics for groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. +> - Issue analytics for projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in GitLab 12.9. Issue analytics is a bar graph which illustrates the number of issues created each month. -The default time span is 13 months, which includes the current month, and the 12 months -prior. +The default time span is 13 months, which includes the current month, and the 12 months prior. +Issue analytics is available for projects and groups. To access the chart: -1. On the left sidebar, select **Search or go to** and find your group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Issue analytics**. You can also access the chart from the [Value Streams Dashboard](../../analytics/value_streams_dashboard.md) through the **New issues** drill-down report. @@ -39,12 +40,11 @@ shows a total of 15 months for the chart in the GitLab.org group. ## Enhanced issue analytics **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233905/) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233905/) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/437542) in GitLab 16.8. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can -[enable the feature flag](../../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. On GitLab.com, this feature is not -available. This feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. On GitLab.com, this feature is available. Enhanced issue analytics display the additional metric "Issues closed", which represents the total number of resolved issues in your group over a selected period. You can use this metric to improve the overall turn-around time and value delivered to your customers. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 877db58b716..58c3f837e26 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -165,7 +165,7 @@ Transferring groups moves them from one place to another in the same GitLab inst - Convert a subgroup into a top-level group by transferring it out of its current group. If you need to copy a group to a different GitLab instance, -[migrate the group by direct transfer](import/index.md#migrate-groups-by-direct-transfer-recommended). +[migrate the group by direct transfer](import/index.md). When transferring groups, note: @@ -449,11 +449,6 @@ for the ability to set merge request approval rules for groups is tracked in > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. -WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta). -Beta users should read about the [known limitations](../project/repository/code_suggestions/index.md#known-limitations). -We look forward to hearing your [feedback](../project/repository/code_suggestions/index.md#feedback). - You can give all users in a group and its subgroups access to [Code Suggestions](../project/repository/code_suggestions/index.md). This setting [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) in the group. diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index a2576f37ac9..1e7c749a705 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -248,6 +248,11 @@ For GitLab.com, alternatively, when users need to [link SAML to their existing G ### Users receive a 404 **(PREMIUM SAAS)** +If the user receives a `404` after signing in successfully, check if you have IP restrictions configured. IP restriction settings are configured: + +- On GitLab.com, [at the group level](../../../user/group/access_and_permissions.md#restrict-group-access-by-ip-address). +- For GitLab self-managed, [at the instance level](../../../administration/reporting/ip_addr_restrictions.md). + Because SAML SSO for groups is a paid feature, your subscription expiring can result in a `404` error when you're signing in using SAML SSO on GitLab.com. If all users are receiving a `404` when attempting to sign in using SAML, confirm [there is an active subscription](../../../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) being used in this SAML SSO namespace. diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 3dcb2d93096..47b2144c7ff 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -111,6 +111,26 @@ Changing the SAML or SCIM configuration or provider can cause the following prob the SCIM app. 1. Use the same SCIM API to update the SCIM `extern_uid` for the user on GitLab.com. +## The member's email address is not allowed for this group + +SCIM provisioning may fail with HTTP status `412` and the following error message: + +```plaintext +The member's email address is not allowed for this group. Check with your administrator. +``` + +This error occurs when both of the following are true: + +- [Restrict group access by domain](../access_and_permissions.md) is configured + for the group. +- The user account being provisioned has an email domain that is not allowed. + +To resolve this issue, you can do either of the following: + +- Add the user account's email domain to the list of allowed domains. +- Disable the [Restrict group access by domain](../access_and_permissions.md) + feature by removing all domains. + ## Search Rails logs for SCIM requests **(PREMIUM SAAS)** GitLab.com administrators can search for SCIM requests in the `api_json.log` using the `pubsub-rails-inf-gprd-*` index in @@ -149,9 +169,9 @@ The first workaround is: 1. Have the end user [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account). 1. After the user has done this, initiate a SCIM sync from your identity provider. -If the SCIM sync completes without the same error, GitLab has -successfully linked the SCIM identity to the existing user account, and the user -should now be able to sign in using SAML SSO. + If the SCIM sync completes without the same error, GitLab has + successfully linked the SCIM identity to the existing user account, and the user + should now be able to sign in using SAML SSO. If the error persists, the user most likely already exists, has both a SAML and SCIM identity, and a SCIM identity that is set to `active: false`. To resolve @@ -166,7 +186,7 @@ this: If any of this information does not match, [contact GitLab Support](https://support.gitlab.com/). 1. Use the API to [update the SCIM provisioned user's `active` value to `true`](/ee/development/internal_api/index.md#update-a-single-scim-provisioned-user). 1. If the update returns a status code `204`, have the user attempt to sign in -using SAML SSO. + using SAML SSO. ## Azure Active Directory diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index a63d4a98fa2..a43de3ef73b 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -10,12 +10,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can organize GitLab [groups](../index.md) into subgroups. You can use subgroups to: -- Separate internal and external organizations. Because every subgroup can have its own +- Separate internal and external content. Because every subgroup can have its own [visibility level](../../public_access.md), you can host groups for different purposes under the same parent group. -- Organize large projects. You can use subgroups to give different access to parts of +- Organize large projects. You can use subgroups to manage who can access parts of the source code. -- Manage people and control visibility. Give a user a different +- Manage permissions. Give a user a different [role](../../permissions.md#group-members-permissions) for each group they're [a member of](#subgroup-membership). Subgroups can: @@ -25,7 +25,7 @@ Subgroups can: - Be nested up to 20 levels. - Use [runners](../../../ci/runners/index.md) registered to parent groups: - Secrets configured for the parent group are available to subgroup jobs. - - Users with the Maintainer role in projects that belong to subgroups can see the details of runners registered to + - Users with at least the Maintainer role in projects that belong to subgroups can see the details of runners registered to parent groups. For example: @@ -52,7 +52,7 @@ graph TD Prerequisites: - To view private nested subgroups, you must be a direct or inherited member of -the private subgroup. + the private subgroup. To view the subgroups of a group: @@ -117,7 +117,7 @@ For more information, view the [permissions table](../../permissions.md#group-me ## Subgroup membership When you add a member to a group, that member is also added to all subgroups of that group. -The member's permissions are inherited from the group's parent. +The member's permissions are inherited from the group into all subgroups. Subgroup members can be: @@ -189,8 +189,8 @@ Members can be [filtered by inherited or direct membership](../index.md#filter-a Users with the Owner role in a subgroup can add members to it. -You can't give a user a role in a subgroup that is lower than the roles the user has in ancestor groups. -To override a user's role in an ancestor group, add the user to the subgroup again with a higher role. +You can't give a user a role in a subgroup that is lower than the roles the user has in parent groups. +To override a user's role in a parent group, add the user to the subgroup again with a higher role. For example: - If User 1 is added to group _Two_ with the Developer role, User 1 inherits that role in every subgroup of group _Two_. @@ -201,7 +201,7 @@ For example: ## Mention subgroups -Mentioning subgroups ([`@<subgroup_name>`](../../discussions/index.md#mentions)) in issues, commits, and merge requests +Mentioning subgroups ([`@<subgroup_name>`](../../discussions/index.md#mentions)) in epics, issues, commits, and merge requests notifies all direct members of that group. Inherited members of a subgroup are not notified by mentions. Mentioning works the same as for projects and groups, and you can choose the group of members to be notified. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 0fdd572ed7c..7e077c7065c 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -166,7 +166,7 @@ In this example, milestones have been created and CI/CD for testing and setting - 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). +- GitLab CI/CD takes 5 minutes to run scripts defined in the [`.gitlab-ci.yml` file](../../../ci/index.md#the-gitlab-ciyml-file). - 19:00: Merge the merge request. **Review** stage stops and **Staging** stage starts. - 19:30: Deployment to the `production` environment finishes. **Staging** stops. @@ -305,7 +305,7 @@ In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on Prerequisites: - To view deployment metrics, you must have a -[production environment configured](#how-value-stream-analytics-identifies-the-production-environment). + [production environment configured](#how-value-stream-analytics-identifies-the-production-environment). To view lifecycle metrics: @@ -442,11 +442,11 @@ After you create a value stream, you can customize it to suit your purposes. To 1. In the upper-right corner, select the dropdown list, then select a value stream. 1. Next to the value stream dropdown list, select **Edit**. 1. Optional: - - Rename the value stream. - - Hide or re-order default stages. - - Remove existing custom stages. - - To add new stages, select **Add another stage**. - - Select the start and end events for the stage. + - Rename the value stream. + - Hide or re-order default stages. + - Remove existing custom stages. + - To add new stages, select **Add another stage**. + - Select the start and end events for the stage. 1. Optional. To undo any modifications, select **Restore value stream defaults**. 1. Select **Save Value Stream**. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 3b20125ff03..839bce217b7 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -52,7 +52,7 @@ To import the project: This project provides you with: - A [cluster on Google Cloud Platform (GCP)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gke.tf) -with defaults for name, location, node count, and Kubernetes version. + with defaults for name, location, node count, and Kubernetes version. - The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/agent.tf) installed in the cluster. ## Register the agent @@ -73,10 +73,10 @@ To create a GitLab agent for Kubernetes: To set up your project to communicate to GCP and the GitLab API: 1. To authenticate GCP with GitLab, create a [GCP service account](https://cloud.google.com/docs/authentication#service-accounts) -with following roles: `Compute Network Viewer`, `Kubernetes Engine Admin`, `Service Account User`, and `Service Account Admin`. Both User and Admin -service accounts are necessary. The User role impersonates the [default service account](https://cloud.google.com/compute/docs/access/service-accounts#default_service_account) -when [creating the node pool](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/using_gke_with_terraform#node-pool-management). -The Admin role creates a service account in the `kube-system` namespace. + with following roles: `Compute Network Viewer`, `Kubernetes Engine Admin`, `Service Account User`, and `Service Account Admin`. Both User and Admin + service accounts are necessary. The User role impersonates the [default service account](https://cloud.google.com/compute/docs/access/service-accounts#default_service_account) + when [creating the node pool](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/using_gke_with_terraform#node-pool-management). + The Admin role creates a service account in the `kube-system` namespace. 1. Download the JSON file with the service account key you created in the previous step. 1. On your computer, encode the JSON file to `base64` (replace `/path/to/sa-key.json` to the path to your key): diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index d76f5dd736a..616e15dc230 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -84,13 +84,13 @@ To use a Terraform template: ```yaml variables: - TF_STATE_NAME: default - # If your terraform files are in a subdirectory, set TF_ROOT accordingly. For example: - # TF_ROOT: terraform/production + TF_STATE_NAME: 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.yml` file the attributes present -in the template you fetched to customize your configuration. + in the template you fetched to customize your configuration. ### Terraform template recipes diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 04d6caff0ba..6662f6a9dcb 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -1,10 +1,11 @@ --- stage: Deploy group: Environments +description: Terraform and Kubernetes deployments. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Infrastructure management **(FREE ALL)** +# Manage your infrastructure **(FREE ALL)** With the rise of DevOps and SRE approaches, infrastructure management becomes codified, automatable, and software development best practices gain their place around infrastructure diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 01bd7ce0ba6..372442bb53f 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -25,13 +25,12 @@ When this list is rendered, it looks like this: - Dog - Turtle -These styles are **valid for GitLab only**. The [GitLab documentation website](https://docs.gitlab.com) -and the [main GitLab website](https://about.gitlab.com) use [Kramdown](https://kramdown.gettalong.org) instead. - -You should not view this page in the documentation, but instead [view these styles as they appear on GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md). +NOTE: +As this Markdown specification is **valid for GitLab only**, you should +[view these styles as they appear on GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md). -GitLab Flavored Markdown extends the [CommonMark specification](https://spec.commonmark.org/current/). -It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). +We do our best to render the Markdown faithfully here, however the [GitLab documentation website](https://docs.gitlab.com) +and the [GitLab handbook](https://handbook.gitlab.com) use a different Markdown processor. ## Where you can use GitLab Flavored Markdown @@ -39,44 +38,58 @@ You can use GitLab Flavored Markdown in the following areas: - Comments - Issues +- Epics - Merge requests - Milestones - Snippets (the snippet must be named with a `.md` extension) - Wiki pages - Markdown documents inside repositories -- Epics You can also use other rich text files in GitLab. You might have to install a dependency to do so. For more information, see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup). ### Differences between GitLab Flavored Markdown and standard Markdown -GitLab uses standard CommonMark formatting. However, GitLab Flavored Markdown -extends standard Markdown with features made specifically for GitLab. +<!-- +Use this topic to list features that are not present in standard Markdown. +Don't repeat this information in each individual topic, unless there's a specific +reason, like in "Newlines". +--> -Features not found in standard Markdown: +GitLab Flavored Markdown consists of the following: + +- Core Markdown features, based on the [CommonMark specification](https://spec.commonmark.org/current/). +- Extensions from [GitHub Flavored Markdown](https://github.github.com/gfm/). +- Extensions made specifically for GitLab. + +All standard Markdown formatting should work as expected in GitLab. Some standard +functionality is extended with additional features, without affecting the standard usage. + +The following features are not found in standard Markdown: - [Color chips written in `HEX`, `RGB` or `HSL`](#colors) - [Diagrams and flowcharts](#diagrams-and-flowcharts) - [Emoji](#emoji) +- [Footnotes](#footnotes) - [Front matter](#front-matter) +- [GitLab-specific references](#gitlab-specific-references) - [Inline diffs](#inline-diff) - [Math equations and symbols written in LaTeX](#math) -- [Task Lists](#task-lists) +- [Strikethrough](#emphasis) - [Table of Contents](#table-of-contents) -- [Wiki specific Markdown](#wiki-specific-markdown) +- [Tables](#tables) +- [Task lists](#task-lists) +- [Wiki-specific Markdown](#wiki-specific-markdown) -Features [extended from standard Markdown](#features-extended-from-standard-markdown): +The following features are extended from standard Markdown: | Standard Markdown | Extended Markdown in GitLab | |---------------------------------------|---------------------------------------------------------------------------------------| -| [blockquotes](#blockquotes) | [multi-line blockquotes](#multiline-blockquote) | -| [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | -| [emphasis](#emphasis) | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis) | -| [headers](#headers) | [linkable Header IDs](#header-ids-and-links) | -| [images](#images) | [embedded videos](#videos) and [audio](#audio) | -| [line breaks](#line-breaks) | [more line break control](#newlines) | -| [links](#links) | [automatically linking URLs](#url-auto-linking) | +| [Blockquotes](#blockquotes) | [Multiline blockquotes](#multiline-blockquote) | +| [Code blocks](#code-spans-and-blocks) | [Colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | +| [Headings](#headings) | [Linkable heading IDs](#heading-ids-and-links) | +| [Images](#images) | [Embedded videos](#videos) and [audio](#audio) | +| [Links](#links) | [Automatically linking URLs](#url-auto-linking) | ## Markdown and accessibility @@ -85,27 +98,25 @@ This content should be as accessible as possible to your audience. The following list is not exhaustive, but it provides guidance for some of the GLFM styles to pay particular attention to: -### Headings +### Accessible headings Use heading formatting to create a logical heading structure. The structure of headings on a page should make sense, like a good table of contents. Ensure that there is only one `h1` element on a page, that heading levels are not skipped, and that they are nested correctly. -### Tables +### Accessible tables To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering **N/A** for "not applicable" or **None**. -### Images and videos +### Accessible images and videos Describe the image or video in the `[alt text]`. Make the description accurate, succinct, and unique. Don't use `image of` or `video of` in the description. For more information, see [WebAim Alternative Text](https://webaim.org/techniques/alttext/). -## Features not found in standard Markdown - -The following features are not found in standard Markdown. +## Colors -### Colors +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors). Markdown does not support changing text color. @@ -132,9 +143,6 @@ display a color chip next to the color code. For example: - `HSLA(540,70%,50%,0.3)` ``` -[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors) -to see the color chips next to the color code: - - `#F00` - `#F00A` - `#FF0000` @@ -145,7 +153,7 @@ to see the color chips next to the color code: - `HSL(540,70%,50%)` - `HSLA(540,70%,50%,0.3)` -### Diagrams and flowcharts +## Diagrams and flowcharts You can generate diagrams from text by using: @@ -155,7 +163,9 @@ You can generate diagrams from text by using: In wikis, you can also add and edit diagrams created with the [diagrams.net editor](#diagramsnet-editor). -#### Mermaid +### Mermaid + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#mermaid). Visit the [official page](https://mermaidjs.github.io/) for more details. The [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) helps you @@ -220,24 +230,20 @@ graph TB end ``` -#### PlantUML +### PlantUML PlantUML integration is enabled on GitLab.com. To make PlantUML available in self-managed installation of GitLab, a GitLab administrator [must enable it](../administration/integration/plantuml.md). -#### Kroki +### Kroki To make Kroki available in GitLab, a GitLab administrator must enable it. For more information, see the [Kroki integration](../administration/integration/kroki.md) page. -### Emoji +## Emoji [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emoji). -::Tabs - -:::TabTitle Rendered Markdown - Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":monkey:" alt=":monkey:"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/star2.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":star2:" alt=":star2:"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":speech_balloon:" alt=":speech_balloon:">. Well we have a gift for you: <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/zap.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":zap:" alt=":zap:">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/v.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":v:" alt=":v:"> @@ -248,7 +254,7 @@ If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-f Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":thumbsup:" alt=":thumbsup:"> -:::TabTitle Code +The above paragraphs in raw Markdown: ```markdown Sometimes you want to :monkey: around a bit and add some :star2: to your @@ -267,12 +273,10 @@ Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. :thumbsup: ``` -::EndTabs - -#### Emoji and your operating system +### Emoji and your operating system The previous emoji example uses hard-coded images. Rendered emoji -in GitLab may be different depending on the OS and browser used. +in GitLab might look different depending on the OS and browser used. Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based emoji where there is no support. @@ -280,14 +284,14 @@ emoji where there is no support. <!-- vale gitlab.Spelling = NO --> On Linux, you can download [Noto Color Emoji](https://github.com/googlefonts/noto-emoji) -to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has +to get full native emoji support. Ubuntu 22.04 (like many modern Linux distributions) has this font installed by default. <!-- vale gitlab.Spelling = YES --> To learn more about adding custom emoji, see [Custom emoji](emoji_reactions.md#custom-emoji). -### Front matter +## Front matter Front matter is metadata included at the beginning of a Markdown document, preceding the content. This data can be used by static site generators like [Jekyll](https://jekyllrb.com/docs/front-matter/), @@ -349,7 +353,7 @@ $example = array( --- ``` -### Inline diff +## Inline diff [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-diff). @@ -377,8 +381,8 @@ However, you cannot mix the wrapping tags: - [- deletion -} ``` -If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` `` with a -backslash <code>\</code>. Otherwise the diff highlight does not render correctly: +Diff highlighting doesn't work with `` `inline code` ``. If your text includes backticks (`` ` ``), escape +each backtick with a backslash <code>\</code>: ```markdown - {+ Just regular text +} @@ -388,7 +392,7 @@ backslash <code>\</code>. Otherwise the diff highlight does not render corre  -### Math +## Math > - LaTeX-compatible fencing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21757) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com. > - LaTeX-compatible fencing [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371180) in GitLab 15.8. Feature flag `markdown_dollar_math` removed. @@ -397,7 +401,7 @@ backslash <code>\</code>. Otherwise the diff highlight does not render corre Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX). _KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ -This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see +This syntax also works in AsciiDoc wikis and files using `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). To prevent malicious activity, GitLab renders only the first 50 inline math instances. @@ -445,7 +449,7 @@ $$ a^2+b^2=c^2 $$ -### Task lists +## Task lists > Inapplicable checkboxes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85982) in GitLab 15.3. @@ -453,12 +457,12 @@ $$ You can add task lists anywhere Markdown is supported. -- In issues, merge requests, and comments, you can select the boxes. +- In issues, merge requests, epics, and comments, you can select the boxes. - In all other places, you cannot select the boxes. You must edit the Markdown manually by adding or removing an `x` in the brackets. Besides complete and incomplete, tasks can also be **inapplicable**. Selecting an inapplicable checkbox -in an issue, merge request, or comment has no effect. +in an issue, merge request, epic, or comment has no effect. To create a task list, follow the format of an ordered or unordered list: @@ -480,28 +484,40 @@ To create a task list, follow the format of an ordered or unordered list:  -### Table of contents +To include task lists in tables, [use HTML list tags or HTML tables](#task-lists-in-tables). + +## Table of contents + +A table of contents is an unordered list that links to subheadings in the document. +You can add a table of contents to issues, merge requests, and epics, but you can't add one +to notes or comments. + +Add one of these tags on their own line to the **description** field of any of the supported +content types: <!-- -The following paragraphs use HTML to work around a Markdown bug. -Do not change it back to a Markdown backticks. +Tags for the table of contents are presented in a code block to work around a Markdown bug. +Do not change the code block back to single backticks. For more information, see https://gitlab.com/gitlab-org/gitlab/-/issues/359077. --> -<!-- vale gitlab.Uppercase = NO --> -A table of contents is an unordered list that links to subheadings in the document. -You can add a table of contents to issues and merge requests, but you can't add one -to notes or comments. Add either the `[[_TOC_]]` or <code>[TOC]</code> tag on its own line -to the **Description** field of any of the supported content types: -<!-- vale gitlab.Uppercase = YES --> -NOTE: -A table of contents renders also when you use <code>`[TOC]`</code>, regardless of being on its own line or not. -This behavior is unintended. For more information, see [issue 359077](https://gitlab.com/gitlab-org/gitlab/-/issues/359077). +```markdown +[[_TOC_]] +or +[TOC] +``` - Markdown files. - Wiki pages. - Issues. - Merge requests. +- Epics. + +NOTE: +A table of contents renders also when you use the TOC code in single square brackets, regardless of +being on its own line or not. +This behavior is unintended. +For more information, see [issue 359077](https://gitlab.com/gitlab-org/gitlab/-/issues/359077). ```markdown This sentence introduces my wiki page. @@ -519,11 +535,13 @@ Second section content.  -### Wiki-specific Markdown +## Wiki-specific Markdown The following topics show how links inside wikis behave. -#### Wiki - direct page link +When linking to wiki pages, you should use the **page slug** rather than the page name. + +### Wiki - direct page link A direct page link includes the slug for a page that points to that page, at the base level of the wiki. @@ -534,7 +552,7 @@ This example links to a `documentation` page at the root of your wiki: [Link to Documentation](documentation) ``` -#### Wiki - direct file link +### Wiki - direct file link A direct file link points to a file extension for a file, relative to the current page. @@ -545,7 +563,7 @@ it links to `<your_wiki>/documentation/file.md`: [Link to File](file.md) ``` -#### Wiki - hierarchical link +### Wiki - hierarchical link A hierarchical link can be constructed relative to the current wiki page by using `./<page>`, `../<page>`, and so on. @@ -578,7 +596,7 @@ it links to `<your_wiki>/documentation/main.md`: [Link to Related Page](../main.md) ``` -#### Wiki - root link +### Wiki - root link A root link starts with a `/` and is relative to the wiki root. @@ -594,7 +612,7 @@ This example links to `<wiki_root>/miscellaneous.md`: [Link to Related Page](/miscellaneous.md) ``` -#### diagrams.net editor +### diagrams.net editor > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322174) in GitLab 15.10. @@ -604,43 +622,54 @@ the plain text editor and the rich text editor. For more information, see [Diagrams.net](../administration/integration/diagrams_net.md). -##### Plain text editor +#### Plain text editor To create a diagram in the plain text editor: +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the plain text editor + (the button on the bottom left says **Switch to rich text editing**). 1. In the editor's toolbar, select **Insert or edit diagram** (**{diagram}**). -1. Use the diagrams.net editor to create the diagram. +1. Create the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 1. Select **Save & exit**. A Markdown image reference to the diagram is inserted in the wiki content. To edit a diagram in the plain text editor: -1. Place the plain text editor's text field cursor in a Markdown image reference -that contains the diagram. -1. Select **Insert or edit diagram** (**{diagram}**) in the plain text editor. -1. Use the diagrams.net editor to edit the diagram. +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the plain text editor + (the button on the bottom left says **Switch to rich text editing**). +1. Position your cursor in the Markdown image reference that contains the diagram. +1. Select **Insert or edit diagram** (**{diagram}**). +1. Edit the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 1. Select **Save & exit**. A Markdown image reference to the diagram is inserted in the wiki content, replacing the previous diagram. -##### Rich text editor +#### Rich text editor To create a diagram in the rich text editor: +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the rich text editor + (the button on the bottom left says **Switch to plain text editing**). 1. In the editor's toolbar, select **More options** (**{plus}**). 1. In the dropdown list, select **Create or edit diagram**. -1. Use the diagrams.net editor to create the diagram. +1. Create the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 1. Select **Save & exit**. The diagram as visualized in the diagrams.net editor is inserted in the wiki content. To edit a diagram in the rich text editor: +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the rich text editor + (the button on the bottom left says **Switch to plain text editing**). 1. Select the diagram that you want to edit. 1. In the floating toolbar, select **Edit diagram** (**{diagram}**). -1. Use the diagrams.net editor to edit the diagram. +1. Edit the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 1. Select **Save & exit**. The selected diagram is replaced with an updated version. @@ -657,54 +686,55 @@ version to reference other projects from the same namespace. GitLab Flavored Markdown recognizes the following: -| references | input | cross-project reference | shortcut inside same namespace | -|:----------------------------------------------------------------------------|:------------------------------|:----------------------------------------|:-------------------------------| -| specific user | `@user_name` | | | -| specific group | `@group_name` | | | -| entire team | [`@all`](discussions/index.md#mentioning-all-members) | | | -| project | `namespace/project>` | | | -| issue | ``#123`` | `namespace/project#123` | `project#123` | -| 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` | -| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | -| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | -| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | -| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | -| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | -| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | -| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | -| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README.md)` | | | -| repository file line references | `[README](doc/README.md#L13)` | | | -| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | -| contact | `[contact:test@example.com]` | | | - -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. +| References | Input | Cross-project reference | Shortcut inside the same namespace | +| -------------------------------------------------------------- | ------------------------------ | --------------------------------------- | ---------------------------------- | +| Specific user | `@user_name` | | | +| Specific group | `@group_name` | | | +| Entire team | [`@all`](discussions/index.md#mentioning-all-members) | | | +| Project | `namespace/project>` | | | +| Issue | ``#123`` | `namespace/project#123` | `project#123` | +| 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) | `[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` | +| Label by name (one word) | `~bug` | `namespace/project~bug` | `project~bug` | +| Label by name (multiple words) | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| Label by name (scoped) | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | +| Project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| Milestone by name (one word) | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| Milestone by name (multiple words) | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| Commit (specific) | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| Commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| Repository file reference | `[README](doc/README.md)` | | | +| Repository file reference (specific line) | `[README](doc/README.md#L13)` | | | +| [Alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | +| [Contact](crm/index.md#contacts) | `[contact:test@example.com]` | | | For example, referencing an issue by using `#123` formats the output as a link to issue number 123 with text `#123`. Likewise, a link to issue number 123 is recognized and formatted with text `#123`. If you don't want `#123` to link to an issue, add a leading backslash `\#123`. -In addition to this, links to some objects are also recognized and formatted. Some examples of these are: +In addition to this, links to some objects are also recognized and formatted. +For example: -- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (comment 101075757)` -- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. -- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. +- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, rendered as `#1234 (comment 101075757)` +- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, rendered as `#1234 (designs)`. +- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, rendered as `#1234[layout.png]`. ### Show the issue, merge request, or epic title in the reference > - Support for issues, merge requests, and epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15694) in GitLab 14.6. > - Support for work items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0. -To include the title in the rendered link of an issue, work item, merge request, or epic, add a plus (`+`) -at the end of the reference. For example, a reference like `#123+` is rendered as -`The issue title (#123)`. +To include the title in the rendered link of an issue, work item, merge request, or epic: + +- Add a plus (`+`) at the end of the reference. + +For example, a reference like `#123+` is rendered as `The issue title (#123)`. URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+` are also expanded. @@ -713,18 +743,23 @@ URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+` are al > - Support for issues and merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386937) in GitLab 15.10. > - Support for work items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0. -To include an extended summary in the rendered link of an issue, work item, or merge request, add a `+s` -at the end of the reference. Summary includes information about **assignees**, **milestone** -and **health status** of referenced item. +To include an extended summary in the rendered link of an issue, work item, or merge request: + +- Add a `+s` at the end of the reference. + +Summary includes information about **assignees**, **milestone** and **health status** of referenced item. For example, a reference like `#123+s` is rendered as `The issue title (#123) • First Assignee, Second Assignee+ • v15.10 • Needs attention`. URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+s` are also expanded. -To update the rendered references if the assignee, milestone, or health status changed, -edit the comment or description and save it. -For more information, see issue [420807](https://gitlab.com/gitlab-org/gitlab/-/issues/420807). +To update the rendered references if the assignee, milestone, or health status changed: + +- Edit the comment or description and save it. + +Issue [420807](https://gitlab.com/gitlab-org/gitlab/-/issues/420807) tracks improving how these +references refresh. ### Embedding Observability dashboards @@ -733,16 +768,11 @@ You can embed GitLab Observability UI dashboards descriptions and comments, for To embed an Observability dashboard URL: 1. In GitLab Observability UI, copy the URL in the address bar. +1. Paste your link in a comment or description. GitLab Flavored Markdown recognizes the URL and displays the source. -1. Paste your link wherever you want to embed your dashboard. GitLab Flavored Markdown recognizes the URL and displays the source. +## Blockquotes -## Features extended from standard Markdown - -All standard Markdown formatting should work as expected in GitLab. Some standard -functionality is extended with additional features, without affecting the standard usage. -If a functionality is extended, the new option is listed as a sub-section. - -### Blockquotes +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#blockquotes). Use a blockquote to highlight information, such as a side note. It's generated by starting the lines of the blockquote with `>`: @@ -753,7 +783,7 @@ by starting the lines of the blockquote with `>`: Quote break. -> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. +> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *use* **Markdown** in a blockquote. ``` > Blockquotes help you emulate reply text. @@ -761,14 +791,13 @@ Quote break. Quote break. -> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. +> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *use* **Markdown** in a blockquote. -#### Multiline blockquote +### Multiline blockquote -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiline-blockquote). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiline-blockquote). -GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes -fenced by `>>>`, with a blank line before and after the block: +Create multi-line blockquotes fenced by `>>>`, with a blank line before and after the block: ```markdown @@ -794,11 +823,13 @@ trigger this problem. > > you can quote that without having to manually prepend `>` to every line! -### Code spans and blocks +## Code spans and blocks -You can highlight anything that should be viewed as code and not standard text. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#code-spans-and-blocks). -Inline code is highlighted with single backticks `` ` ``: +Highlight anything that should be viewed as code and not standard text. + +Inline code is formatted with single backticks `` ` ``: ```markdown Inline `code` has `back-ticks around` it. @@ -811,6 +842,9 @@ Inline `code` has `back-ticks around` it. To achieve a similar effect for a larger code example, you can: - Fence an entire block of code with triple backticks (```` ``` ````). + - You can use more than three backticks, as long as both the opening and closing set have the same number. + Use multiple backticks for example when you want to include [suggestions](project/merge_requests/reviews/suggestions.md#nest-code-blocks-in-suggestions) + in your code blocks, or the other way around. - Fence an entire block of code with triple tildes (`~~~`). - Indent it four or more spaces. @@ -852,10 +886,9 @@ is like using Tildes are OK too. ``` -#### Colored code and syntax highlighting +### Colored code and syntax highlighting -If this section isn't rendered correctly, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). GitLab uses the [Rouge Ruby library](https://github.com/rouge-ruby/rouge) for more colorful syntax highlighting in code blocks. For a list of supported languages visit the @@ -917,44 +950,45 @@ s = "No highlighting is shown for this line." But let's throw in a <b>tag</b>. ``` -### Emphasis +## Emphasis + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emphasis). -In Markdown, you can emphasize text in multiple ways. You can italicize, bold, strikethrough, -and combine these emphasis styles together. -Strikethrough is not part of the core Markdown standard, but is part of GitLab Flavored Markdown. +You can emphasize text in multiple ways. Use italics, bold, strikethrough, +or combine these emphasis styles together. Examples: ```markdown -Emphasis, aka italics, with *asterisks* or _underscores_. +Emphasis, or italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with double **asterisks** or __underscores__. +Strong emphasis, or bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. -Strikethrough uses two tildes. ~~Scratch this.~~ +Strikethrough with double tildes. ~~Scratch this.~~ ``` <!-- markdownlint-disable MD050 --> -Emphasis, aka italics, with *asterisks* or _underscores_. +Emphasis, or italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with double **asterisks** or __underscores__. +Strong emphasis, or bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. -Strikethrough uses two tildes. ~~Scratch this.~~ +Strikethrough with double tildes. ~~Scratch this.~~ <!-- markdownlint-enable MD050 --> -#### Multiple underscores in words and mid-word emphasis +### Multiple underscores in words and mid-word emphasis -If this section isn't rendered correctly, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words). Avoid italicizing a portion of a word, especially when you're dealing with code and names that often appear with multiple underscores. -GitLab Flavored Markdown extends the standard Markdown standard by ignoring multiple underlines in words, + +GitLab Flavored Markdown ignores multiple underlines in words, to allow better rendering of Markdown documents discussing code: ```markdown @@ -989,9 +1023,11 @@ perform*complicated*task do*this*and*do*that*and*another thing -### Footnotes +## Footnotes + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#footnotes). -Footnotes add a link to a note that are rendered at the end of a Markdown file. +Footnotes add a link to a note rendered at the end of a Markdown file. To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with the note content. @@ -1026,7 +1062,9 @@ These are used to force the Vale ReferenceLinks check to skip these examples. [^footnote-42]: This text is another footnote. -### Headers +## Headings + +Create headings from 1 to 6 by using `#`. ```markdown # H1 @@ -1035,9 +1073,11 @@ These are used to force the Vale ReferenceLinks check to skip these examples. #### H4 ##### H5 ###### H6 +``` -Alternatively, for H1 and H2, an underline-ish style: +Alternatively, for H1 and H2, use an underline style: +```markdown Alt-H1 ====== @@ -1045,111 +1085,121 @@ Alt-H2 ------ ``` -#### Header IDs and links +### Heading IDs and links -GitLab Flavored Markdown extends the standard Markdown standard so that all Markdown-rendered headers automatically -get IDs, which can be linked to, except in comments. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#heading-ids-and-links). + +All Markdown-rendered headings automatically +get IDs that can be linked to, except in comments. On hover, a link to those IDs becomes visible to make it easier to copy the link to -the header to use it somewhere else. +the heading to use it somewhere else. -The IDs are generated from the content of the header according to the following rules: +The IDs are generated from the content of the heading according to the following rules: 1. All text is converted to lowercase. 1. All non-word text (such as punctuation or HTML) is removed. 1. All spaces are converted to hyphens. 1. Two or more hyphens in a row are converted to one. -1. If a header with the same ID has already been generated, a unique +1. If a heading with the same ID has already been generated, a unique incrementing number is appended, starting at 1. Example: ```markdown -# This header has spaces in it -## This header has a :thumbsup: in it -# This header has Unicode in it: 한글 -## This header has spaces in it -### This header has spaces in it -## This header has 3.5 in it (and parentheses) +# This heading has spaces in it +## This heading has a :thumbsup: in it +# This heading has Unicode in it: 한글 +## This heading has spaces in it +### This heading has spaces in it +## This heading has 3.5 in it (and parentheses) ``` Would generate the following link IDs: -1. `this-header-has-spaces-in-it` -1. `this-header-has-a-in-it` -1. `this-header-has-unicode-in-it-한글` -1. `this-header-has-spaces-in-it-1` -1. `this-header-has-spaces-in-it-2` -1. `this-header-has-3-5-in-it-and-parentheses` +1. `this-heading-has-spaces-in-it` +1. `this-heading-has-a-in-it` +1. `this-heading-has-unicode-in-it-한글` +1. `this-heading-has-spaces-in-it-1` +1. `this-heading-has-spaces-in-it-2` +1. `this-heading-has-3-5-in-it-and-parentheses` -Emoji processing happens before the header IDs are generated. The +Emoji processing happens before the heading IDs are generated. The emoji is converted to an image, which is then removed from the ID. -### Horizontal Rule +## Horizontal rule + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#horizontal-rule). Create a horizontal rule by using three or more hyphens, asterisks, or underscores: ```markdown -Three or more hyphens, - --- -asterisks, - *** -or underscores - ___ ``` -### Images +--- -Examples: +--- + +--- + +## Images + +Embed images using inline or reference links. +To see title text, hover over the image. <!-- -The following codeblock uses HTML to skip the Vale ReferenceLinks test. -Do not change it back to a markdown codeblock. +The following examples use HTML to skip the Vale ReferenceLinks test. +Do not change it back to a markdown codeblocks. --> -<!-- markdownlint-disable proper-names --> +<!-- +DO NOT change the name of markdown_logo.png. This file is used for a test in +spec/controllers/help_controller_spec.rb. +--> -<pre class="highlight"><code>Inline-style (hover to see title text): +<!-- +The examples below use an in-line link to pass the Vale ReferenceLinks test. +Do not change to a reference style link. +--> - +Inline-style: -Reference-style (hover to see title text): +<!-- markdownlint-disable proper-names --> -![alt text1][logo] +<pre class="highlight"><code> + + -[logo]: img/markdown_logo.png "Title Text" </code></pre> -<!-- markdownlint-enable proper-names --> + -<!-- -DO NOT change the name of markdown_logo.png. This file is used for a test in -spec/controllers/help_controller_spec.rb. ---> +Reference-style: -Inline-style (hover to see title text): +<pre class="highlight"><code> - +![alt text1][logo] -Reference-style (hover to see title text): +[logo]: img/markdown_logo.png "Title Text" -<!-- -The example below uses an in-line link to pass the Vale ReferenceLinks test. -Do not change to a reference style link. ---> +</code></pre>  -#### Change the image or video dimensions +<!-- markdownlint-enable proper-names --> + +### Change the image or video dimensions > - Support for images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7. > - Support for videos [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17139) in GitLab 15.9. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#change-the-image-or-video-dimensions). + You can control the width and height of an image or video by following the image with an attribute list. The value must an integer with a unit of either `px` (default) or `%`. @@ -1167,50 +1217,45 @@ For example You can also use the `img` HTML tag instead of Markdown and set its `height` and `width` parameters. -#### Videos +### Videos -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos). Image tags that link to files with a video extension are automatically converted to a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`: -```markdown -Here's a sample video: +Here's an example video: +```markdown  ``` -Here's a sample video: -  -#### Audio +### Audio -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#audio). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#audio). Similar to videos, link tags for files with an audio extension are automatically converted to an audio player. The valid audio extensions are `.mp3`, `.oga`, `.ogg`, `.spx`, and `.wav`: -```markdown -Here's a sample audio clip: +Here's an example audio clip: +```markdown  ``` -Here's a sample audio clip: -  -### Inline HTML +## Inline HTML > Allowing `rel="license"` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20857) in GitLab 14.6. -To see the second example of Markdown rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-html). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-html). You can also use raw HTML in your Markdown, and it usually works pretty well. -See the documentation for HTML::Pipeline's [SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42) +See the documentation for `HTML::Pipeline`'s [SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` allowlist, GitLab allows `span`, `abbr`, `details` and `summary` elements. `rel="license"` is allowed on links to support the [Rel-License microformat](https://microformats.org/wiki/rel-license) and license attribution. @@ -1243,7 +1288,7 @@ are separated into their own lines: <dt>Markdown in HTML</dt> <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd> - <dt>Markdown in HTML</dt> + <dt>Markdown in HTML with proper spacing</dt> <dd> Does *not* work **very** well. HTML tags work, in most cases. @@ -1261,7 +1306,7 @@ Markdown is fine in GitLab. <dt>Markdown in HTML</dt> <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd> - <dt>Markdown in HTML</dt> + <dt>Markdown in HTML with proper spacing</dt> <dd> Does <em>not</em> work <b>very</b> well. HTML tags work, in most cases. @@ -1269,38 +1314,33 @@ Markdown is fine in GitLab. </dd> </dl> -#### Collapsible section +### Collapsible section -To see the second Markdown example rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#details-and-summary). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#details-and-summary). Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) tags. For example, collapse a long log file so it takes up less screen space. ```html -<p> <details> -<summary>Click this to collapse/fold.</summary> +<summary>Click to expand</summary> These details <em>remain</em> <strong>hidden</strong> until expanded. <pre><code>PASTE LOGS HERE</code></pre> </details> -</p> ``` -<p> <details> -<summary>Click this to collapse/fold.</summary> +<summary>Click to expand</summary> These details <em>remain</em> <strong>hidden</strong> until expanded. <pre><code>PASTE LOGS HERE</code></pre> </details> -</p> --- @@ -1312,7 +1352,7 @@ Remember to leave a blank line before and after any Markdown sections, as shown <details> <summary> -Click this to _collapse/fold._ +Click to _expand._ </summary> @@ -1331,7 +1371,7 @@ works correctly in GitLab. --> <details> -<summary>Click this to <em>collapse/fold.</em></summary> +<summary>Click to <em>expand.</em></summary> These details <em>remain</em> <b>hidden</b> until expanded. @@ -1339,11 +1379,13 @@ These details <em>remain</em> <b>hidden</b> until expanded. </details> -### Line breaks +## Line breaks + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#line-breaks). A line break is inserted (a new paragraph starts) if the previous text is ended with two newlines, like when you press <kbd>Enter</kbd> twice in a row. If you only -use one newline (select <kbd>Enter</kbd> once), the next sentence remains part of the +use one newline (press <kbd>Enter</kbd> once), the next sentence remains part of the same paragraph. Use this approach if you want to keep long lines from wrapping, and keep them editable: @@ -1367,7 +1409,7 @@ These lines are only separated by single newlines, so they *do not break* and just follow the previous lines in the *same paragraph*. -#### Newlines +### Newlines GitLab Flavored Markdown adheres to the Markdown specification for handling [paragraphs and line breaks](https://spec.commonmark.org/current/). @@ -1382,7 +1424,7 @@ paragraph, with a blank line in between: ```markdown First paragraph. Another line in the same paragraph. -A third line in the same paragraph, but this time ending with two spaces.{space}{space} +A third line in the same paragraph, but this time ending with two spaces.<space><space> A new line directly under the first paragraph. Second paragraph. @@ -1390,7 +1432,9 @@ Another line, this time ending with a backslash.\ A new line due to the previous backslash. ``` -### Links +## Links + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#links). You can create links two ways: inline-style and reference-style. For example: @@ -1404,10 +1448,10 @@ Do not change it back to a markdown codeblock. - 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: +Using heading ID anchors: -- 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) +- This line links to [a section on a different Markdown page, using a "#" and the heading ID](permissions.md#project-features-permissions) +- This line links to [a different section on the same page, using a "#" and the heading ID](#heading-ids-and-links) Using references: @@ -1427,10 +1471,10 @@ Some text to show that the reference links can follow later. - 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: +Using heading ID anchors: -- This line links to [a section on a different Markdown page, using a "#" and the header ID](permissions.md#project-members-permissions) -- This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) +- This line links to [a section on a different Markdown page, using a "#" and the heading ID](permissions.md#project-members-permissions) +- This line links to [a different section on the same page, using a "#" and the heading ID](#heading-ids-and-links) Using references: @@ -1451,9 +1495,11 @@ page, or a wiki page in a project file. The reason: a wiki is always in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` points the link to `wikis/style` only when the link is inside of a wiki Markdown file. -#### URL auto-linking +### URL auto-linking + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#url-auto-linking). -GitLab Flavored Markdown auto-links almost any URL you put into your text: +Almost any URL you put into your text is auto-linked: ```markdown - https://www.google.com @@ -1469,12 +1515,15 @@ GitLab Flavored Markdown auto-links almost any URL you put into your text: - <https://www.google.com> - <https://www.google.com> - <ftp://ftp.us.debian.org/debian/> -- <smb://foo/bar/baz> -- <irc://irc.freenode.net/> +- <a href="smb://foo/bar/baz/">smb://foo/bar/baz</a> +- <a href="irc://irc.freenode.net">irc://irc.freenode.net</a> - <http://localhost:3000> <!-- vale gitlab.Spelling = YES --> -### Lists + +## Lists + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#lists). You can create ordered and unordered lists. @@ -1629,10 +1678,11 @@ For example: CommonMark ignores the blank line and renders this as one list with paragraph spacing. -### Superscripts / Subscripts +## Superscripts / Subscripts + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#superscripts-subscripts). -CommonMark and GitLab Flavored Markdown don't support the Redcarpet superscript syntax ( `x^2` ). -Use the standard HTML syntax for superscripts and subscripts: +For superscripts and subscripts, use the standard HTML syntax: ```html The formula for water is H<sub>2</sub>O @@ -1646,7 +1696,11 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>. <!-- vale gitlab.Spelling = YES --> -### Keyboard HTML tag +GitLab Flavored Markdown doesn't support the Redcarpet superscript syntax ( `x^2` ). + +## Keyboard HTML tag + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#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. @@ -1656,27 +1710,27 @@ Press <kbd>Enter</kbd> to go to the next page. Press <kbd>Enter</kbd> to go to the next page. -### Tables +## Tables -Tables are not part of the core Markdown specification, but are part of GitLab Flavored Markdown. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#tables-1). -#### Markdown +When creating tables: -1. The first line contains the headers, separated by "pipes" (`|`). -1. The second line separates the headers from the cells. - - The cells can contain only empty spaces, hyphens, and - (optionally) colons for horizontal alignment. - - Each cell must contain at least one hyphen, but adding more hyphens to a - cell does not change the cell's rendering. - - Any content other than hyphens, whitespace, or colons is not allowed -1. The third, and any following lines, contain the cell values. - - You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines, - but they can be very long. You can also include HTML `<br>` tags to force newlines if needed. - - The cell sizes **don't** have to match each other. They are flexible, but must be separated - by pipes (`|`). - - You **can** have blank cells. -1. Column widths are calculated dynamically based on the content of the cells. -1. To use the pipe character (`|`) in the text and not as table delimiter, you must escape it with a backslash (`\|`). +- The first line contains the headers, separated by "pipes" (`|`). +- The second line separates the headers from the cells. + - The cells can contain only empty spaces, hyphens, and + (optionally) colons for horizontal alignment. + - Each cell must contain at least one hyphen, but adding more hyphens to a + cell does not change the cell's rendering. + - Any content other than hyphens, whitespace, or colons is not allowed +- The third, and any following lines, contain the cell values. + - You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines, + but they can be very long. You can also include HTML `<br>` tags to force newlines if needed. + - The cell sizes **don't** have to match each other. They are flexible, but must be separated + by pipes (`|`). + - You **can** have blank cells. +- Column widths are calculated dynamically based on the content of the cells. +- To use the pipe character (`|`) in the text and not as table delimiter, you must escape it with a backslash (`\|`). Example: @@ -1694,6 +1748,10 @@ Example: | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell 9 | +### Alignment + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#alignment). + Additionally, you can choose the alignment of text in columns by adding colons (`:`) to the sides of the "dash" lines in the second row. This affects every cell in the column: @@ -1712,6 +1770,10 @@ to the sides of the "dash" lines in the second row. This affects every cell in t [In GitLab itself](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#tables), the headers are always left-aligned in Chrome and Firefox, and centered in Safari. +### Cells with multiple lines + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#cells-with-multiple-lines). + You can use HTML formatting to adjust the rendering of tables. For example, you can use `<br>` tags to force a cell to have multiple lines: @@ -1727,45 +1789,49 @@ use `<br>` tags to force a cell to have multiple lines: | Item1 | This text is on one line | | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | -You can use HTML formatting in GitLab itself to add [task lists](#task-lists) with checkboxes, -but they do not render properly on `docs.gitlab.com`. These tasks will not save their -state when selected, like regular GitLab task lists. - -```markdown -| header 1 | header 2 | -| --- | --- | -| cell 1 | cell 2 | -| cell 3 | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> | -``` - -To have fully functioning task lists in a table, create an HTML table with Markdown in the cells: - -```html -<table> -<thead> -<tr><th>header 1</th><th>header 2</th></tr> -</thead> -<tbody> -<tr> -<td>cell 1</td> -<td>cell 2</td> -</tr> -<tr> -<td>cell 3</td> -<td> +### Task lists in tables + +To add [task lists](#task-lists) with checkboxes, use HTML formatting. Using either: + +- **An HTML table with Markdown in the cells.** Tables formatted this way result in fully functioning + task lists. + + ```html + <table> + <thead> + <tr><th>header 1</th><th>header 2</th></tr> + </thead> + <tbody> + <tr> + <td>cell 1</td> + <td>cell 2</td> + </tr> + <tr> + <td>cell 3</td> + <td> + + - [ ] Task one + - [ ] Task two + + </td> + </tr> + </tbody> + </table> + ``` -- [ ] Task one -- [ ] Task two +- **A Markdown table with HTML list tags.** These tasks don't save their state when selected. + Tables formatted this way do not render properly on `docs.gitlab.com`. -</td> -</tr> -</tbody> -</table> -``` + ```markdown + | header 1 | header 2 | + | --- | --- | + | cell 1 | cell 2 | + | cell 3 | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> | + ``` -##### Copy and paste from a spreadsheet +You can also [create a table in the rich text editor](rich_text_editor.md#tables) and insert a task list then. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. +### Copy and paste from a spreadsheet If you're working in spreadsheet software (for example, Microsoft Excel, Google Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy and paste @@ -1779,7 +1845,7 @@ entry and paste the spreadsheet:  -#### JSON +### JSON > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86353) in GitLab 15.3. diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 14e887fe297..1bed94a302b 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -72,7 +72,7 @@ To view an objective: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) -for `Type = objective`. + for `Type = objective`. 1. Select the title of an objective from the list. ## View a key result @@ -82,7 +82,7 @@ To view a key result: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) -for `Type = key_result`. + for `Type = key_result`. 1. Select the title of a key result from the list. Alternatively, you can access a key result from the **Child objectives and key results** section in @@ -220,7 +220,7 @@ Prerequisites: To promote a key result: 1. [Open the key result](#view-a-key-result). -1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**).. +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Promote to objective**. Alternatively, use the `/promote_to objective` [quick action](../user/project/quick_actions.md). @@ -236,7 +236,7 @@ To copy the objective or key result reference to your clipboard: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your objective or key result to view it. -1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. You can now paste the reference into another description or comment. @@ -256,7 +256,7 @@ To copy the objective's or key result's email address: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. -1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy objective email address** or **Copy key result email address**. +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy objective email address** or **Copy key result email address**. ## Close an OKR @@ -443,7 +443,7 @@ Prerequisites: To change the confidentiality of an existing OKR: 1. [Open the objective](#view-an-objective) or [key result](#view-a-key-result). -1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Turn on confidentiality** or **Turn off confidentiality**. ### Who can see confidential OKRs @@ -498,6 +498,7 @@ or assignees, on the right. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Enabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7. +> - Adding related items by entering their URLs and IDs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427594) in GitLab 16.8. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `linked_work_items`. @@ -522,7 +523,7 @@ To link an item to an objective or key result: - **Relates to** - **Blocks** - **Is blocked by** -1. Enter the search text of the item. +1. Enter the search text of the item, URL, or its reference ID. 1. When you have added all the items to be linked, select **Add** below the search box. When you have finished adding all linked items, you can see diff --git a/doc/user/organization/index.md b/doc/user/organization/index.md index c4fff4178f1..ecc62b0d510 100644 --- a/doc/user/organization/index.md +++ b/doc/user/organization/index.md @@ -44,6 +44,8 @@ To view the organizations you have access to: 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New organization**. 1. In the **Organization name** text box, enter a name for the organization. 1. In the **Organization URL** text box, enter a path for the organization. +1. In the **Organization description** text box, enter a description for the organization. Supports a [limited subset of Markdown](#supported-markdown-for-organization-description). +1. In the **Organization avatar** field, select **Upload** or drag and drop an avatar. 1. Select **Create organization**. ## Edit an organization's name @@ -51,6 +53,10 @@ To view the organizations you have access to: 1. On the left sidebar, select **Organizations** (**{organization}**) and find the organization you want to edit. 1. Select **Settings > General**. 1. In the **Organization name** text box, edit the name. +1. In the **Organization description** text box, edit the description. Supports a [limited subset of Markdown](#supported-markdown-for-organization-description). +1. In the **Organization avatar** field, if an avatar is: + - Selected, select **Remove avatar** to remove. + - Not selected, select **Upload** or drag and drop an avatar. 1. Select **Save changes**. ## Change an organization's URL @@ -72,6 +78,14 @@ To view the organizations you have access to: 1. On the left sidebar, select **Organizations** (**{organization}**) and find the organization you want to manage. 1. Select **Manage > Users**. +## Supported Markdown for Organization description + +The Organization description field supports a limited subset of [GitLab Flavored Markdown](../markdown.md), including: + +- [Emphasis](../markdown.md#emphasis) +- [Links](../markdown.md#links) +- [Superscripts / Subscripts](../markdown.md#superscripts--subscripts) + ## Related topics - [Organization developer documentation](../../development/organization/index.md) diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index db3d31d3c18..c116a43293b 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -128,6 +128,7 @@ Install a package from the package registry so you can use it as a dependency. Prerequisites: - A package in the package registry. +- The package registry is enabled in the project responsible for publishing the package. - The group ID, which is on the group's home page. - One of the following token types: - A [personal access token](../../../user/profile/personal_access_tokens.md) diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 56ea4fe74b4..72f36ca4e80 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -318,11 +318,11 @@ To search by full or partial package name, or by exact recipe, run the The scope of your search depends on your Conan remote configuration: - If you have a remote configured for your [instance](#add-a-remote-for-your-instance), your search includes -all projects you have permission to access. This includes your private projects - as well as all public projects. + all projects you have permission to access. This includes your private projects + as well as all public projects. - If you have a remote configured for a [project](#add-a-remote-for-your-project), your search includes all -packages in the target project, as long as you have permission to access it. + packages in the target project, as long as you have permission to access it. NOTE: The limit of the search results is 500 packages, and the results are sorted by the most recently published packages. diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index ae19a891fc9..6e1c0ded758 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -20,9 +20,9 @@ All of these authentication methods require the minimum scope: To authenticate, run the `docker login` command. For example: - ```shell - docker login registry.example.com -u <username> -p <token> - ``` +```shell +docker login registry.example.com -u <username> -p <token> +``` ## Use GitLab CI/CD to authenticate diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index 680aab42544..7187f5ef1e9 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -46,7 +46,7 @@ You can configure your `.gitlab-ci.yml` file to build and push container images ## Use GitLab CI/CD -You can use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push container images to the +You can use [GitLab CI/CD](../../../ci/index.md) to build and push container images to the Container Registry. You can use CI/CD to test, build, and deploy your project from the container image you created. diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md index 852c20a80f5..73ac0082058 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -101,7 +101,7 @@ delete_image: - ./reg rm -d --auth-url $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $IMAGE_TAG stage: clean variables: - IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228 REG_VERSION: 0.16.1 only: 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 614639c705f..de24f2618d5 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -191,14 +191,14 @@ To create a cleanup policy in the UI: 1. In the **Cleanup policies** section, select **Set cleanup rules**. 1. Complete the fields: - | Field | Description | - |----------------------------|-------------------------------------------------| - | **Toggle** | Turn the policy on or off. | - | **Run cleanup** | How often the policy should run. | - | **Keep the most recent** | How many tags to _always_ keep for each image. | + | Field | Description | + |----------------------------|-------------| + | **Toggle** | Turn the policy on or off. | + | **Run cleanup** | How often the policy should run. | + | **Keep the most recent** | How many tags to _always_ keep for each image. | | **Keep tags matching** | A regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | - | **Remove tags older than** | Remove only tags older than X days. | - | **Remove tags matching** | A regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Remove tags older than** | Remove only tags older than X days. | + | **Remove tags matching** | A regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | 1. Select **Save**. @@ -275,9 +275,9 @@ You can use the following application settings to prevent server resource starva For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - ```ruby - ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) - ``` +```ruby +ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) +``` They are also available in the [administrator area](../../../administration/admin_area.md): @@ -292,7 +292,7 @@ You can set, update, and disable the cleanup policies using the GitLab API. Examples: - Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve -any images with the name `main`, and the policy is enabled: + any images with the name `main`, and the policy is enabled: ```shell curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" \ diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 8f702183adc..bd5311276c6 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -17,8 +17,6 @@ Supported clients: - `mvn`. Learn how to build a [Maven](../workflows/build_packages.md#maven) package. - `gradle`. Learn how to build a [Gradle](../workflows/build_packages.md#gradle) package. - `sbt`. - - `sbt` can only be used to [pull dependencies](#install-a-package). - See this [issue 408479](https://gitlab.com/gitlab-org/gitlab/-/issues/408479) for more details. ## Publish to the GitLab package registry @@ -255,9 +253,9 @@ credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<tok In this example: - `<endpoint url>` is the [endpoint URL](#endpoint-urls). -Example: `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven`. + Example: `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven`. - `<host>` is the host present in the `<endpoint url>` without the protocol -scheme or the port. Example: `gitlab.example.com`. + scheme or the port. Example: `gitlab.example.com`. - `<name>` and `<token>` are explained in the table above. ::EndTabs @@ -289,11 +287,11 @@ For the instance-level endpoint, ensure the relevant section of your `pom.xml` i #### Endpoint URLs -| Endpoint | Endpoint URL for `pom.xml` | Additional information | -| -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | +| Endpoint | Endpoint URL for `pom.xml` | Additional information | +|----------|--------------------------------------------------------------------------|------------------------| | Project | `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<project_id>` with your project ID, found on your project's homepage. | -| Group | `https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<group_id>` with your group ID, found on your group's homepage. | -| Instance | `https://gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | +| Group | `https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<group_id>` with your group ID, found on your group's homepage. | +| Instance | `https://gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | ### Edit the configuration file for publishing @@ -454,6 +452,35 @@ gradle publish Go to your project's **Packages and registries** page and view the published packages. +:::TabTitle `sbt` + +Configure the `publishTo` setting in your `build.sbt` file: + +```scala +publishTo := Some("gitlab" at "<endpoint url>") +``` + +Ensure the credentials are referenced correctly. See the [`sbt` documentation](https://www.scala-sbt.org/1.x/docs/Publishing.html#Credentials) for more information. + +To publish a package using `sbt`: + +```shell +sbt publish +``` + +If the deploy is successful, the build success message is displayed: + +```shell +[success] Total time: 1 s, completed Jan 28, 2020 12:08:57 PM +``` + +Check the success message to ensure the package was published to the +correct location: + +```shell +[info] published my-project_2.12 to https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/my-project_2.12/0.1.1-SNAPSHOT/my-project_2.12-0.1.1-SNAPSHOT.pom +``` + ::EndTabs ## Install a package diff --git a/doc/user/packages/package_registry/dependency_proxy/index.md b/doc/user/packages/package_registry/dependency_proxy/index.md index 7b5e7a4c624..88e424ed3ac 100644 --- a/doc/user/packages/package_registry/dependency_proxy/index.md +++ b/doc/user/packages/package_registry/dependency_proxy/index.md @@ -7,12 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency proxy for packages **(PREMIUM ALL BETA)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3610) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. Disabled by default. -> - This feature is in [Beta](../../../../policy/experiment-beta-support.md). - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. -On GitLab.com, this feature is not available. -The feature is not ready for production use. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415218) in GitLab 16.8. Feature flag `packages_dependency_proxy_maven` removed. The GitLab dependency proxy for packages is a local proxy for frequently pulled packages. It is implemented as a pull-through cache that works at the project level. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 2c9576bf9f7..b4a0597bf60 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -48,10 +48,10 @@ You can publish Terraform modules by using the [Terraform Module Registry API](. Prerequisites: -- The package name and version [must be unique in the top-level namespace](#how-module-resolution-works). +- Unless [duplicates are allowed](#allow-duplicate-terraform-modules), the package name and version [must be unique in the top-level namespace](#how-module-resolution-works). - Your project and group names must not include a dot (`.`). For example, `source = "gitlab.example.com/my.group/project.name"`. - You must [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. -- The name of a module [must be unique in the scope of its group](#how-module-resolution-works), otherwise an +- Unless [duplicates are allowed](#allow-duplicate-terraform-modules), the name of a module [must be unique in the scope of its group](#how-module-resolution-works), otherwise an [error occurs](#troubleshooting). ```plaintext @@ -155,7 +155,23 @@ upload: ``` To trigger this upload job, add a Git tag to your commit. Ensure the tag follows the [Semantic versioning specification](https://semver.org/) that Terraform requires. The `rules:if: $CI_COMMIT_TAG` ensures that only tagged commits to your repository trigger the module upload job. -For other ways to control jobs in your CI/CD pipeline, refer to the [`.gitlab-ci.yml`](../../../ci/yaml/index.md) keyword reference. +For other ways to control jobs in your CI/CD pipeline, refer to the [CI/CD YAML syntax reference](../../../ci/yaml/index.md). + +### Allow duplicate Terraform modules + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368040) in GitLab 16.8. + +By default, the Terraform Module Registry enforces uniqueness for module names in the same namespace. To allow publishing duplicate module names: + +- Enable `terraform_module_duplicates_allowed` for the namespace with the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings). + +To allow duplicates with specific names: + +1. Ensure `terraform_module_duplicates_allowed` is disabled. +1. Use `terraform_module_duplicate_exception_regex` to define a regex pattern for the module names you want to allow duplicates for. + +The top-level namespace setting takes precedence over the child namespace settings. +For example, if you enable `terraform_module_duplicates_allowed` for a group, and disable it for a subgroup, duplicates are allowed for all projects in the group and its subgroups. ## Reference a Terraform module @@ -163,7 +179,9 @@ Prerequisites: - You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. -Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` or `%APPDATA%/terraform.rc` file: +### From a namespace + +You can provide authentication tokens (job tokens, personal access tokens, or deploy tokens) for `terraform` in your `~/.terraformrc` or `%APPDATA%/terraform.rc` file: ```terraform credentials "gitlab.com" { @@ -183,6 +201,32 @@ module "<module>" { Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the Terraform Module Registry. +### From a project + +To reference a Terraform module using a project-level source, use the [fetching archives over HTTP](https://developer.hashicorp.com/terraform/language/modules/sources#fetching-archives-over-http) source type provided by Terraform. + +You can provide authentication tokens (job tokens, personal access tokens, or deploy tokens) for `terraform` in your `~/.netrc` file: + +```netrc +machine gitlab.com +login <USERNAME> +password <TOKEN> +``` + +Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance, and `<USERNAME>` is your token username. + +You can refer to your Terraform module from a downstream Terraform project: + +```terraform +module "<module>" { + source = "https://gitlab.com/api/v4/projects/<project-id>/packages/terraform/modules/<module-name>/<module-system>/<module-version>" +} +``` + +If you need to reference the latest version of a module, you can omit the `<module-version>` from the source URL. To prevent future issues, you should reference a specific version if possible. + +If there are [duplicate module names](#allow-duplicate-terraform-modules) in the same namespace, referencing the module from the namespace level installs the recently published module. To reference a specific version of a duplicate module, use the [project-level](#from-a-project) source type. + ## Download a Terraform module To download a Terraform module: @@ -249,4 +293,4 @@ For examples of the Terraform Module Registry, check the projects below: ## Troubleshooting -- Publishing a module with a duplicate name results in a `{"message":"Access Denied"}` error. There's an ongoing discussion about allowing duplicate module names [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/368040). +- Publishing a module with a duplicate name results in a `{"message":"A package with the same name already exists in the namespace"}` error. diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md index 59508b3e9e2..9d8db546566 100644 --- a/doc/user/packages/workflows/build_packages.md +++ b/doc/user/packages/workflows/build_packages.md @@ -276,6 +276,51 @@ OS: Windows 10 10.0 amd64 1. Enter a project name or press <kbd>Enter</kbd> to use the directory name as project name. +## sbt + +### Install sbt + +Install sbt to create new sbt projects. + +To install sbt for your development environment: + +1. Follow the instructions at [scala-sbt.org](https://www.scala-sbt.org/1.x/docs/Setup.html). + +1. From your terminal, verify you can use sbt: + + ```shell + sbt --version + ``` + +The output is similar to: + +```plaintext +[warn] Project loading failed: (r)etry, (q)uit, (l)ast, or (i)gnore? (default: r) +sbt script version: 1.9.8 +``` + +### Create a Scala project + +1. Open your terminal and create a directory to store the project. +1. From the new directory, initialize a new project: + + ```shell + sbt new scala/scala-seed.g8 + ``` + + The output is: + + ```plaintext + Minimum Scala build. + + name [My Something Project]: hello + + Template applied in ./hello + ``` + +1. Enter a project name or press <kbd>Enter</kbd> to use the directory name as project name. +1. Open the `build.sbt` file and edit it as described in the [sbt documentation](https://www.scala-sbt.org/1.x/docs/Publishing.html) to publish your project to the package registry. + ## npm ### Install npm diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 8c15d696760..05633cac3b0 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -66,7 +66,7 @@ The following table lists project permissions available for each role: | [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_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) | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/proxy-based.md#on-demand-scans) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/on-demand_scan.md) | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | | [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) | | | | | ✓ | diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 75e44471f92..54120ff2330 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -4,7 +4,7 @@ group: Product Analytics info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Product analytics **(ULTIMATE ALL EXPERIMENT)** +# Product analytics **(ULTIMATE SAAS BETA)** > - Introduced in GitLab 15.4 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. > - `cube_api_proxy` revised to only reference the [Product Analytics API](../../api/product_analytics.md) in GitLab 15.6. @@ -12,11 +12,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. > - Snowplow integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398253) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. Disabled by default. > - Snowplow integration feature flag `product_analytics_snowplow_support` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130228) in GitLab 16.4. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/414865) from GitLab self-managed to GitLab.com in 16.7. +> - Enabled in GitLab 16.7 as a [Beta](../../policy/experiment-beta-support.md#beta) feature. This page is a work in progress, and we're updating the information as we add more features. For more information, see the [group direction page](https://about.gitlab.com/direction/monitor/product-analytics/). @@ -30,7 +27,7 @@ To leave feedback about Product Analytics bugs or functionality: Product analytics uses several tools: - [**Snowplow**](https://docs.snowplow.io/docs) - A developer-first engine for collecting behavioral data, and passing it through to ClickHouse. -- [**ClickHouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. +- [**ClickHouse**](../../integration/clickhouse.md) - A database suited to store, query, and retrieve analytical data. - [**Cube**](https://cube.dev/docs/) - A universal semantic layer that provides an API to run queries against the data stored in ClickHouse. The following diagram illustrates the product analytics flow: @@ -65,22 +62,23 @@ flowchart TB > - `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10. > - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flags](../../administration/feature_flags.md) named `product_analytics_dashboards`, `product_analytics_admin_settings`, and `combined_analytics_dashboards`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - -To track events in your project applications on a self-managed instance, -you must enable and configure product analytics. +To track events in your project's applications on GitLab.com, +you must enable and configure Product Analytics. Prerequisites: -- You must be an administrator of a self-managed GitLab instance. +- You must be an Owner of the group you wish to enable Product Analytics for. + +### Group-level settings -1. On the left sidebar, at the bottom, select **Admin Area**. +NOTE: +These group-level settings are available for top-level groups and cascade to all projects that belong to the group. + +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. -1. Expand the **Analytics** tab and find the **Product analytics** section. -1. Select **Enable product analytics** and enter the configuration values. +1. Expand the **Permissions and group features** section. +1. Check **Use Experiment and Beta features** checkbox. +1. Check **Use product analytics** checkbox. 1. Select **Save changes**. ### Project-level settings @@ -90,7 +88,6 @@ have a different configured product analytics instance for your project. Prerequisites: -- Product analytics must be enabled at the instance-level. - You must have at least the Maintainer role for the project or group the project belongs to. - The project must be in a group namespace. @@ -109,19 +106,7 @@ To onboard a project: 1. Select **Analyze > Analytics dashboards**. 1. Under **Product analytics**, select **Set up**. 1. Select **Set up product analytics**. -Your instance is being created, and the project onboarded. - -### Onboard an internal project - -GitLab team members can enable Product Analytics on their internal projects on GitLab.com (Ultimate) during the experiment phase. - -1. Send a message to the Product Analytics team (`#g_analyze_product_analytics`) informing them of the repository to be enabled. -1. Using ChatOps, enable both the `product_analytics_dashboards` and `combined_analytics_dashboards`: - - ```plaintext - /chatops run feature set product_analytics_dashboards true --project=FULLPATH_TO_PROJECT - /chatops run feature set combined_analytics_dashboards true --project=FULLPATH_TO_PROJECT - ``` + Your instance is being created, and the project onboarded. ## Instrument your application @@ -138,11 +123,6 @@ To instrument code to collect data, use one or more of the existing SDKs: > - Introduced in GitLab 15.5 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default. > - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - Product analytics dashboards are a subset of dashboards under [Analytics dashboards](../analytics/analytics_dashboards.md). Specifically product analytics dashboards and visualizations make use of the `cube_analytics` data type. @@ -150,6 +130,8 @@ The `cube_analytics` data type connects to the Cube instance defined when [produ All filters and queries are sent to the Cube instance and the returned data is processed by the product analytics data source to be rendered by the appropriate visualizations. +Data table visualizations from `cube_analytics` have an additional configuration option for rendering `links` (array of objects, each with `text` and `href` properties to specify the dimensions to be used in links. If `href` contains multiple dimensions, values are joined into a single URL). See [example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/analytics_visualization.json?ref_type=heads#L112)). + ### Filling missing data - Introduced in GitLab 16.3 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. Disabled by default. diff --git a/doc/user/product_analytics/instrumentation/browser_sdk.md b/doc/user/product_analytics/instrumentation/browser_sdk.md index 6bc9a9ef234..b9cfbc5b2df 100644 --- a/doc/user/product_analytics/instrumentation/browser_sdk.md +++ b/doc/user/product_analytics/instrumentation/browser_sdk.md @@ -92,7 +92,7 @@ interface GitLabClientSDKOptions { ### Plugins - `Client Hints`: An alternative to tracking the User Agent, which is particularly useful in browsers that are freezing the User Agent string. -Enabling this plugin will automatically capture the following context: + Enabling this plugin will automatically capture the following context: For example, [iglu:org.ietf/http_client_hints/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/blob/master/schemas/org.ietf/http_client_hints/jsonschema/1-0-0) @@ -163,12 +163,12 @@ glClient.page(eventAttributes); The `eventAttributes` object supports the following optional properties: -| Property | Type | Description | -| :--------------- | :-------------------------- | :---------------------------------------------------------------------------- | -| `title` | `String` | Override the default page title. | -| `contextCallback` | `Function` | A callback that fires on the page view. | -| `context` | `Object` | Add context (additional information) on the page view. | -| `timestamp` | `timestamp` | Set the true timestamp or overwrite the device-sent timestamp on an event. | +| Property | Type | Description | +|:------------------|:------------|:------------| +| `title` | `String` | Override the default page title. | +| `contextCallback` | `Function` | A callback that fires on the page view. | +| `context` | `Object` | Add context (additional information) on the page view. | +| `timestamp` | `timestamp` | Set the true timestamp or overwrite the device-sent timestamp on an event. | ### `track` diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 6c78152fa70..4611b3a6a40 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -1,6 +1,7 @@ --- stage: Govern group: Authentication +description: Passwords, user moderation, broadcast messages. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 81e2f3d7a55..b903e422a59 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -425,7 +425,7 @@ a session if the browser is closed or the existing session expires. ## Related topics - [Create users](account/create_accounts.md) -- [Sign in to your GitLab account](../../topics/authentication/index.md) +- [Sign in to your GitLab account](../../administration/auth/index.md) - [Change your password](user_passwords.md) - Receive emails for: - [Sign-ins from unknown IP addresses or devices](notifications.md#notifications-for-unknown-sign-ins) diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 9d54381ef87..dec42e74a58 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -123,8 +123,9 @@ A personal access token can perform actions based on the assigned scopes. | `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. | | `admin_mode` | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 15.8.) | | `create_runner` | Grants permission to create runners. | -| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | | `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. | +| `read_service_ping`| Grant access to download Service Ping payload via API when authenticated as an admin use. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 16.8. | WARNING: If you enabled [external authorization](../../administration/settings/external_authorization.md), personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 6cc5f7c5039..de8ab4b25e9 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -321,20 +321,14 @@ To access your **Followers** and **Following** tabs: ## Enable Code Suggestions **(FREE SAAS)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../policy/experiment-beta-support.md#beta). -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. UI user setting removed. -A percentage of users can use Code Suggestions without any additional configuration. +If Code Suggestions is +[enabled for your top-level group](../group/manage.md#enable-code-suggestions-for-a-group), +you can use Code Suggestions after you +[configure a supported IDE extension](../project/repository/code_suggestions/index.md#supported-editor-extensions). -If the following options are available to you, it means you are **not** part of the percentage of users -and you must manually enable Code Suggestions for your account: - -1. On the left sidebar, select your avatar. -1. Select **Preferences**. -1. Select the **Enable Code Suggestions** checkbox. -1. Select **Save changes**. - -NOTE: -If Code Suggestions are disabled [for any groups that you belong to](../../user/group/manage.md#enable-code-suggestions-for-a-group), then you cannot enable them for yourself. (Your setting has no effect.) +If Code Suggestions are disabled [for all the groups that you belong to](../../user/group/manage.md#enable-code-suggestions-for-a-group), then you cannot enable them for yourself. ## Integrate your GitLab instance with third-party services diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index a15bd39f1b7..df6df1653ac 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -15,7 +15,7 @@ commit author. Changelog formats [can be customized](#customize-the-changelog-ou Each section in the default changelog has a title containing the version number and release date, like this: -````markdown +```markdown ## 1.0.0 (2021-01-05) ### Features (4 changes) @@ -24,7 +24,7 @@ number and release date, like this: - [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) - [Feature 3](gitlab-org/gitlab@234abc) by @steve - [Feature 4](gitlab-org/gitlab@456) -```` +``` The date format for sections can be customized, but the rest of the title cannot. When adding new sections, GitLab parses these titles to determine where to place @@ -121,11 +121,11 @@ these variables: `### Features`, `### Bug fixes`, and `### Performance improvements`: ```yaml - --- - categories: - feature: Features - bug: Bug fixes - performance: Performance improvements + --- + categories: + feature: Features + bug: Bug fixes + performance: Performance improvements ``` ### Custom templates diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 161a698a48c..ea4c345a592 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -25,7 +25,7 @@ See the prerequisites below to add existing clusters to GitLab. To add any cluster to GitLab, you need: - Either a GitLab.com account or an account for a self-managed installation -running GitLab 12.5 or later. + running GitLab 12.5 or later. - The Maintainer role for group-level and project-level clusters. - Access to the Admin Area for instance-level clusters. - A Kubernetes cluster. @@ -48,7 +48,7 @@ To add an existing **EKS** cluster, you need: - An Amazon EKS cluster with worker nodes properly configured. - `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) -for access to the EKS cluster. + for access to the EKS cluster. - Ensure the token of the account has administrator privileges for the cluster. ### GKE clusters @@ -56,8 +56,8 @@ for access to the EKS cluster. To add an existing **GKE** cluster, you need: - The `container.clusterRoleBindings.create` permission to create a cluster -role binding. You can follow the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) -to grant access. + role binding. You can follow the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) + to grant access. ## How to add an existing cluster diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 940561d70d0..7d18ef0d1e4 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -39,7 +39,7 @@ When removing a cluster integration, you have two options: - **Remove integration**: remove only the Kubernetes integration. - **Remove integration and resources**: remove the cluster integration and -all GitLab cluster-related resources such as namespaces, roles, and bindings. + all GitLab cluster-related resources such as namespaces, roles, and bindings. To remove the Kubernetes cluster integration: diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 4fb6ecb1336..9e96438393e 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -40,8 +40,8 @@ For example, let's say the following Kubernetes clusters exist in a project: | Development | `*` | | Production | `production` | -And the following environments are set in -[`.gitlab-ci.yml`](../../../ci/yaml/index.md): +And the following environments are set in the +[`.gitlab-ci.yml` file](../../../ci/index.md#the-gitlab-ciyml-file): ```yaml stages: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 87467cbc56c..b861fe9d154 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -480,6 +480,23 @@ repository to be imported manually. Administrators can manually import the repos project.create_import_state if project.import_state.blank? # Set state to start project.import_state.force_start + + # Optional: If your import had certain optional stages selected or a timeout strategy + # set, you can reset them here. Below is an example. + # The params follow the format documented in the API: + # https://docs.gitlab.com/ee/api/import.html#import-repository-from-github + Gitlab::GithubImport::Settings + .new(project) + .write( + timeout_strategy: "optimistic", + optional_stages: { + single_endpoint_issue_events_import: true, + single_endpoint_notes_import: true, + attachments_import: true, + collaborators_import: true + } + ) + # Trigger import from second step Gitlab::GithubImport::Stage::ImportRepositoryWorker.perform_async(project.id) ``` diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index e604d9d871b..135b51bf81a 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The GitLab.com importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108502) in GitLab 15.8 and removed in GitLab 16.0. To import GitLab projects from GitLab.com to a self-managed GitLab instance use -[migrating groups and projects by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +[migrating groups and projects by direct transfer](../../group/import/index.md). ## Related topics diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 681174400a2..8c9ba408799 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -4,34 +4,61 @@ group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import and migrate projects **(FREE ALL)** +# Import and migrate groups and projects **(FREE ALL)** -If you want to bring existing projects to GitLab or copy GitLab projects to a different location, you can: +To bring existing projects to GitLab, or copy GitLab groups and projects to a different location, you can: -- Import projects from external systems using one of the [available importers](#available-project-importers). -- Migrate GitLab projects: - - Between two GitLab self-managed instances. - - Between a self-managed instance and GitLab.com in both directions. - - In the same GitLab instance. +- Migrate GitLab groups and projects by using direct transfer. +- Import from supported import sources. +- Import from other import sources. -For any type of source and target, you can migrate GitLab projects: +## Migrate from GitLab to GitLab by using direct transfer -- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), - which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in - [Beta](../../../policy/experiment-beta-support.md#beta). The feature is not ready for production use. -- Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network - connection between instances is required. +The best way to migrate GitLab groups and projects between GitLab instances, or in the same GitLab instance, is +[by using direct transfer](../../group/import/index.md). -If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). However, you can't -import issues and merge requests this way. To retain metadata like issues and merge requests, either: +You can also migrate GitLab projects by using a GitLab file export, which is a supported import source. -- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). - This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). It is not ready for production use. -- Use [file exports](../settings/import_export.md) to import projects. +## Supported import sources -Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). -When migrating from self-managed to GitLab.com, user associations (such as comment author) -are changed to the user who is importing the projects. +> All importers default to disabled for GitLab self-managed installations. This change was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118970) in GitLab 16.0. + +The import sources that are available to you by default depend on which GitLab you use: + +- GitLab.com: all available import sources are [enabled by default](../../gitlab_com/index.md#default-import-sources). +- GitLab self-managed: no import sources are enabled by default and must be + [enabled](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources). + +GitLab can import projects from these supported import sources. + +| Import source | Description | +|:----------------------------------------------|:------------| +| [Bitbucket Cloud](bitbucket.md) | Using [Bitbucket.org as an OmniAuth provider](../../../integration/bitbucket.md), import Bitbucket repositories. | +| [Bitbucket Server](bitbucket_server.md) | Import repositories from Bitbucket Server (also known as Stash). | +| [FogBugz](fogbugz.md) | Import FogBuz projects. | +| [Gitea](gitea.md) | Import Gitea projects. | +| [GitHub](github.md) | Import from either GitHub.com or GitHub Enterprise. | +| [GitLab export](../settings/import_export.md) | Migrate projects one by one by using a GitLab export file. | +| [Manifest file](manifest.md) | Upload a manifest file. | +| [Repository by URL](repo_by_url.md) | Provide a Git repository URL to create a new project from. | + +## Other import sources + +You can also read information on importing from these other import sources: + +- [ClearCase](clearcase.md) +- [Concurrent Versions System (CVS)](cvs.md) +- [Jira (issues only)](jira.md) +- [Perforce Helix](perforce.md) +- [Team Foundation Version Control (TFVC)](tfvc.md) + +### Import repositories from Subversion + +GitLab can not automatically migrate Subversion repositories to Git. Converting Subversion repositories to Git can be +difficult, but several tools exist including: + +- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and basic repositories. +- [`reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html), for larger and more complex repositories. ## Security @@ -49,35 +76,6 @@ GitLab self-managed administrators can reduce their attack surface by disabling In GitLab 16.1 and earlier, you should **not** use direct transfer with [scheduled scan execution policies](../../../user/application_security/policies/scan-execution-policies.md). -## Available project importers - -You can import projects from: - -- [Bitbucket Cloud](bitbucket.md) -- [Bitbucket Server (also known as Stash)](bitbucket_server.md) -- [ClearCase](clearcase.md) -- [CVS](cvs.md) -- [FogBugz](fogbugz.md) -- [GitHub.com or GitHub Enterprise](github.md) -- [Gitea](gitea.md) -- [Perforce](perforce.md) -- [TFVC](tfvc.md) -- [Repository by URL](repo_by_url.md) -- [Uploading a manifest file (AOSP)](manifest.md) -- [Jira (issues only)](jira.md) - -You can also import any Git repository through HTTP from the **New Project** page. If the repository -is too large, the import can timeout. - -You can then [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). - -## Import from Subversion - -GitLab can not automatically migrate Subversion repositories to Git. Converting Subversion repositories to Git can be difficult, but several tools exist including: - -- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and basic repositories. -- [`reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html), for larger and more complex repositories. - ## Migrate using the API To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/rest/index.md). diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5d67d10582d..3c5a40b8d27 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -6,7 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import project from repository by URL **(FREE ALL)** -You can import your existing repositories by providing the Git URL. +You can import your existing repositories by providing the Git URL. You can't import GitLab issues and merge requests +this way. Other methods provide more complete import methods. + +If the repository is too large, the import can timeout. ## Prerequisites diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 8a91a0c4621..b7addb5131f 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -4,27 +4,28 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Insights for projects **(ULTIMATE ALL)** +# Insights **(ULTIMATE ALL)** -Configure project insights to explore data such as: +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. + +Configure insights for your projects and groups to explore data such as: - Issues created and closed during a specified period. - Average time for merge requests to be merged. - Triage hygiene. -Insights are also available for [groups](../../group/insights/index.md). +You can also create custom Insights reports that are relevant for your group. ## View project insights Prerequisites: -- You must have: - - Access to a project to view information about its merge requests and issues. - - Permission to view confidential merge requests and issues in the project. +- For project insights, you must have access to the project and permission to view information about its merge requests and issues. +- For group insights, you must have permission to view the group. -To view project insights: +To view insights for a project or group: -1. On the left sidebar, select **Search or go to** and find your project. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Insights**. 1. To view a report, select the **Select report** dropdown list. @@ -35,23 +36,61 @@ You can direct users to a specific report in Insights by using the deep-linked U To create a deep link, append the report key to the end of the Insights report URL. For example, a GitLab report with the key `bugsCharts` has the deep link URL `https://gitlab.com/gitlab-org/gitlab/insights/#/bugsCharts`. +## Interact with Insights charts + +You can interact with the insights charts to view details about your group's activity. + +### Display different reports + +To display one of the available reports on the insights page, from the **Select report** dropdown list, +select the report you want to display. + +### View bar chart annotations + +To view annotations, hover over each bar in the chart. + +### Zoom in on chart + +Insights display data from the last 90 days. You can zoom in to display data only from a subset of the 90-day range. + +To do this, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: + +- To change the start date, slide the left pause icon to the left or right. +- To change the end date, slide the right pause icon to the left or right. + +### Exclude dimensions from charts + +By default, insights display all available dimensions on the chart. + +To exclude a dimension, from the legend below the chart, select the name of the dimension. + +### Drill down on charts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372215/) in GitLab 16.7. + +You can drill down into the data of the **Bugs created per month by priority** and **Bugs created per month by severity** charts from the [default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). + +To view a drill-down report of the data for a specific priority or severity in a month: + +- On the chart, select the bar stack you want to drill down on. + ## Configure project insights Prerequisites: - Depending on your project configuration, you must have at least the Developer role. -Project insights are configured with the [`.gitlab/insights.yml`](#insights-configuration-file) file in the project. If a project doesn't have a configuration file, it uses the [group configuration](../../group/insights/index.md#configure-group-insights). +Project insights are configured with the [`.gitlab/insights.yml`](#insights-configuration-file) file in the project. If a project doesn't have a configuration file, it uses the [group configuration](#configure-group-insights). The `.gitlab/insights.yml` file is a YAML file where you define: - The structure and order of charts in a report. - The style of charts displayed in the report of your project or group. -To configure project insights, either: +To configure project insights, create a file `.gitlab/insights.yml` either: -- Create a `.gitlab/insights.yml` file locally in the root directory of your project, and push your changes. -- Create a `.gitlab/insights.yml` file in the UI: +- Locally, in the root directory of your project, and push your changes. +- From the UI: 1. On the left sidebar, select **Search or go to** and find your project. 1. Above the file list, select the branch you want to commit to, select the plus icon, then select **New file**. 1. In the **File name** text box, enter `.gitlab/insights.yml`. @@ -59,7 +98,21 @@ To configure project insights, either: 1. Select **Commit changes**. After you create the configuration file, you can also -[use it for the project's group](../../group/insights/index.md#configure-group-insights). +use it for the project's group. + +## Configure group insights + +GitLab reads insights from the +[default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). + +To configure group insights: + +1. In a project that belongs to your group, [create a `.gitlab/insights.yml` file](#configure-project-insights). +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand **Analytics** and find the **Insights** section. +1. Select the project that contains your `.gitlab/insights.yml` configuration file. +1. Select **Save changes**. ## Insights configuration file @@ -403,7 +456,7 @@ Use `query.environment_tiers` to define an array of environments to include the Use `projects` to limit where issuables are queried from: -- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-group-insights), use `projects` to define the projects from which to query issuables. By default, all projects under the group are used. +- If `.gitlab/insights.yml` is used for a group's insights, use `projects` to define the projects from which to query issuables. By default, all projects under the group are used. - If `.gitlab/insights.yml` is used for a project's insights, specifying other projects does not yield results. By default, the project is used. #### `projects.only` diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 3031ae42e4d..18022fbaeb8 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -16,19 +16,20 @@ The feature is still in development, but you can: - [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). - [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). -With the Apple App Store Connect integration, you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. +Use the Apple App Store Connect integration to configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com). +With this integration, you can build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. The Apple App Store Connect integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. -## Prerequisites +## Enable the integration in GitLab -An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.com/programs/enroll/) is required to enable this integration. +Prerequisites: -## Configure GitLab +- You must have an Apple ID enrolled in the [Apple Developer Program](https://developer.apple.com/programs/enroll/). +- You must [generate a new private key](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api) for your project in the Apple App Store Connect portal. -GitLab supports enabling the Apple App Store Connect integration at the project level. Complete these steps in GitLab: +To enable the Apple App Store Connect integration in GitLab: -1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Apple App Store Connect**. @@ -38,7 +39,6 @@ GitLab supports enabling the Apple App Store Connect integration at the project - **Key ID**: The key ID of the generated private key. - **Private key**: The generated private key. You can download this key only once. - **Protected branches and tags only**: Enable to set variables on protected branches and tags only. - 1. Select **Save changes**. After you enable the integration: diff --git a/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md index 363e7c2c364..3a1bc746d5b 100644 --- a/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md +++ b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md @@ -10,13 +10,13 @@ When configuring the GitLab for Slack app on GitLab.com, you might encounter the For self-managed GitLab, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md#troubleshooting). -## The app does not appear in the list of integrations +## App does not appear in the list of integrations The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../../administration/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). -## Project or alias not found +## `Project or alias not found` Some Slack commands must have a project full path or alias and fail with the following error if the project cannot be found: @@ -31,18 +31,19 @@ To resolve this issue, ensure: - If using a [project alias](gitlab_slack_application.md#create-a-project-alias-for-slash-commands), the alias is correct. - The GitLab for Slack app is [enabled for the project](gitlab_slack_application.md#from-project-integration-settings). -## Slash commands return an error in Slack +## Slash commands return `dispatch_failed` in Slack Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. + To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../../administration/settings/slack_app.md) on your self-managed instance. -## Notifications are not received to a channel +## Notifications not received to a channel If you're not receiving notifications to a Slack channel, ensure: - The channel name you configured is correct. - If the channel is private, you've [added the GitLab for Slack app to the channel](gitlab_slack_application.md#receive-notifications-to-a-private-channel). -## The App Home does not display properly +## App Home does not display properly If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](gitlab_slack_application.md#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 70a1fe5b054..cfe48d11bcb 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -34,7 +34,7 @@ To enable the Google Play integration in GitLab: 1. Select **Google Play**. 1. In **Enable integration**, select the **Active** checkbox. 1. In **Package name**, enter the package name of the app (for example, `com.gitlab.app_name`). -1. Optional. Under **Protected branches and tags only**, select the **Only set variables on protected branches and tags** checkbox. +1. Optional. Under **Protected branches and tags only**, select the **Set variables on protected branches and tags only** checkbox. 1. In **Service account key (.JSON)**, drag or upload your key file. 1. Optional. Select **Test settings**. 1. Select **Save changes**. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 0a82a94d998..91c8e9ce2f1 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -19,8 +19,8 @@ To use the Mattermost integration you must create an incoming webhook integratio in Mattermost: 1. Sign in to your Mattermost instance. -1. [Enable incoming webhooks](https://docs.mattermost.com/developer/webhooks-incoming.html#enabling-incoming-webhooks). -1. [Add an incoming webhook](https://docs.mattermost.com/developer/webhooks-incoming.html#creating-integrations-using-incoming-webhooks). +1. [Enable incoming webhooks](https://docs.mattermost.com/configure/integrations-configuration-settings.html#enable-incoming-webhooks). +1. [Add an incoming webhook](https://developers.mattermost.com/integrate/webhooks/incoming/#create-an-incoming-webhook). 1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it and copy the **Webhook URL** because we need this later for GitLab. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 9b92fa35e24..fee6de2af6d 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) in GitLab 15.9 -and is planned for removal in 17.0. Use the [GitLab for Slack app](gitlab_slack_application.md) instead. +and is planned for removal in 18.0. Use the [GitLab for Slack app](gitlab_slack_application.md) instead. This change is a breaking change. The Slack notifications integration enables your GitLab project to send events diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 33da78191c0..ccf416fc8c6 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,6 +1,7 @@ --- stage: Manage group: Import and Integrate +description: Custom HTTP callbacks, used to send events. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e6fd302e4f0..39353480908 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -101,7 +101,7 @@ For examples of using issue boards along with [epics](../group/epics/index.md), - [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -[Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) + [Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) ### Use cases for a single issue board diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 6f2d0083ae8..b80db3887bf 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -355,7 +355,7 @@ To delete an issue: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. -1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). +1. In the upper-right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Delete issue**. Alternatively: @@ -367,23 +367,44 @@ Alternatively: ## Promote an issue to an epic **(PREMIUM ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. -> - Moved from GitLab Ultimate to GitLab Premium in 12.8. -> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab 13.6. - You can promote an issue to an [epic](../../group/epics/index.md) in the immediate parent group. +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, and comment threads. +- Upvotes and downvotes. +- Participants. +- Group labels that the issue had. +- Parent epic. + +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. + To promote an issue to an epic: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. -1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). +1. In the upper-right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Promote to epic**. Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). -Read more about [promoting an issues to epics](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). - ## Promote an issue to an incident > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 2cc38e6a31c..f064d867e0f 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -14,7 +14,7 @@ you're interested in. Labels are a key part of [issue boards](issue_board.md). With labels you can: - Categorize [epics](../group/epics/index.md), issues, and merge requests using colors and descriptive titles like -`bug`, `feature request`, or `docs`. + `bug`, `feature request`, or `docs`. - Dynamically filter and manage [epics](../group/epics/index.md), issues, and merge requests. - Search lists of issues, merge requests, and epics, as well as issue boards. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 92aaee1ae54..66258c3873e 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -59,6 +59,7 @@ Prerequisites: - You must have the Owner or Maintainer role. - [Group membership lock](../../group/access_and_permissions.md#prevent-members-from-being-added-to-projects-in-a-group) must be disabled. +- If [sign-up is disabled](../../../administration/settings/sign_up_restrictions.md#disable-new-sign-ups), an administrator must add the user by email first. To add a user to a project: @@ -156,6 +157,7 @@ To add a group to a project: The invited group is displayed on the **Groups** tab. Private groups are masked from unauthorized users. +With the feature flag `allow_members_to_see_invited_groups_in_access_dropdowns` enabled, private groups are displayed in project settings for protected branches, protected tags, and protected environments. The members of the invited group are not displayed on the **Members** tab. The **Members** tab shows: diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 3881220ec7a..bf8a7468199 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -16,7 +16,7 @@ For a project that was created by `Group 1`: - The members of `Group 1` have access to the project. - The owner of `Group 1` can invite `Group 2` to the project. -This way, members of both `Group 1` and `Group 2` have access to the shared project. + This way, members of both `Group 1` and `Group 2` have access to the shared project. ## Prerequisites @@ -31,7 +31,7 @@ In addition: - You must be a member of the group or the subgroup being invited. - The [visibility level](../../public_access.md) of the group you're inviting -must be at least as restrictive as that of the project. For example, you can invite: + must be at least as restrictive as that of the project. For example, you can invite: - A _private_ group to a _private_ project - A _private_ group to an _internal_ project. - A _private_ group to a _public_ project. @@ -46,12 +46,9 @@ must be at least as restrictive as that of the project. For example, you can inv ## Share a project with a group -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal - window [with a flag](../../feature_flags.md). Disabled by default. -> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) - in GitLab 14.8. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. - [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. Similar to how you [share a group with another group](../../group/manage.md#share-a-group-with-another-group), you can share a project with a group by inviting that group to the project. @@ -101,6 +98,15 @@ NOTE: The Max role does not elevate the privileges of users. For example, if a group member has the role of Developer, and the group is invited to a project with a Max role of Maintainer, the member's role is not elevated to Maintainer. +### Which roles you can assign + +In GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233408) and later, the maximum role you can assign depends on whether you have the Owner or Maintainer role for the project. The maximum role you can set is: + +- Owner (`50`), if you have the Owner role for the project. +- Maintainer (`40`), if you have the Maintainer role for the project. + +In GitLab 16.6 and earlier, the maximum role you can assign to an invited group is Maintainer (`40`). + ### View the member's Max role To view the maximum role assigned to a member: diff --git a/doc/user/project/merge_requests/approvals/img/group_access_example_01_v16_8.png b/doc/user/project/merge_requests/approvals/img/group_access_example_01_v16_8.png Binary files differnew file mode 100644 index 00000000000..0b5fbf7e075 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/group_access_example_01_v16_8.png diff --git a/doc/user/project/merge_requests/approvals/img/group_access_example_02_v16_8.png b/doc/user/project/merge_requests/approvals/img/group_access_example_02_v16_8.png Binary files differnew file mode 100644 index 00000000000..49df19f2c46 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/group_access_example_02_v16_8.png diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 5436edf9f8d..bf4e2e8334e 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -17,15 +17,13 @@ flexibility: - Create required [rules](rules.md) about the number and type of approvers before work can merge. - Specify a list of users who act as [code owners](../../codeowners/index.md) for specific files, and require their approval before work can merge. +- For GitLab Premium and GitLab Ultimate, configure approvals + [for the entire instance](../../../../administration/merge_requests_approvals.md). You can configure merge request approvals on a per-project basis, and some approvals can be configured [on the group level](../../../group/manage.md#group-merge-request-approval-settings). Support for group-level settings for merge request approval rules is tracked in this -[epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). Administrators of -[GitLab Premium](https://about.gitlab.com/pricing/) and -[GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances -can also configure approvals -[for the entire instance](../../../../administration/admin_area.md). +[epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). ## How approvals work @@ -48,6 +46,8 @@ You can also configure: - Merge request approval rules and settings through the GitLab UI or with the [Merge request approvals API](../../../../api/merge_request_approvals.md). +Approvals cannot be added after a merge request is merged. + ## Approve a merge request When an [eligible approver](rules.md#eligible-approvers) visits an open merge request, @@ -60,9 +60,8 @@ GitLab displays one of these buttons after the body of the merge request: Eligible approvers can also use the `/approve` [quick action](../../../project/quick_actions.md) when adding a comment to -a merge request. [In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), -if a user approves a merge request and is shown in the reviewer list, a green check mark -(**{check-circle-filled}**) displays next to their name. +a merge request. Users in the reviewer list who have approved a merge request display +a green check mark (**{check-circle-filled}**) next to their name. After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, @@ -80,8 +79,6 @@ of the rule. ## Optional approvals -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. - GitLab allows all users with Developer or greater [permissions](../../../permissions.md) to approve merge requests. Approvals in GitLab Free are optional, and don't prevent a merge request from merging without approval. @@ -128,7 +125,7 @@ Invalid approval rules created through a scan result policy are presented with ## Related topics - [Merge request approvals API](../../../../api/merge_request_approvals.md) -- [Instance-level approval rules](../../../../administration/admin_area.md) for self-managed installations +- [Instance-level approval rules](../../../../administration/merge_requests_approvals.md) for self-managed installations <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index c284df8d9aa..2f1e2a96295 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -16,7 +16,10 @@ You can define approval rules: - [As project defaults](#add-an-approval-rule). - [Per merge request](#edit-or-override-merge-request-approval-rules). -- [At the instance level](../../../../administration/admin_area.md) + +You can configure approval rules: + +- [At the instance level](../../../../administration/merge_requests_approvals.md). If you don't define a [default approval rule](#add-an-approval-rule), any user can approve a merge request. Even if you don't define a rule, you can still @@ -311,8 +314,18 @@ For more information about this validation error, read ### Groups need explicit or inherited Developer role on a project A group created to handle approvals may be created in a different area of the -project hierarchy than the project requiring review. If this happens, the approvals group -isn't recognized as a valid Code Owner for the project, nor does it display in the -project's **Approvals** list. To fix this problem, add the approval group as a shared group -high enough in the shared hierarchy so the project requiring review inherits this -group of users. +project hierarchy than the project requiring review. If this happens, members of the +group may not be able to approve the merge request as they do not have access to it. + +For example: + +In the group structure below, project 1 belongs to subgroup 1 and subgroup 4 has users. + + + +Project 1 has a project level approval rule which assigns subgroup 4 as approvers. +When a merge request is created approvers from subgroup 4 appear in the eligible approvers list. +However, as users from subgroup 4 do not have permission to view the merge request, the `404` error is returned. +To grant membership, the group must be invited as a project member. It is now possible for users from subgroup 4 to approve. + + diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index f9e40a6714c..0120be0cf17 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -57,7 +57,7 @@ this setting, unless you configure one of these options: - [Prevent overrides of default approvals](#prevent-editing-approval-rules-in-merge-requests) at the project level. - *(Self-managed instances only)* Prevent overrides of default approvals - [at the instance level](../../../../administration/admin_area.md). When configured + [at the instance level](../../../../administration/merge_requests_approvals.md). When configured at the instance level, you can't edit this setting at the project or individual merge request levels. @@ -68,7 +68,7 @@ this setting, unless you configure one of these options: > - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131778) removed in GitLab 16.5. This check now includes merge commits. By default, users who commit to a merge request can still approve it. At both -the project level or [instance level](../../../../administration/admin_area.md), +the project level or instance level, you can prevent committers from approving merge requests that are partially their own. To do this: @@ -76,7 +76,7 @@ their own. To do this: 1. In the **Merge request approvals** section, scroll to **Approval settings** and select **Prevent approvals by users who add commits**. If this checkbox is cleared, an administrator has disabled it - [at the instance level](../../../../administration/admin_area.md), and + [at the instance level](../../../../administration/merge_requests_approvals.md), and it can't be changed at the project level. 1. Select **Save changes**. @@ -116,10 +116,11 @@ When this field is changed, it can affect all open merge requests depending on t > - Requiring re-authentication by using SAML authentication for GitLab.com groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default. > - Requiring re-authentication by using SAML authentication for self-managed instances [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431415) in GitLab 16.7 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default. +> - [Enabled `ff_require_saml_auth_to_approve` by default](https://gitlab.com/gitlab-org/gitlab/-/issues/431714) in GitLab 16.8 for GitLab.com and self-managed instances. FLAG: -On self-managed GitLab, by default requiring re-authentication by using SAML authentication is not available. To make it available, an administrator can -[enable the feature flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. On GitLab.com, this feature is not available. +On self-managed GitLab, by default requiring re-authentication by using SAML authentication is available. To hide the feature, an administrator can +[disable the feature flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. On GitLab.com, this feature is available. You can force potential approvers to first authenticate with either: @@ -184,7 +185,7 @@ To do this: You can also enforce merge request approval settings: -- At the [instance level](../../../../administration/admin_area.md), which apply to all groups +- At the [instance level](../../../../administration/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all projects. - On a [top-level group](../../../group/manage.md#group-merge-request-approval-settings), which apply to all subgroups and projects. @@ -194,6 +195,6 @@ that inherited them. ## Related topics -- [Instance-level merge request approval settings](../../../../administration/admin_area.md) +- [Instance-level merge request approval settings](../../../../administration/merge_requests_approvals.md) - [Compliance center](../../../compliance/compliance_center/index.md) - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 780041ac411..094d2cf5730 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -162,6 +162,13 @@ per conflicted file on the merge request diff:  +## Show scanner findings in diff **(ULTIMATE ALL)** + +You can show scanner findings in the diff. For details, see: + +- [Code Quality findings](../../../ci/testing/code_quality.md#merge-request-changes-view) +- [Static Analysis findings](../../application_security/sast/index.md#merge-request-changes-view) + ## Add a comment to a merge request file > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123515) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `comment_on_files`. Enabled by default. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 951c848dee1..d2c5b0af339 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -155,23 +155,50 @@ You can create a merge request by running Git commands on your local machine. You can create a merge request from your fork to contribute back to the main project. -1. On the left sidebar, select **Search or go to** and find your project. -1. Select your fork of the repository. -1. On the left sidebar, select **Code > Merge requests**, and select **New merge request**. -1. In the **Source branch** dropdown list box, select the branch in your forked repository as the source branch. -1. In the **Target branch** dropdown list box, select the branch from the upstream repository as the target branch. - You can set a [default target project](#set-the-default-target-project) to - change the default target branch (which can be useful if you are working in a - forked project). +1. On the left sidebar, select **Search or go to** and find your fork. +1. Select **Code > Merge requests**, and select **New merge request**. +1. For **Source branch**, select the branch in your fork that contains your changes. +1. For **Target branch**: + + 1. Select the target project. (Make sure to select the upstream project, rather than your fork.) + 1. Select a branch from the upstream repository. + + NOTE: + If you contribute changes upstream frequently, consider setting a + [default target project](#set-the-default-target-project) for your fork. + 1. Select **Compare branches and continue**. -1. Select **Create merge request**. +1. Select **Create merge request**. The merge request is created in the target project, + not your fork. -After your work is merged, if you don't intend to -make any other contributions to the upstream project, you can -[unlink your fork](../repository/forking_workflow.md#unlink-a-fork) from its upstream project. +After your work merges, [unlink your fork](../repository/forking_workflow.md#unlink-a-fork) +from its upstream project if you don't intend to make more contributions. For more information, [see the forking workflow documentation](../repository/forking_workflow.md). +### Set the default target project + +By default, merge requests originating from a fork target your fork, not the upstream project. +If you frequently contribute back to the upstream project, and want to target it +by default, change the default target for your fork. + +Prerequisites: + +- You're working in a fork. +- You must have at least the Developer role, or be allowed to create merge requests in the project. +- The upstream project allows merge requests to be created. +- The [visibility settings](../../public_access.md#change-project-visibility) for + the fork must match, or be less strict than, the upstream repository. For example: + this setting isn't shown if your fork is private, but the upstream is public. + +To do this: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > Merge requests**. +1. In the **Target project** section, select the option you want to use for + your default target project. +1. Select **Save changes**. + ## By sending an email You can create a merge request by sending an email message to GitLab. @@ -179,60 +206,41 @@ The merge request target branch is the project's default branch. Prerequisites: +- The merge request must target the current project, not an upstream project. - A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md). - A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md). +- You must have at least the Developer role, or be allowed to create merge requests in the project. To create a merge request by sending an email: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. -1. In the upper-right corner, select **Email a new merge request to this project**. - An email address is displayed. Copy this address. - Ensure you keep this address private. +1. If the project contains any merge requests, select **Email a new merge request to this project**. +1. In the dialog, copy the email address shown. Keep this address private. Anyone who + has it can create issues or merge requests as if they were you. 1. Open an email and compose a message with the following information: - The **To** line is the email address you copied. - - The subject line is the source branch name. - - The message body is the merge request description. + - The **Subject** is the source branch name. + - The body of the email is the merge request description. -1. Send the email message. +1. To add commits, attach `.patch` files to the message. +1. Send the email. A merge request is created. ### Add attachments when creating a merge request by email -You can add commits to a merge request by adding -patches as attachments to the email. All attachments with a file name ending in `.patch` are considered patches and are processed -ordered by name. +Add commits to a merge request by adding patches as attachments to the email. -The combined size of the patches can be 2 MB. - -If the source branch from the subject does not exist, it is -created from the repository's HEAD or the specified target branch. -You can specify the target branch by using the -[`/target_branch` quick action](../quick_actions.md). If the source -branch already exists, the patches are applied on top of it. - -## Set the default target project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58093) in GitLab 13.11. - -Merge requests have a source and a target project that are the same, unless -forking is involved. Creating a fork of the project can cause either of these -scenarios when you create a new merge request: - -- You target an upstream project (the project you forked, and the default - option). -- You target your own fork. - -To have merge requests from a fork by default target your own fork -(instead of the upstream project), you can change the default. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > Merge requests**. -1. In the **Target project** section, select the option you want to use for - your default target project. -1. Select **Save changes**. +- The combined size of the patches must be 2 MB or less. +- To be considered a patch, the attachment's file name must end in `.patch`. +- Patches are processed in order by name. +- If the source branch from the subject does not exist, it is + created from the repository's `HEAD`, or the default target branch. + To change the target branch manually, use the + [`/target_branch` quick action](../quick_actions.md). +- If the source branch already exists, patches are applied on top of it. ## Troubleshooting @@ -249,3 +257,14 @@ To make this button appear, one possible workaround is to [remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork). After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks. + +### Email message could not be processed + +When sending an email to create a merge request, and you attempt to target an +upstream project, GitLab responds with this error: + +```plaintext +Unfortunately, your email message to GitLab could not be processed. + +You are not allowed to perform this action. If you believe this is in error, contact a staff member. +``` diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index a9cad78449b..3a2729bd64b 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -23,6 +23,9 @@ author can either retry any failed jobs, or push new commits to fix the failure: - If a retried job succeeds on the second try, the merge request is merged. - If new commits are added to the merge request, GitLab cancels the request to ensure the new changes are reviewed before merge. +- If new commits are added to the target branch of the merge request and + fast-forward only merge request is configured, GitLab cancels the request + to prevent merge conflicts. ## Auto-merge a merge request diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 23b1207619e..78e4c19dd57 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -19,6 +19,7 @@ review merge requests in Visual Studio Code. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Merge request review](https://www.youtube.com/watch?v=2MayfXKpU08&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=183). +<!-- Video published on 2023-04-29 --> ## GitLab Duo Suggested Reviewers **(ULTIMATE SAAS)** @@ -31,6 +32,7 @@ GitLab uses machine learning to suggest reviewers for your merge request. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab Duo Suggested Reviewers](https://www.youtube.com/embed/ivwZQgh4Rxw). +<!-- Video published on 2023-11-03 --> To suggest reviewers, GitLab uses: diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index d60bd660b53..a6680e5e4f4 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -73,3 +73,9 @@ If you have configured [License Compliance](../../compliance/license_scanning_of If you have configured [external status checks](status_checks.md) you can see the status of these checks in merge requests [in a specific widget](status_checks.md#status-checks-widget). + +## Application security scanning + +If you have enabled any application security scanning tools, the results are shown in the security +scanning widget. For more information, see +[security scanning output in merge request widget](../../application_security/index.md#merge-request). diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index a959507b338..f4df178794d 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -142,7 +142,7 @@ To edit a milestone: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. 1. Select a milestone's title. -1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**. +1. In the upper-right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**. 1. Edit the title, start date, due date, or description. 1. Select **Save changes**. @@ -159,7 +159,7 @@ To edit a milestone: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. 1. Select a milestone's title. -1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Delete**. +1. In the upper-right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Delete**. 1. Select **Delete milestone**. ## Promote a project milestone to a group milestone diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md index 35972f0ad7f..1522fd8e4fc 100644 --- a/doc/user/project/ml/experiment_tracking/mlflow_client.md +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -39,6 +39,9 @@ To use MLflow client compatibility from a local environment: 1. If the training code contains the call to `mlflow.set_tracking_uri()`, remove it. +In the model registry, you can copy the tracking URI from the overflow menu in the top right +by selecting the vertical ellipsis (**{ellipsis_v}**). + ## Model experiments When running the training code, MLflow client can be used to create experiments, runs, @@ -141,11 +144,22 @@ description = 'Model version description' model_version = client.create_model_version(model_name, source="", description=description) ``` +If the version parameter is not passed, it will be auto-incremented from the latest uploaded +version. You can set the version by passing a tag during model version creation. The version +must follow [SemVer](https://semver.org/) format. + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +tags = { "gitlab.version" = version } +client.create_model)version(model_name, version, description=description, tags=tags) +``` + **Notes** - Argument `run_id` is ignored. Every model version behaves as a Candidate/Run. Creating a mode version from a run is not yet supported. - Argument `source` is ignored. GitLab will create a package location for the model version files. -- Argument `tags` is ignored. - Argument `run_link` is ignored. - Argument `await_creation_for` is ignored. diff --git a/doc/user/project/ml/model_registry/index.md b/doc/user/project/ml/model_registry/index.md index 492ec9940ab..026afc01f22 100644 --- a/doc/user/project/ml/model_registry/index.md +++ b/doc/user/project/ml/model_registry/index.md @@ -29,13 +29,14 @@ at least the [Reporter role](../../../permissions.md#roles) to modify or delete ## Exploring models, model versions and model candidates -Model registry can be accessed on `https/<your-project>-/ml/models`. +To access the model registry, from the left sidebar, select **Deploy > Model registry**. ## Creating machine learning models and model versions Models and model versions can be created using the [MLflow](https://www.mlflow.org/docs/latest/tracking.html) client compatibility. -See [MLflow client compatibility](../experiment_tracking/mlflow_client.md#model-registry) on how to -create and manage models and model versions. +For more information about how to create and manage models and model versions, see [MLflow client compatibility](../experiment_tracking/mlflow_client.md#model-registry). +You can also create models directly on GitLab by selecting **Create Model** +on the Model registry page. ## Upload files, log metrics, log parameters to a model version diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index d41825af613..1371f5e77d0 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -1,6 +1,7 @@ --- stage: Data Stores group: Tenant Scale +description: Project visibility, search, badges, layout. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/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 345a30da198..b34369cb3b7 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 @@ -47,7 +47,7 @@ this document for an [overview on DNS records](dns_concepts.md). To add your custom domain to GitLab Pages: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. In the upper-right corner, select **New Domain**. 1. In **Domain**, enter the domain name. 1. Optional. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). You can also add the certificate and key later. @@ -158,7 +158,7 @@ If you're using Cloudflare, check After you have added all the DNS records: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). @@ -287,7 +287,7 @@ domain (as long as you've set a valid certificate for it). To enable this setting: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Select the **Force HTTPS (requires valid certificates)** checkbox. 1. Select **Save changes**. 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 9de2703b82b..73583eefdda 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -70,7 +70,7 @@ This specific Ruby image is maintained on [DockerHub](https://hub.docker.com/_/r Edit your `.gitlab-ci.yml` file and add this text as the first line: ```yaml -image: ruby:2.7 +image: ruby:3.2 ``` If your SSG needs [NodeJS](https://nodejs.org/) to build, you must specify an @@ -156,7 +156,7 @@ pages: Your `.gitlab-ci.yml` file should now look like this: ```yaml -image: ruby:2.7 +image: ruby:3.2 pages: script: @@ -185,7 +185,7 @@ GitLab Pages daemon. GitLab runs it in the background and doesn't use a runner. ## Other options for your CI/CD file If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file -with [any of the available settings](../../../../ci/yaml/index.md). You can validate +with [other CI/CD YAML keywords](../../../../ci/yaml/index.md). You can validate your `.gitlab-ci.yml` file with the [CI Lint](../../../../ci/lint.md) tool that's included with GitLab. The following topics show other examples of other options you can add to your CI/CD file. @@ -198,7 +198,7 @@ First, add a `workflow` section to force the pipeline to run only when changes a pushed to branches: ```yaml -image: ruby:2.7 +image: ruby:3.2 workflow: rules: @@ -218,7 +218,7 @@ Then configure the pipeline to run the job for the [default branch](../../repository/branches/default.md) (here, `main`) only. ```yaml -image: ruby:2.7 +image: ruby:3.2 workflow: rules: @@ -249,7 +249,7 @@ To specify a stage for your job to run in, add a `stage` line to your CI file: ```yaml -image: ruby:2.7 +image: ruby:3.2 workflow: rules: @@ -273,7 +273,7 @@ Now add another job to the CI file, telling it to test every push to every branch **except** the `main` branch: ```yaml -image: ruby:2.7 +image: ruby:3.2 workflow: rules: @@ -325,7 +325,7 @@ for both jobs, `pages` and `test`. Move these commands to a `before_script` section: ```yaml -image: ruby:2.7 +image: ruby:3.2 workflow: rules: @@ -366,7 +366,7 @@ This example caches Jekyll dependencies in a `vendor` directory when you run `bundle install`: ```yaml -image: ruby:2.7 +image: ruby:3.2 workflow: rules: diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index d658a09e760..00dfe0c66d9 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -226,7 +226,7 @@ Some other examples of mixing [variables](../../../ci/variables/index.md) with s ### Use multiple deployments to create pages environments -You can use multiple GitLap Pages deployments to create a new [environment](../../../ci/environments/index.md). +You can use multiple GitLab Pages deployments to create a new [environment](../../../ci/environments/index.md). For example: ```yaml diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 42a05e0b1bb..9f40b4d64af 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -133,8 +133,8 @@ pages: artifacts: paths: - public - only: - - main + rules: + - if: $CI_COMMIT_BRANCH == "main" ``` ### `.gitlab-ci.yml` for a static site generator @@ -145,7 +145,7 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit -the `pages` job with the [`only` parameter](../../../ci/yaml/index.md#only--except), +the `pages` job with [`rules:if`](../../../ci/yaml/index.md#rulesif), whenever a new commit is pushed to a branch used specifically for your pages. @@ -175,8 +175,8 @@ pages: artifacts: paths: - public - only: - - pages + rules: + - if: '$CI_COMMIT_REF_NAME == "pages"' ``` See an example that has different files in the [`main` branch](https://gitlab.com/pages/jekyll-branched/tree/main) diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 1c7aa0f182c..07b41f391ba 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -48,7 +48,8 @@ can access the website. To sign out of your GitLab Pages website, revoke the application access token for GitLab Pages: -1. In the top menu, select your profile, and then select **Settings**. -1. On the left sidebar, select **Applications**. -1. Scroll to the **Authorized applications** section, find the **GitLab Pages** - entry, and select its **Revoke** button. +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **Applications**. +1. In the **Authorized applications** section, find the **GitLab Pages** + entry, and select **Revoke**. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index d13f30060e7..b88e7d2d376 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -26,7 +26,7 @@ are supported. | Rewrites (other than `200`) | **{dotted-circle}** No | `/en/* /en/404.html 404` | | Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` | | Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` | -| Domain-level redirects | **{dotted-circle}** No | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | +| [Domain-level redirects](#domain-level-redirects) | **{check-circle}** Yes | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | | Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | | Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | @@ -119,6 +119,31 @@ request matches the `from`: This status code can be used in combination with [splat rules](#splats) to dynamically rewrite the URL. +## Domain-level redirects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/936) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `FF_ENABLE_DOMAIN_REDIRECT`. Disabled by default. + +To create a domain-level redirect, add a domain-level path (beginning with `http://` +or `https://`) to either: + +- The `to` path only. +- The `from` and `to` paths. + +The supported [HTTP status codes](#http-status-codes) are `301` and `302`: + +```plaintext +# 301 permanent redirect +http://blog.example.com/file_1.html https://www.example.com/blog/file_1.html 301 +/file_2.html https://www.example.com/blog/file_2.html 301 + +# 302 temporary redirect +http://blog.example.com/file_3.html https://www.example.com/blog/file_3.html 302 +/file_4.html https://www.example.com/blog/file_4.html 302 +``` + +Domain-level redirects can be used in combination with [splat rules](#splats) (including splat placeholders) +to dynamically rewrite the URL path. + ## Splats > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 0377ab389a5..60b862a4d3b 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -395,6 +395,6 @@ third-party Git clients. ### Branch names are case-sensitive -Branch names in `git` are case-sensitive. When configuring your protected branch -or [target branch rule](repository/branches/index.md#configure-rules-for-target-branches), +Branch names in `git` are case-sensitive. When configuring your protected branch, +or your [target branch workflow](repository/branches/index.md#configure-workflows-for-target-branches), `dev` is not the same `DEV` or `Dev`. diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 6c31b2ad5d3..1d721d71444 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -70,7 +70,7 @@ You should create a release as one of the last steps in your CI/CD pipeline. Prerequisites: - You must have at least the Developer role for a project. For more information, read -[Release permissions](#release-permissions). + [Release permissions](#release-permissions). To create a release in the Releases page: diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index c74ebaab89d..7c45a510877 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -50,7 +50,8 @@ A release contains the following types of assets: ### Source code GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` -archived source code from the given Git tag. These are read-only assets. +archived source code from the given Git tag. These assets are read-only, +and [can be downloaded](../repository/index.md#download-the-code-in-a-repository). ### Links diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index cf46774741c..b37a2c5fc0f 100644 --- a/doc/user/project/remote_development/connect_machine.md +++ b/doc/user/project/remote_development/connect_machine.md @@ -4,7 +4,7 @@ group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Connect a remote machine to the Web IDE **(FREE ALL BETA)** +# Tutorial: Connect a remote machine to the Web IDE **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. @@ -13,9 +13,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. -WARNING: -This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. - This tutorial shows you how to: - Create a development environment outside of GitLab. diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index ac8d7102e40..65445e54949 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -4,7 +4,7 @@ group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Remote development **(FREE ALL BETA)** +# Remote development **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. @@ -13,9 +13,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. -WARNING: -This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. - You can use remote development to write and compile code hosted on GitLab. With remote development, you can: diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 0a0cbcbb9c8..d6bcae57322 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -35,7 +35,7 @@ To create a new branch from the GitLab UI: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. -1. On the top right, select **New branch**. +1. In the upper-right corner, select **New branch**. 1. Enter a **Branch name**. 1. In **Create from**, select the base of your branch: an existing branch, an existing tag, or a commit SHA. @@ -283,62 +283,64 @@ To do this: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. -1. On the upper right corner of the page, select **More** **{ellipsis_v}**. +1. In the upper right corner of the page, select **More** **{ellipsis_v}**. 1. Select **Delete merged branches**. 1. In the dialog, enter the word `delete` to confirm, then select **Delete merged branches**. -## Configure rules for target branches **(PREMIUM ALL)** +## Configure workflows for target branches **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127115) in GitLab 16.4 [with a flag](../../../../administration/feature_flags.md) named `target_branch_rules_flag`. Enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136431) in GitLab 16.7. Some projects use multiple long-term branches for development, like `develop` and `qa`. In these projects, you might want to keep `main` as the default branch, but expect -merge requests to target `develop` or `qa` instead. Target branch rules help ensure +merge requests to target `develop` or `qa` instead. Target branch workflows help ensure merge requests target the appropriate development branch for your project. -When you create a merge request, the rule checks the name of the branch. If the -branch name matches the rule, the merge request targets the branch you specify -in the rule. If the branch name does not match, the merge request targets the +When you create a merge request, the workflow checks the name of the branch. If the +branch name matches the workflow, the merge request targets the branch you specify. If the branch name does not match, the merge request targets the default branch of the project. +Rules are processed on a "first-match" basis - if two rules match the same branch name, the top-most rule is applied. + Prerequisites: - You must have at least the Maintainer role. -To create a target branch rule: +To create a target branch workflow: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. -1. Select **Add target branch rule**. -1. For **Rule name**, provide a string or wild card to compare against branch names. -1. Select the **Target branch** to use when the branch name matches the **Rule name**. +1. Scroll down to **Merge request branch workflow** +1. Select **Add branch target**. +1. For **Branch name pattern**, provide a string or wild card to compare against branch names. +1. Select the **Target branch** to use when the branch name matches the **Branch name pattern**. 1. Select **Save**. ### Example -You could configure your project to have the following target branch rules: +You could configure your project to have the following target branch workflows: -| Rule name | Target branch | +| Branch name pattern | Target branch | |-------------|---------------| | `feature/*` | `develop` | | `bug/*` | `develop` | | `release/*` | `main` | -These rules simplify the process of creating merge requests for a project that: +These target branches simplify the process of creating merge requests for a project that: - Uses `main` to represent the deployed state of your application. - Tracks current, unreleased development work in another long-running branch, like `develop`. -If your workflow initially places new features in `develop` instead of `main`, these rules +If your workflow initially places new features in `develop` instead of `main`, these target branches ensure all branches matching either `feature/*` or `bug/*` do not target `main` by mistake. -When you're ready to release to `main`, create a branch named `release/*`, and the rules +When you're ready to release to `main`, create a branch named `release/*`, and ensure this branch targets `main`. -## Delete a target branch rule +## Delete a target branch workflow -When you remove a target branch rule, existing merge requests remain unchanged. +When you remove a target branch workflow, existing merge requests remain unchanged. Prerequisites: @@ -348,7 +350,7 @@ To do this: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. -1. Select **Delete** on the rule you want to delete. +1. Select **Delete** on the branch target you want to delete. ## Related topics diff --git a/doc/user/project/repository/code_suggestions/index.md b/doc/user/project/repository/code_suggestions/index.md index 9e52da6068c..ed9eeac1c2c 100644 --- a/doc/user/project/repository/code_suggestions/index.md +++ b/doc/user/project/repository/code_suggestions/index.md @@ -4,40 +4,45 @@ group: Code Creation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Code Suggestions **(FREE ALL BETA)** +# Code Suggestions **(FREE ALL)** > - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. > - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2. > - [Introduced support for Code Generation](https://gitlab.com/gitlab-org/gitlab/-/issues/415583) in GitLab 16.3. - -WARNING: -This feature is in [Beta](../../../../policy/experiment-beta-support.md#beta). -Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your [feedback](#feedback). +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435271) in GitLab 16.7. Write code more efficiently by using generative AI to suggest code while you're developing. -With Code Suggestions, you get: +With [GitLab Duo Code Suggestions](https://about.gitlab.com/solutions/code-suggestions/), you get: -- Code Completion, which suggests completions the current line you are typing. These suggestions are usually low latency. -- Code Generation, which generates code based on a natural language code comment block. Generating code can exceed multiple seconds. +- Code Completion, which suggests completions to the current line you are typing. These suggestions are usually low latency. +- Code Generation, which generates code based on a natural language code + comment block. Write a comment like `# Type more here` to generate the + appropriate code, based on the context of your comment and the rest of your code. + - Algorithms or large code blocks may take more than 10 seconds to generate. + - Streaming of code generation responses is supported in VS Code, leading to faster average response times. Other supported IDEs offer slower response times and will return the generated code in a single block. ## Start using Code Suggestions GitLab Duo Code Suggestions are available: -- On [self-managed](self_managed.md) and [SaaS](saas.md). View these pages to get started. +- In the Premium and Ultimate tier for [self-managed](self_managed.md), and across all tiers for [SaaS](saas.md). View these pages to get started. - In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. - In the GitLab Web IDE. <div class="video-fallback"> - <a href="https://youtu.be/wAYiy05fjF0">View how to setup and use GitLab Duo Code Suggestions</a>. + <a href="https://youtu.be/xQUlrbIWo8o">View how to setup and use GitLab Duo Code Suggestions</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/wAYiy05fjF0" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/xQUlrbIWo8o" frameborder="0" allowfullscreen> </iframe> </figure> -During Beta, usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). -Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). As Code Suggestions matures to General Availability it will be governed by our [AI Functionality Terms](https://about.gitlab.com/handbook/legal/ai-functionality-terms/). +Code Suggestions is available and free to use until February 15, 2024: + +- Before February 15, 2024, usage of Code Suggestions is governed by the + [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +- On February 15, 2024, Code Suggestions becomes a paid add-on and will be governed by our + [AI Functionality Terms](https://about.gitlab.com/handbook/legal/ai-functionality-terms/). ## Supported languages @@ -51,7 +56,11 @@ For languages not listed in the following table, Code Suggestions might not func ### Supported languages in IDEs -Editor support for languages is documented in the following table. +Code Suggestions is aware of common popular programming concepts and +infrastructure-as-code interfaces, like Kubernetes Resource Model (KRM), +Google Cloud CLI, and Terraform. + +The editor supports these languages: | Language | VS Code | JetBrains IDEs | Visual Studio | Neovim | |------------------|------------------------|------------------------|------------------------|--------| @@ -61,16 +70,14 @@ Editor support for languages is documented in the following table. | Google SQL | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | Java | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | JavaScript | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | -| Kotlin | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Kotlin | **{check-circle}** Yes (Requires third-party extension providing Kotlin support) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | PHP | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | Python | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | Ruby | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | Rust | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | -| Scala | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Scala | **{check-circle}** Yes (Requires third-party extension providing Scala support) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | Swift | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | | TypeScript | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | -| Google Cloud | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | -| Kubernetes Resource Model (KRM) | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | | Terraform | **{check-circle}** Yes (Requires third-party extension providing Terraform support) | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes (Requires third-party extension providing the `terraform` file type) | NOTE: @@ -81,18 +88,13 @@ plugin support. Refer to the JetBrains documentation for specifics on your IDE. Code Suggestions supports a variety of popular editors including: -- VS Code, using [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). +- VS Code, using [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). Supports streaming responses for code generation. - [GitLab WebIDE (VS Code in the Cloud)](../../../project/web_ide/index.md), with no additional configuration. - Microsoft Visual Studio, using the [Visual Studio GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). - JetBrains IDEs, using the [GitLab plugin](https://plugins.jetbrains.com/plugin/22325-gitlab). - Neovim, using the [`gitlab.vim` plugin](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim). -A [GitLab Language Server for Code Suggestions](https://gitlab.com/gitlab-org/editor-extensions/gitlab-language-server-for-code-suggestions) -is also in process. -This improvement should result in: - -- Faster iteration and standardization of the IDE extensions. -- The ability to use Code Suggestions even when an official editor extension isn't available. +A [GitLab Language Server](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp) is used in VS Code, Visual Studio, and Neovim. The Language Server supports faster iteration across more platforms. Users can also configure it to support Code Suggestions in IDEs where GitLab doesn't provide official support. ## Code Suggestions data usage @@ -120,7 +122,7 @@ For self-managed instances that have enabled Code Suggestions and SaaS accounts, ### Inference window context -Code Suggestions inferences against the currently opened file, the content before and after the cursor, the filename, and the extension type. For more information on possible future context expansion to improve the quality of suggestions, see [epic 11669](https://gitlab.com/groups/gitlab-org/-/epics/11669). +Code Suggestions inferences against the currently opened file, the content before and after the cursor, the file name, and the extension type. For more information on possible future context expansion to improve the quality of suggestions, see [epic 11669](https://gitlab.com/groups/gitlab-org/-/epics/11669). ### Training data @@ -133,14 +135,18 @@ For more information on GitLab Code Suggestions data [sub-processors](https://ab ## Known limitations -While in Beta, we are working on improving the accuracy of overall generated content. +We are continuing to work on the accuracy of overall generated content. However, Code Suggestions may generate suggestions that are: -- Low-quality -- Incomplete -- Produce failed pipelines -- Insecure code -- Offensive or insensitive +- Irrelevant. +- Incomplete. +- Results in failed pipelines. +- Potentially insecure. +- Offensive or insensitive. + +When using Code Suggestions, [code review best practice](../../../../development/code_review.md) still applies. + +Let us know if you have [feedback](#feedback). ## Progressive enhancement @@ -151,4 +157,11 @@ Code Suggestions do not prevent you from writing code in your IDE. ## Feedback -Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). +Let us know about your Code Suggestions experience in [issue 435783](https://gitlab.com/gitlab-org/gitlab/-/issues/435783). + +## Troubleshooting + +### Disable Code Suggestions + +Individual users can disable Code Suggestions by disabling the feature in their +[installed IDE editor extension](index.md#supported-editor-extensions). diff --git a/doc/user/project/repository/code_suggestions/repository_xray.md b/doc/user/project/repository/code_suggestions/repository_xray.md new file mode 100644 index 00000000000..d851ee94e34 --- /dev/null +++ b/doc/user/project/repository/code_suggestions/repository_xray.md @@ -0,0 +1,60 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Repository X-Ray **(PREMIUM)** + +Repository X-Ray enhances GitLab Duo Code Suggestions by providing additional context to improve the accuracy and relevance of code recommendations. + +Repository X-Ray gives the code assistant more insight into the project's codebase and dependencies to generate better code suggestions. It does this by analyzing key project configuration files such as `Gemfile.lock`, `package.json`, and `go.mod` to build additional context. + +By understanding the frameworks, libraries and other dependencies in use, Repository X-Ray helps the code assistant tailor suggestions to match the coding patterns, styles and technologies used in the project. This results in code recommendations that integrate more seamlessly and follow best practices for that stack. + +## Supported languages and package managers + +| Language | Package Manager | Configuration File | +| ---------- |-----------------| -------------------- | +| Go | Go Modules | `go.mod` | +| JavaScript | NPM, Yarn | `package.json` | +| Ruby | RubyGems | `Gemfile.lock` | +| Python | Poetry | `pyproject.toml` | +| Python | Pip | `requirements.txt` | +| Python | Conda | `environment.yml` | + +## Enable Repository X-Ray + +Prerequisites: + +- You must have access to [GitLab Duo Code Suggestions](index.md) in the project. +- GitLab Runner must be set up and enabled for the project, because Repository X-Ray runs analysis pipelines using GitLab runners. + +To enable Repository X-Ray, add the following definition job to the project's `.gitlab-ci.yml`. + +```yaml +xray: + stage: build + image: registry.gitlab.com/gitlab-org/code-creation/repository-x-ray:latest + allow_failure: true + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + variables: + OUTPUT_DIR: reports + script: + - x-ray-scan -p "$CI_PROJECT_DIR" -o "$OUTPUT_DIR" + artifacts: + reports: + repository_xray: "$OUTPUT_DIR/*/*.json" +``` + +- The `$OUTPUT_DIR` environment variable defines the: + - Output directory for reports. + - Path that artifacts are uploaded from. +- The added rules restrict the job to the default branch only. Restricting the job this way ensures development changes do not impact the baseline X-Ray data used for production code suggestions. + +After the initial x-ray job completes and uploads the repository analysis reports, no further action is required. Repository X-Ray automatically enriches all code generation requests from that point forward. + +The X-Ray data for your project updates each time a CI/CD pipeline containing the `xray` +job is run. To learn more about pipeline configuration and triggers, see the +[pipelines documentation](../../../../ci/pipelines/merge_request_pipelines.md). diff --git a/doc/user/project/repository/code_suggestions/saas.md b/doc/user/project/repository/code_suggestions/saas.md index 1af5eef585c..4b1cc762406 100644 --- a/doc/user/project/repository/code_suggestions/saas.md +++ b/doc/user/project/repository/code_suggestions/saas.md @@ -4,13 +4,14 @@ group: Code Creation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Code Suggestions on GitLab SaaS **(FREE SAAS BETA)** +# Code Suggestions on GitLab SaaS **(FREE SAAS)** > - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](../../../../policy/experiment-beta-support.md#beta) for early access Ultimate customers on GitLab.com. > - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](../../../../policy/experiment-beta-support.md#beta). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435271) in GitLab 16.7. Write code more efficiently by using generative AI to suggest code while you're developing. @@ -20,14 +21,14 @@ Learn about [data usage when using Code Suggestions](index.md#code-suggestions-d ## Enable Code Suggestions > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. UI user setting removed. A group owner must [enable Code Suggestions for your top-level group](../../../group/manage.md#enable-code-suggestions-for-a-group). NOTE: If you are having issues enabling Code Suggestions, view the -[troubleshooting guide](troubleshooting.md#code-suggestions-arent-displayed). +[troubleshooting guide](troubleshooting.md#code-suggestions-are-not-displayed). ## Use Code Suggestions @@ -35,19 +36,23 @@ Prerequisites: - You must have configured Code Suggestions in a [supported IDE editor extension](index.md#supported-editor-extensions). -- Code Suggestions must be enabled for: - - [The top-level group](../../../group/manage.md#enable-code-suggestions-for-a-group). - - [Your own account](../../../profile/preferences.md#enable-code-suggestions), if your - account is not part of the percentage rollout. +- Code Suggestions must be enabled for [the top-level group](../../../group/manage.md#enable-code-suggestions-for-a-group). To use Code Suggestions: -1. Determine if your user account is part of the percentage rollout. See - [Enable Code Suggestions](../../../profile/preferences.md#enable-code-suggestions) - for more information. 1. Author your code. As you type, suggestions are displayed. Code Suggestions provide code snippets or complete the current line, depending on the cursor position. -1. Describe the requirements in natural language. Be concise and specific. Code Suggestions generates functions and code snippets as appropriate. +1. Describe the requirements in natural language. Code Suggestions generates functions and code snippets based on the context provided. To get the best results from code generation: + - Be as specific as possible while remaining concise. State the outcome you want to generate (for example, a function) and provide details on what you want to achieve. Add additional information, such as the framework or library you want to use when applicable. + For example, to create a Python web service with some specific requirements, you might write something similar to the following: + + ```plaintext + # Create a web service using Tornado that allows a user to log in, run a security scan, and review the scan results. + # Each action (log in, run a scan, and review results) should be its own resource in the web service + ... + ``` + + - Add a space or go to a new line after each comment. This tells the code generator that you have completed your instructions. 1. To accept a suggestion, press <kbd>Tab</kbd>. 1. To ignore a suggestion, keep typing as you usually would. 1. To explicitly reject a suggestion, press <kbd>Esc</kbd>. diff --git a/doc/user/project/repository/code_suggestions/self_managed.md b/doc/user/project/repository/code_suggestions/self_managed.md index 26850bc8b5f..8cd499c13d0 100644 --- a/doc/user/project/repository/code_suggestions/self_managed.md +++ b/doc/user/project/repository/code_suggestions/self_managed.md @@ -4,12 +4,13 @@ group: Code Creation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Code Suggestions on self-managed GitLab **(SELF BETA)** +# Code Suggestions on self-managed GitLab **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta) on self-managed GitLab. > - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. > - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2. > - Code Suggestions in the GitLab WebIDE enabled for all GitLab-hosted customers. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435271) in GitLab 16.7. Write code more efficiently by using generative AI to suggest code while you're developing. @@ -28,16 +29,19 @@ Learn about [data usage when using Code Suggestions](index.md#code-suggestions-d ## Enable Code Suggestions on self-managed GitLab > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. +> - [Enabled self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. When you enable Code Suggestions for your self-managed instance, you: - Agree to the [GitLab testing agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). - Acknowledge that GitLab sends data from the instance, including personal data, to GitLab.com infrastructure. -How you enable Code Suggestions for your instance differs depending on your version of GitLab. +How you enable Code Suggestions for your instance differs depending on your +version of GitLab. This setting is visible only in self-managed GitLab instances. -### GitLab 16.3 and later **(PREMIUM)** +::Tabs + +:::TabTitle GitLab 16.3 and later Prerequisites: @@ -53,17 +57,12 @@ To enable Code Suggestions for your self-managed GitLab instance: In GitLab 16.3, you do not need to enter anything into the **Personal access token** field. In GitLab 16.4 and later, there is no **Personal access token** field. 1. Select **Save changes**. - -This setting is visible only in self-managed GitLab instances. - -WARNING: -In GitLab 16.2 and earlier, if you clear the **Turn on Code Suggestions for this instance** checkbox, the users in your instance can still use Code Suggestions for up to one hour, until the issued JSON web token (JWT) expires. - -To make sure Code Suggestions works immediately, you must [manually synchronize your subscription](#manually-synchronize-your-subscription). +1. To make sure Code Suggestions works immediately, you must + [manually synchronize your subscription](#manually-synchronize-your-subscription). The users in your instance can now use Code Suggestions. -### GitLab 16.2 and earlier +:::TabTitle GitLab 16.2 and earlier FLAG: On self-managed GitLab 16.0 and earlier, GitLab Duo Code Suggestions is not available. To use this feature, you must have GitLab 16.1 or later. For optimal performance and full feature access, you should upgrade to GitLab 16.3 or later, which supports cloud licensing. @@ -75,7 +74,7 @@ Prerequisites: - You have a [GitLab SaaS account](https://gitlab.com/users/sign_up). You do not need to have a GitLab SaaS subscription. NOTE: -If you do not have a customer success manager, you cannot participate in the free trial of Code Suggestions on self-managed GitLab. Upgrade to GitLab 16.3 to [perform self-service onboarding](#gitlab-163-and-later). +If you do not have a customer success manager, you cannot participate in the free trial of Code Suggestions on self-managed GitLab. Upgrade to GitLab 16.3 or later to perform self-service onboarding. Then, you will: @@ -83,7 +82,7 @@ Then, you will: 1. Enable Code Suggestions for the instance. 1. [Request early access](#request-access-to-code-suggestions) to the Code Suggestions Beta. -#### Enable Code Suggestions for your SaaS account +### Enable Code Suggestions for your SaaS account To enable Code Suggestions for your GitLab SaaS account: @@ -94,7 +93,7 @@ To enable Code Suggestions for your GitLab SaaS account: 1. In the **Code Suggestions** section, select **Enable Code Suggestions**. 1. Select **Save changes**. -#### Enable Code Suggestions for the instance +### Enable Code Suggestions for the instance To enable Code Suggestions for your self-managed GitLab instance: @@ -110,7 +109,9 @@ This setting is visible only in self-managed GitLab instances. WARNING: If you clear the **Turn on Code Suggestions for this instance** checkbox, the users in your instance can still use Code Suggestions for up to one hour, until the issued JSON web token (JWT) expires. -#### Request access to Code Suggestions +::EndTabs + +### Request access to Code Suggestions GitLab provisions access on a customer-by-customer basis for Code Suggestions on self-managed instances. To request access, contact your customer success manager. @@ -120,7 +121,7 @@ Your customer success manager then provisions access by commenting on [issue 415 After GitLab has provisioned access to Code Suggestions for your instance, the users in your instance can now enable Code Suggestions. -### Configure network and proxy settings +## Configure network and proxy settings Configure any firewalls to allow outbound connections to `https://codesuggestions.gitlab.com/`. @@ -128,7 +129,7 @@ If your GitLab instance uses an HTTP proxy server to access the internet, ensure the server is configured to allow outbound connections, including the [`gitlab_workhorse` environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html). -### Upgrade GitLab +## Upgrade GitLab In GitLab 16.3 and later, GitLab is enforcing the cloud licensing requirement for Code Suggestions: @@ -138,11 +139,11 @@ In GitLab 16.3 and later, GitLab is enforcing the cloud licensing requirement fo If you have a GitLab Free subscription and upgrade to GitLab 16.3 or later, to continue having early access to Code Suggestions, you must: -1. Have a [subscription that supports cloud licensing](https://about.gitlab.com/pricing/). +1. Have a [subscription that supports cloud licensing](https://about.gitlab.com/pricing/licensing-faq/cloud-licensing/). 1. Make sure you have the latest version of your [IDE extension](index.md#supported-editor-extensions). 1. [Manually synchronize your subscription](#manually-synchronize-your-subscription). -#### Manually synchronize your subscription +### Manually synchronize your subscription You must [manually synchronize your subscription](../../../../subscriptions/self_managed/index.md#manually-synchronize-your-subscription-details) if either: diff --git a/doc/user/project/repository/code_suggestions/troubleshooting.md b/doc/user/project/repository/code_suggestions/troubleshooting.md index c18ea2dd26b..47327d7a28f 100644 --- a/doc/user/project/repository/code_suggestions/troubleshooting.md +++ b/doc/user/project/repository/code_suggestions/troubleshooting.md @@ -4,35 +4,34 @@ group: Code Creation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Troubleshooting Code Suggestions **(FREE ALL BETA)** +# Troubleshooting Code Suggestions **(FREE ALL)** When working with GitLab Duo Code Suggestions, you might encounter the following issues. -## Code Suggestions aren't displayed +## Code Suggestions are not displayed If Code Suggestions are not displayed, and you have [installed a supported IDE extension](index.md#supported-editor-extensions), try the following troubleshooting steps. -In GitLab, ensure Code Suggestions is enabled: - -- [For your user account](../../../profile/preferences.md#enable-code-suggestions). -- [For **all** top-level groups your account belongs to](../../../group/manage.md#enable-code-suggestions-for-a-group). If you don't have a role that lets you view the top-level group's settings, contact a group owner. +In GitLab, ensure Code Suggestions is enabled for **at least one** +[top-level group your account belongs to](../../../group/manage.md#enable-code-suggestions-for-a-group). +If you don't have a role that lets you view the top-level group's settings, contact a group owner. ### Code Suggestions not displayed in VS Code or GitLab WebIDE -Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. +Check all the steps in [Code Suggestions are not displayed](#code-suggestions-are-not-displayed) first. If you are a self-managed user, ensure that Code Suggestions for the [GitLab WebIDE](../../../project/web_ide/index.md) are enabled. The same settings apply to VS Code as local IDE. 1. On the left sidebar, select **Extensions > GitLab Workflow**. 1. Select **Settings** (**{settings}**), and then select **Extension Settings**. -1. In **GitLab > AI Assisted Code Suggestions**, select the **Enable code completion (Beta)** +1. In **GitLab > AI Assisted Code Suggestions**, select the **Enable code completion** checkbox. If the settings are enabled, but Code Suggestions are still not displayed, try the following steps: 1. Enable the `Debug` checkbox in the GitLab Workflow **Extension Settings**. 1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Workflow** as the log filter. The command palette command is `GitLab: Show Extension Logs`. -1. Disable and re-enable the **Enable code completion (Beta)** checkbox. +1. Disable and re-enable the **Enable code completion** checkbox. 1. Verify that the debug log contains similar output: ```shell @@ -43,7 +42,7 @@ If the settings are enabled, but Code Suggestions are still not displayed, try t ### Code Suggestions not displayed in Microsoft Visual Studio -Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. +Check all the steps in [Code Suggestions are not displayed](#code-suggestions-are-not-displayed) first. 1. Ensure you have properly [set up the extension](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension#setup). 1. From the **Tools > Options** menu, find the **GitLab** option. Ensure **Log Level** is set to **Debug**. diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index a602638d244..f1fb118b8d5 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -34,6 +34,28 @@ to the left of the user avatar shows the general age of the commit. The newest commits have a dark blue bar. As the age of the commit increases, the bar color changes to light gray. +### View blame directly in the file view +<!-- +When feature flags `graphql_git_blame`, `blob_blame_info` and `highlight_js_worker` are removed, +delete this section and update the steps in "View blame for a file". +--> + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/430950) in GitLab 16.7 [with flags](../../../administration/feature_flags.md) named `graphql_git_blame`, `blob_blame_info` and `highlight_js_worker`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. +To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `blob_blame_info`. +On GitLab.com, this feature is available. + +When this feature is enabled, you can additionally view blame for a file directly from the file page. + +To do so: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Repository**. +1. Select the file you want to review. +1. In the file header, select **Blame**, and go to the line you want to see. + ### Blame previous commit To see earlier revisions of a specific line: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md deleted file mode 100644 index 592041ef4e2..00000000000 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../signed_commits/gpg.md' -remove_date: '2023-12-01' ---- - -This document was moved to [another location](../signed_commits/gpg.md). - -<!-- This redirect file can be deleted after <2023-12-01>. --> -<!-- 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/repository/index.md b/doc/user/project/repository/index.md index dd8ee61f6ae..550ff25e0b1 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -39,7 +39,7 @@ You can upload a file from the GitLab UI. 1. Go to the directory where you want to upload the file. 1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**. 1. Complete the fields. - - To create a merge request with your changes, enter a branch name + To create a merge request with your changes, enter a branch name that's not your repository's [default branch](branches/default.md). 1. Select **Upload file**. @@ -85,7 +85,7 @@ Projects that contain a `.xcodeproj` or `.xcworkspace` directory can be cloned into Xcode on macOS. 1. From the GitLab UI, go to the project's overview page. -1. Select **Clone**. +1. In the upper-right corner, select **Code**. 1. Select **Xcode**. The project is cloned onto your computer and you are @@ -101,7 +101,7 @@ Visual Studio Code: - From the GitLab interface: 1. Go to the project's overview page. - 1. Select **Clone**. + 1. In the upper-right corner, select **Code**. 1. Under **Open in your IDE**, select **Visual Studio Code (SSH)** or **Visual Studio Code (HTTPS)**. 1. Select a folder to clone the project into. @@ -121,16 +121,15 @@ Prerequisites: To do this: 1. Go to the project's overview page. -1. Select **Clone**. +1. In the upper-right corner, select **Code**. 1. Under **Open in your IDE**, select **IntelliJ IDEA (SSH)** or **IntelliJ IDEA (HTTPS)**. ## Download the code in a repository -> Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. - You can download the source code that's stored in a repository. -1. Above the file list, select the download icon (**{download}**). +1. On the left sidebar, select **Search or go to** and find your project. +1. Above the file list, select **Code**. 1. From the options, select the files you want to download. - **Source code:** diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md deleted file mode 100644 index 1fedd8da20c..00000000000 --- a/doc/user/project/repository/managing_large_repositories.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'monorepos/index.md' -remove_date: '2023-12-17' ---- - -This document was moved to [another location](monorepos/index.md). - -<!-- This redirect file can be deleted after <2023-12-17>. --> -<!-- 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/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index d4ab550cb8a..dc789d28a4f 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -39,7 +39,7 @@ instance can help reduce race conditions by syncing changes more frequently. Prerequisites: - You have configured the [push](push.md#set-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) -and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab instance. + and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab instance. To create the webhook in the downstream instance: diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 34a2757bb67..9d5048a4fed 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -208,4 +208,4 @@ Older versions of SSH may require you to remove `-E md5` from the command. - [Troubleshooting](troubleshooting.md) for repository mirroring. - Configure a [Pull Mirroring Interval](../../../../administration/instance_limits.md#pull-mirroring-interval) - [Disable mirrors for a project](../../../../administration/settings/visibility_and_access_controls.md#enable-project-mirroring) -- [Secrets file and mirroring](../../../../administration/backup_restore/backup_gitlab.md#when-the-secrets-file-is-lost) +- [Secrets file and mirroring](../../../../administration/backup_restore/troubleshooting_backup_gitlab.md#when-the-secrets-file-is-lost) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 3aa4c768ebe..babe99441ef 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -161,7 +161,7 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Copy or download the special Git HTTPS user ID and password. 1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. -1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). +1. Open your new repository, in the upper-right corner, select **Code > Clone HTTPS** (not **Clone HTTPS (GRC)**). 1. In GitLab, open the repository to be push-mirrored. 1. Select **Settings > Repository**, and then expand **Mirroring repositories**. 1. Fill in the **Git repository URL** field using this format, replacing diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md index 57a9351e85d..f252c047072 100644 --- a/doc/user/project/repository/mirror/troubleshooting.md +++ b/doc/user/project/repository/mirror/troubleshooting.md @@ -215,3 +215,13 @@ Project.where(mirror: true).each do |project| project.save end ``` + +## `The requested URL returned error: 301` + +When mirroring using the `http://` or `https://` protocols, be sure to specify the exact URL to the repository: `https://gitlab.example.com/group/project.git` + +HTTP redirects are not followed and omitting `.git` can result in a 301 error: + +```plaintext +13:fetch remote: "fatal: unable to access 'https://gitlab.com/group/project': The requested URL returned error: 301\n": exit status 128. +``` diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index fc36748a8dd..b15d66e27fb 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -118,20 +118,20 @@ Some validation examples: - Branches must start with `JIRA-`. ```plaintext - `^JIRA-` + ^JIRA- ``` - Branches must end with `-JIRA`. ```plaintext - `-JIRA$` + -JIRA$ ``` - Branches must be between `4` and `15` characters long, accepting only lowercase letters, numbers and dashes. ```plaintext - `^[a-z0-9\\-]{4,15}$` + ^[a-z0-9\\-]{4,15}$ ``` ## Prevent unintended consequences diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index a060973d89f..528e9eefa44 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -190,7 +190,7 @@ no longer being available. To clean up a repository: -1. Go to the project for the repository. +1. On the left sidebar, select **Search or go to** and find your project. 1. Go to **Settings > Repository**. 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. diff --git a/doc/user/project/repository/signed_commits/ssh.md b/doc/user/project/repository/signed_commits/ssh.md index e1c2a73be3e..1d3fca6d681 100644 --- a/doc/user/project/repository/signed_commits/ssh.md +++ b/doc/user/project/repository/signed_commits/ssh.md @@ -156,7 +156,7 @@ To revoke an SSH key: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select (**{key}**) **SSH Keys**. +1. On the left sidebar, select **SSH Keys** (**{key}**). 1. Select **Revoke** next to the SSH key you want to delete. ## Related topics diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md deleted file mode 100644 index 89e3d811dba..00000000000 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../signed_commits/ssh.md' -remove_date: '2023-12-01' ---- - -This document was moved to [another location](../signed_commits/ssh.md). - -<!-- This redirect file can be deleted after <2023-12-01>. --> -<!-- 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/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 3899890ea7e..d2df9cc18ae 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -20,7 +20,7 @@ To create a text file in the Web Editor: 1. Go to the directory where you want to create the new file. 1. Next to the directory name, select the plus icon (**{plus}**) > **New file**. 1. Complete the fields. - - To create a merge request with your changes, enter a branch name + To create a merge request with your changes, enter a branch name that's not your repository's [default branch](branches/default.md). 1. Select **Commit changes**. @@ -31,14 +31,14 @@ To create a text file from a template in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. 1. Go to the directory where you want to create the new file. 1. Next to the directory name, select the plus icon (**{plus}**) > **New file**. -1. In **Filename**, enter a filename that GitLab provides a template for: +1. In **Filename**, enter a name that GitLab provides a template for: - `.gitignore` - `.gitlab-ci.yml` - `LICENSE` - `Dockerfile` 1. From the **Apply a template** dropdown list, select a template. 1. Complete the fields. - - To create a merge request with your changes, enter a branch name + To create a merge request with your changes, enter a branch name that's not your repository's [default branch](branches/default.md). 1. Select **Commit changes**. @@ -50,7 +50,7 @@ To edit a text file in the Web Editor: 1. Go to the file you want to edit. 1. Select **Edit > Edit single file**. 1. Complete the fields. - - To create a merge request with your changes, enter a branch name + To create a merge request with your changes, enter a branch name that's not your repository's [default branch](branches/default.md). 1. Select **Commit changes**. @@ -72,7 +72,7 @@ To close the preview panel, select the **Write** tab. ### Link to specific lines To link to single or multiple lines in the Web Editor, add hash -information to the filename segment of the URL. For example: +information to the file name segment of the URL. For example: - `MY_FILE.js#L3` highlights line 3 in `MY_FILE.js`. - `MY_FILE.js#L3-10` highlights lines 3 to 10 in `MY_FILE.js`. @@ -90,7 +90,7 @@ To upload a file in the Web Editor: 1. Go to the directory where you want to upload the file. 1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**. 1. Complete the fields. - - To create a merge request with your changes, enter a branch name + To create a merge request with your changes, enter a branch name that's not your repository's [default branch](branches/default.md). 1. Select **Upload file**. @@ -102,7 +102,7 @@ To create a directory in the Web Editor: 1. Go to the directory where you want to create the new directory. 1. Next to the directory name, select the plus icon (**{plus}**) > **New directory**. 1. Complete the fields. - - To create a merge request with your changes, enter a branch name + To create a merge request with your changes, enter a branch name that's not your repository's [default branch](branches/default.md). 1. Select **Create directory**. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md deleted file mode 100644 index ae418581820..00000000000 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../signed_commits/x509.md' -remove_date: '2023-12-01' ---- - -This document was moved to [another location](../signed_commits/x509.md). - -<!-- This redirect file can be deleted after <2023-12-01>. --> -<!-- 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/requirements/index.md b/doc/user/project/requirements/index.md index 0594f3fe2ee..e489f19585c 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -50,7 +50,7 @@ To create a requirement: 1. In a project, go to **Plan > Requirements**. 1. Select **New requirement**. -1. Enter a title and description and select **Create requirement**. +1. Enter a title and description and select **New requirement**.  @@ -240,7 +240,8 @@ To import requirements: 1. In a project, go to **Plan > Requirements**. - For a project with requirements, in the - upper-right corner, select the import icon (**{import}**). + upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), + then select **Import requirements** (**{import}**). - For a project without requirements, in the middle of the page, select **Import CSV**. 1. Select the file and select **Import requirements**. @@ -300,7 +301,8 @@ Prerequisites: To export requirements: 1. In a project, go to **Plan > Requirements**. -1. In the upper-right corner, select **Export as CSV** (**{export}**). +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), + then select **Export as CSV** (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/service_desk/configure.md b/doc/user/project/service_desk/configure.md index 91dbe7a38dd..95c15ef42b7 100644 --- a/doc/user/project/service_desk/configure.md +++ b/doc/user/project/service_desk/configure.md @@ -63,14 +63,14 @@ For example, you can format the emails to include a header and footer in accorda organization's brand guidelines. You can also include the following placeholders to display dynamic content specific to the Service Desk ticket or your GitLab instance. -| Placeholder | `thank_you.md` | `new_note.md` | Description -| ---------------------- | ---------------------- | ---------------------- | ----------- -| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. -| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. -| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). -| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. -| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. -| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the requesters may never see the updates on their Service Desk ticket. +| Placeholder | `thank_you.md` | `new_note.md` | Description | +|------------------------|------------------------|------------------------|-------------| +| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. | +| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. | +| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). | +| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. | +| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. | +| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the requesters may never see the updates on their Service Desk ticket. | ### Thank you email @@ -105,7 +105,7 @@ Instance administrators can add a header, footer or additional text to the GitLa them to all emails sent from GitLab. If you're using a custom `thank_you.md` or `new_note.md`, to include this content, add `%{SYSTEM_HEADER}`, `%{SYSTEM_FOOTER}`, or `%{ADDITIONAL_TEXT}` to your templates. -For more information, see [System header and footer messages](../../../administration/appearance.md#system-header-and-footer-messages) and [custom additional text](../../../administration/settings/email.md#custom-additional-text). +For more information, see [System header and footer messages](../../../administration/appearance.md#add-system-header-and-footer-messages) and [custom additional text](../../../administration/settings/email.md#custom-additional-text). ## Use a custom template for Service Desk tickets @@ -165,6 +165,7 @@ the assignees of the issue and creates to-do items for them. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a walkthrough, see [a short showcase video](https://youtu.be/163wDM1e43o). +<!-- Video published on 2023-12-12 --> Prerequisites: @@ -191,6 +192,7 @@ Maintain brand identity and instill confidence among support requesters with a d <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [a short showcase video](https://youtu.be/_moD5U3xcQs). +<!-- Video published on 2023-09-12 --> This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). A Beta feature is not production-ready, but is unlikely to change drastically @@ -225,12 +227,12 @@ Configure and verify a custom email address when you want to send Service Desk e 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. -1. Expand **Service Desk** and find the **Custom email** settings. +1. Expand **Service Desk** and find the **Configure a custom email address** section. 1. Note the presented Service Desk address of this project, and with your email provider (for example, Gmail), set up email forwarding from the custom email address to the Service Desk address. 1. Back in GitLab, complete the fields. -1. Select **Save & test settings**. +1. Select **Save & test connection**. The configuration has been saved and the verification of the custom email address is triggered. @@ -945,7 +947,7 @@ or completely separately. ::EndTabs 1. GitLab offers two methods to transport emails from `mail_room` to the GitLab -application. You can configure the `delivery_method` for each email setting individually: + application. You can configure the `delivery_method` for each email setting individually: 1. Recommended: `webhook` (default in GitLab 15.3 and later) sends the email payload via an API POST request to your GitLab application. It uses a shared token to authenticate. If you choose this method, make sure the `mail_room` process can access the API endpoint and distribute the shared diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md index 9ab69c4bdb8..6a15b9798f7 100644 --- a/doc/user/project/service_desk/index.md +++ b/doc/user/project/service_desk/index.md @@ -14,6 +14,10 @@ Service Desk emails are created in your GitLab project as new issues. Your team can respond directly from the project, while customers interact with the thread only through email. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see [Introducing GitLab Service Desk (GitLab 16.7)](https://www.youtube.com/watch?v=LDVQXv3I5rI). +<!-- Video published on 2023-12-19 --> + ## Service Desk workflow For example, let's assume you develop a game for iOS or Android. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index fc9b24362e0..f2faa0676b5 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -4,27 +4,31 @@ group: Import and Integrate info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- -# Migrating projects using file exports **(FREE ALL)** +# Migrate projects and groups by using file exports **(FREE ALL)** + +You can migrate projects and groups by using file exports. However, using +[direct transfer](../../group/import/index.md) is recommended if possible. + +## Migrate projects by uploading an export file Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and -then imported into another GitLab instance. You can also copy GitLab projects to another location with more automation by -[migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +then imported into another GitLab instance. -## Preserving user contributions +### Preserving user contributions Preserving user contribution depends on meeting the following requirements: -### Migrating from GitLab self-managed to GitLab.com +#### Migrating from GitLab self-managed to GitLab.com When migrating projects by using file exports, an administrator's access token is required for user contributions to map correctly. Therefore, user contributions never map correctly when importing file exports from a self-managed instance to GitLab.com. Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. To preserve contribution history, do one of the following: -- [Migrate by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- [Migrate by direct transfer](../../group/import/index.md). - Consider paid GitLab [migration services](https://about.gitlab.com/services/migration/). -### Migrating to GitLab self-managed +#### Migrating to GitLab self-managed To ensure GitLab maps users and their contributions correctly: @@ -43,7 +47,7 @@ That user becomes an author of merge requests created by other users. Supplement - Added for comments, merge request approvals, linked tasks, and items. - Not added for the merge request or issue creator, added or removed labels, and merged-by information. -## Edit project export files +### Edit project export files You can add or remove data from export files. For example, you can: @@ -58,7 +62,7 @@ To edit a project export file: You can also make sure that all members were exported by checking the `project_members.ndjson` file. -## Compatibility +### Compatibility > Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389888) in GitLab 15.11. @@ -75,7 +79,7 @@ For example: | 13.0 | 13.0, 12.10, 12.9 | | 13.1 | 13.1, 13.0, 12.10 | -## Configure file exports as an import source **(FREE SELF)** +### Configure file exports as an import source **(FREE SELF)** Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: @@ -92,7 +96,7 @@ To enable file exports as an import source for the destination instance: 1. Scroll to **Import sources**. 1. Select the **GitLab export** checkbox. -## Between CE and EE +### Between CE and EE You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa, assuming [compatibility](#compatibility) is met. @@ -101,7 +105,7 @@ If you're exporting a project from the Enterprise Edition to the Community Editi data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../index.md). -## Export a project and its data +### Export a project and its data Before you can import a project, you must export it. @@ -124,7 +128,7 @@ To export a project and its data, follow these steps: The export is generated in your configured `shared_path`, a temporary shared directory, and then moved to your configured `uploads_directory`. Every 24 hours, a worker deletes these export files. -### Items that are exported +#### Items that are exported Exported project items depend on the version of GitLab you use. To determine if a specific project item is exported: @@ -166,7 +170,7 @@ For a quick overview, items that are exported include: - Project and inherited group members, as long as the user has the Maintainer role in the exported project's group or is an administrator -### Items that are not exported +#### Items that are not exported Items that are **not** exported include: @@ -189,7 +193,7 @@ Items that are **not** exported include: Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and [instance](../../../administration/custom_project_templates.md) levels. Therefore, the list of exported items is the same. -## Import a project and its data +### Import a project and its data > Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. Administrators of self-managed instances can [set maximum import file size](#set-maximum-import-file-size). On GitLab.com, the value is [set to 5 GB](../../gitlab_com/index.md#account-and-limit-settings). @@ -199,7 +203,7 @@ WARNING: Only import projects from sources you trust. If you import a project from an untrusted source, it may be possible for an attacker to steal your sensitive data. -### Prerequisites +#### Prerequisites > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. @@ -209,7 +213,7 @@ may be possible for an attacker to steal your sensitive data. - Review [compatibility](#compatibility) for any issues. - At least the Maintainer role on the destination group to migrate to. -### Import a project +#### Import a project To import a project: @@ -222,7 +226,7 @@ To import a project: To get the status of an import, you can query it through the [API](../../../api/project_import_export.md#import-status). As described in the API documentation, the query may return an import error or exceptions. -### Changes to imported items +#### Changes to imported items Exported items are imported with the following changes: @@ -235,11 +239,11 @@ Exported items are imported with the following changes: Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches. -### Import large projects **(FREE SELF)** +#### Import large projects **(FREE SELF)** If you have a larger project, consider [using a Rake task](../../../administration/raketasks/project_import_export.md#import-large-projects). -## Set maximum import file size **(FREE SELF)** +### Set maximum import file size **(FREE SELF)** Administrators can set the maximum import file size one of two ways: @@ -248,7 +252,7 @@ Administrators can set the maximum import file size one of two ways: The default is `0` (unlimited). -## Rate limits +### Rate limits To help avoid abuse, by default, users are rate limited to: @@ -258,11 +262,161 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 projects per minute | +## Migrate groups by uploading an export file (deprecated) + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6 and replaced by +[migrating groups by direct transfer](../../group/import/index.md). However, this feature is still recommended for migrating groups between +offline systems. To follow progress on an alternative solution for [offline environments](../../application_security/offline_deployments/index.md), see +[the relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/8985). + +Prerequisites: + +- Owner role on the group to migrate. + +Using file exports, you can: + +- Export any group to a file and upload that file to another GitLab instance or to another location on the same instance. +- Use either the GitLab UI or the [API](../../../api/group_import_export.md). +- Migrate groups one by one, then export and import each project for the groups one by one. + +GitLab maps user contributions correctly when an admin access token is used to perform the import. GitLab does not map +user contributions correctly when you are importing from a self-managed instance to GitLab.com. Correct mapping of user +contributions when importing from a self-managed instance to GitLab.com can be preserved with paid involvement of +Professional Services team. + +Note the following: + +- Exports are stored in a temporary directory and are deleted every 24 hours by a specific worker. +- To preserve group-level relationships from imported projects, export and import groups first so that projects can + be imported into the desired group structure. +- Imported groups are given a `private` visibility level, unless imported into a parent group. +- If imported into a parent group, a subgroup inherits the same level of visibility unless otherwise restricted. +- You can export groups from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) + and vice versa. The Enterprise Edition retains some group data that isn't part of the Community Edition. If you're + exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, + see [downgrading from EE to CE](../../../index.md). + +### Compatibility + +> Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/383682) in GitLab 15.8. + +Group file exports are in NDJSON format. + +You can import group file exports that were exported from a version of GitLab up to two +[minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for +[security releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Destination version | Compatible source versions | +|:--------------------|:---------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + +### Exported contents + +The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) +file for groups lists items exported and imported when migrating groups using file exports. View this file in the branch +for your version of GitLab to check which items can be imported to the destination GitLab instance. For example, +[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/group/import_export.yml). + +Group items that are exported include: + +- Milestones +- Group Labels (_without_ associated label priorities) +- Boards and Board Lists +- Badges +- Subgroups (including all the aforementioned data) +- Epics + - Epic resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) +- Events +- [Wikis](../../project/wiki/group.md) + ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9) +- Iterations cadences ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95372) in 15.4) + +Items that are **not** exported include: + +- Projects +- Runner tokens +- SAML discovery tokens + +### Preparation + +- To preserve the member list and their respective permissions on imported groups, review the users in these groups. Make + sure these users exist before importing the desired groups. +- Users must set a public email in the source GitLab instance that matches their confirmed primary email in the destination GitLab instance. Most users receive an email asking them to confirm their email address. + +### Enable export for a group + +Prerequisites: + +- You must have the Owner role for the group. + +To enable import and export for a group: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Visibility and access controls**. +1. In the **Import sources** section, select the checkboxes for the sources you want. + +### Export a group + +Prerequisites: + +- You must have the Owner role for the group. + +To export the contents of a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. In the **Advanced** section, select **Export group**. +1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) + in a compressed tar archive, with contents in NDJSON format. +1. Alternatively, you can download the export from the UI: + + 1. Return to your group's **Settings > General** page. + 1. In the **Advanced** section, select **Download export**. + You can also generate a new file by selecting **Regenerate export**. + +You can also export a group [using the API](../../../api/group_import_export.md). + +### Import the group + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New subgroup**. +1. Select the **import an existing group** link. +1. Enter your group name. +1. Accept or modify the associated group URL. +1. Select **Choose file...**. +1. Select the file that you exported in the [Export a group](#export-a-group) section. +1. To begin importing, select **Import**. + +Your newly imported group page appears after the operation completes. + +NOTE: +The maximum import file size can be set by the administrator, default is `0` (unlimited). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the +[Application settings API](../../../api/settings.md#change-application-settings) or the +[Admin Area](../../../administration/settings/account_and_limit_settings.md). +Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to 0 in GitLab 13.8. + +### Rate limits + +To help avoid abuse, by default, users are rate limited to: + +| Request Type | Limit | +|-----------------|-------| +| Export | 6 groups per minute | +| Download export | 1 download per group per minute | +| Import | 6 groups per minute | + ## Related topics - [Project import and export API](../../../api/project_import_export.md) - [Project import and export administration Rake tasks](../../../administration/raketasks/project_import_export.md) - [Migrating GitLab groups](../../group/import/index.md) - [Group import and export API](../../../api/group_import_export.md) -- [Migrate groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). -- [Migrate groups by using file exports](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated). +- [Migrate groups by direct transfer](../../group/import/index.md). diff --git a/doc/user/project/settings/project_features_permissions.md b/doc/user/project/settings/project_features_permissions.md index 27c0668079c..c1fe9045ea5 100644 --- a/doc/user/project/settings/project_features_permissions.md +++ b/doc/user/project/settings/project_features_permissions.md @@ -173,7 +173,7 @@ To subscribe to a topic: - From the **Explore topics** page: - 1. On the left sidebar, expand the top-most chevron ({**chevron-down**}). + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). 1. Select **Explore**. 1. Select **Topics**. 1. Select the topic you want to subscribe to. diff --git a/doc/user/project/use_project_as_go_package.md b/doc/user/project/use_project_as_go_package.md index 54e9eac7756..bf11cd784cb 100644 --- a/doc/user/project/use_project_as_go_package.md +++ b/doc/user/project/use_project_as_go_package.md @@ -10,7 +10,7 @@ Prerequisites: - Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). - To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause -`go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. + `go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 49efd463334..4aaf7f27229 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -17,71 +17,65 @@ The Web IDE is an advanced editor with commit staging. You can use the Web IDE to make changes to multiple files directly from the GitLab UI. For a more basic implementation, see [Web Editor](../repository/web_editor.md). -To pair the Web IDE with a remote development environment, see [remote development](../remote_development/index.md). +To pair the Web IDE with a remote development environment, see [Remote development](../remote_development/index.md). -## Use the Web IDE +## Open the Web IDE -To open the Web IDE from the GitLab UI: +To open the Web IDE: 1. On the left sidebar, select **Search or go to** and find your project. 1. Use the <kbd>.</kbd> keyboard shortcut. -You can also open the Web IDE from: +### From a file or directory -- A file -- The repository file list -- A merge request +To open the Web IDE from a file or directory: -### From a file or the repository file list - -To open the Web IDE from a file or the repository file list: - -- In the upper right, select **Edit > Open in Web IDE**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Go to your file or directory. +1. Select **Edit > Open in Web IDE**. ### From a merge request To open the Web IDE from a merge request: +1. On the left sidebar, select **Search or go to** and find your project. 1. Go to your merge request. -1. In the upper-right corner, select **Code > Open in Web IDE**. +1. In the upper right, select **Code > Open in Web IDE**. -The Web IDE opens new and modified files in separate tabs and displays changes side by side with the original source. -To optimize loading time, only the top 10 files (by number of lines changed) are opened automatically. +The Web IDE opens new and modified files in separate tabs and displays changes side by side. +To reduce load time, only 10 files with the most lines changed are opened automatically. -In the file tree, any new or modified file in the merge request is indicated by an icon next to the filename. -To view changes to a file, right-click the filename and select **Compare with merge request base**. +On the left **Explorer** sidebar, any new or modified file is indicated +by the merge request icon (**{merge-request}**) next to the file name. +To view changes to a file, right-click the file and select **Compare with merge request base**. -## Open a file in the Web IDE +## Open a file -To open any file by its name: +To open a file by name in the Web IDE: 1. Press <kbd>Command</kbd>+<kbd>P</kbd>. -1. Enter the name of your file. +1. In the search box, enter the file name. -## Search across files +## Search open files -You can use the Web IDE to search all files in the opened folder. - -To search across files: +To search across open files in the Web IDE: 1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>F</kbd>. -1. Enter your search term. - -In the Web IDE, only partial results from opened files are displayed. +1. In the search box, enter your search term. -## View a list of changed files +## View a list of modified files -To view a list of files you changed in the Web IDE: +To view a list of files you modified in the Web IDE: -- On the activity bar on the left, select **Source Control**, - or press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. +- On the left activity bar, select **Source Control**, or + press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. For more information, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). ## Restore uncommitted changes -You don't have to manually save any file you modify in the Web IDE. +You do not have to manually save any file you modify in the Web IDE. Modified files are automatically staged and can be [committed](#commit-changes). Uncommitted changes are saved in your browser's local storage and persist even if you close the browser tab or refresh the Web IDE. @@ -93,68 +87,67 @@ To restore uncommitted changes in the Web IDE: 1. In the search box, enter `Local History: Find Entry to Restore`. 1. Select the file that contains the uncommitted changes. -## Upload a new file +## Upload a file + +To upload a file in the Web IDE: + +1. On the left activity bar, select **Explorer**, or + press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>E</kbd>. +1. Go to the directory where you want to upload the file. + To create a new directory: -To upload a new file in the Web IDE: + - On the left **Explorer** sidebar, in the upper right, + select **New Folder** (**{folder-new}**). -1. On the activity bar on the left, select **Explorer** and go to the directory where you want to upload the file. -1. Optional. For a new directory, go to the path where you want to have the directory and do one of the following: - - Right-click the path, and select **New Folder...**. You can create a nested path with `/` (for example, `parentdir/subdir1/subdir2`). - - In the upper right of the **Explorer** panel, select **New Folder...** (**{folder-new}**). -1. Enter the name of the new directory, and press <kbd>Enter</kbd>. -1. Right-click the path, and select **Upload...**. -1. Select the file you want to upload, then select **Open**. You can upload multiple files at once. +1. Right-click the directory and select **Upload**. +1. Select the file you want to upload. -The new file is uploaded and automatically added to the repository. +You can upload multiple files at once. +The files are uploaded and automatically added to the repository. ## Switch branches -The Web IDE uses the currently selected branch by default. +The Web IDE uses the current branch by default. To switch branches in the Web IDE: -1. On the status bar, in the lower-left corner, select the current branch name. -1. In the search box, start typing the branch name. -1. From the dropdown list, select the branch. +1. On the bottom status bar, on the left, select the current branch name. +1. Enter or select an existing branch. ## Create a branch To create a branch from the current branch in the Web IDE: -1. On the status bar, in the lower-left corner, select the current branch name. -1. From the dropdown list, select **Create new branch...**. -1. Enter the branch name. -1. Press <kbd>Enter</kbd>. +1. On the bottom status bar, on the left, select the current branch name. +1. From the dropdown list, select **Create new branch**. +1. Enter the new branch name. -If you don't have write access to the repository, **Create new branch...** is not visible. +If you do not have write access to the repository, **Create new branch** is not visible. ## Commit changes To commit changes in the Web IDE: -1. On the activity bar on the left, select **Source Control**, - or press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. +1. On the left activity bar, select **Source Control**, or + press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. 1. Enter your commit message. -1. Select **Commit & Push**. -1. Commit to the current branch, or [create a new branch](#create-a-branch). +1. Commit to the current branch or [create a new branch](#create-a-branch). ## Create a merge request -To create a merge request in the Web IDE: +To create a [merge request](../merge_requests/index.md) in the Web IDE: 1. [Commit the changes](#commit-changes). -1. In the pop-up notification in the lower-right corner, select **Create Merge Request**. - A new window opens for you to create the [merge request](../merge_requests/index.md). +1. In the notification that appears in the lower right, select **Create MR**. -To access missed notifications, see [Access notifications](#access-notifications). +For more information, see [View missed notifications](#view-missed-notifications). ## Use the command palette -In the Web IDE, you can access many commands through the command palette. +You can use the command palette to access many commands. To open the command palette and run a command in the Web IDE: 1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd>. -1. In the search box, start typing the command name. -1. From the dropdown list, select the command. +1. Enter or select the command. ## Edit settings @@ -168,7 +161,8 @@ In the settings editor, you can search for the settings you want to modify. ## Edit keyboard shortcuts -You can use the keyboard shortcuts editor to view and modify the default keybindings for all available commands. +You can use the keyboard shortcuts editor to view and modify +the default keybindings for all available commands. To open the keyboard shortcuts editor in the Web IDE: - On the top menu bar, select **File > Preferences > Keyboard Shortcuts**, @@ -179,13 +173,15 @@ In the keyboard shortcuts editor, you can search for: - The keybindings you want to change - The commands you want to add or remove keybindings for -Keybindings are based on your keyboard layout. If you change your keyboard layout, existing keybindings are updated automatically. +Keybindings are based on your keyboard layout. +If you change your keyboard layout, existing keybindings are updated automatically. -## Change themes +## Change the color theme -You can choose between different themes for the Web IDE. The default theme for the Web IDE is **GitLab Dark**. +You can choose between different color themes for the Web IDE. +The default theme is **GitLab Dark**. -To change the Web IDE theme: +To change the color theme in the Web IDE: 1. On the top menu bar, select **File > Preferences > Theme > Color Theme**, or press <kbd>Command</kbd>+<kbd>K</kbd> then <kbd>Command</kbd>+<kbd>T</kbd>. @@ -194,12 +190,13 @@ To change the Web IDE theme: The active color theme is stored in the [user settings](#edit-settings). -## Access notifications +## View missed notifications -When you perform actions in the Web IDE, notifications appear in the lower-right corner. To access missed notifications: +When you perform actions in the Web IDE, notifications appear in the lower right. +To view any notification you might have missed: -1. On the status bar, in the lower-right corner, select the bell (**{notifications}**) for a list of notifications. -1. Select the notification you want to access. +1. On the bottom status bar, on the right, select the bell icon (**{notifications}**) for a list of notifications. +1. Select the notification you want to view. <!-- ## Privacy and data collection for extensions @@ -215,7 +212,7 @@ To protect your privacy and data: - Carefully review the permissions requested by an extension before you install the extension. - Keep your extensions up to date to ensure that any security or privacy vulnerabilities are addressed promptly. --> -## Interactive web terminals for the Web IDE **(BETA)** +## Interactive web terminals **(BETA)** WARNING: This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. @@ -228,21 +225,25 @@ When you set up a remote development server in the Web IDE, you can use interact You cannot use interactive web terminals to interact with a runner. However, you can use a terminal to install dependencies and compile and debug code. -For more information about configuring a workspace that supports interactive web terminals, see [remote development](../remote_development/index.md). +For more information, see [Remote development](../remote_development/index.md). ## Related topics -- [GitLab Duo Chat in the Web IDE](../../gitlab_duo_chat.md#web-ide) +- [GitLab Duo Chat in the Web IDE](../../gitlab_duo_chat.md#use-gitlab-duo-chat-in-the-web-ide) ## Troubleshooting When working with the Web IDE, you might encounter the following issues. -### Character offset in the Web IDE +### Character offset when typing -When you type in the Web IDE, you might get a four-character offset. To resolve the issue, do one of the following: +When you type in the Web IDE, you might get a four-character offset. +As a workaround: -- Add `"editor.disableMonospaceOptimizations": true` to your settings. -- Modify your `"editor.font"` setting. +1. On the top menu bar, select **File > Preferences > Settings**, + or press <kbd>Command</kbd>+<kbd>,</kbd>. +1. In the upper-right corner, select **Open Settings (JSON)**. +1. In the `settings.json` file, add `"editor.disableMonospaceOptimizations": true` + or modify the `"editor.fontFamily"` setting. For more information, see [VS Code issue 80170](https://github.com/microsoft/vscode/issues/80170). diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 64f6fa2c75e..59e949c5218 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -37,7 +37,7 @@ To access a group wiki: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9. Users with the Owner role in a group can -[import or export a group wiki](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated) when they +[import or export a group wiki](../../project/settings/import_export.md#migrate-groups-by-uploading-an-export-file-deprecated) when they import or export a group. Content created in a group wiki is not deleted when an account is downgraded or a @@ -47,7 +47,7 @@ the wiki is exported. To access the group wiki data from the export file if the feature is no longer available, you have to: -1. Extract the [export file tarball](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated) +1. Extract the [export file tarball](../../project/settings/import_export.md#migrate-groups-by-uploading-an-export-file-deprecated) with this command, replacing `FILENAME` with your file's name: `tar -xvzf FILENAME.tar.gz` 1. Browse to the `repositories` directory. This directory contains a diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index f4946230360..07c5ce73470 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -94,8 +94,12 @@ Users with at least the Developer role can create new wiki pages: Wikis are based on Git repositories, so you can clone them locally and edit them like you would do with every other Git repository. To clone a wiki repository -locally, select **Clone repository** from the right-hand sidebar of any wiki page, -and follow the on-screen instructions. +locally: + +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Plan > Wiki**. +1. On the right sidebar, select **Clone repository**. +1. Follow the on-screen instructions. Files you add to your wiki locally must use one of the following supported extensions, depending on the markup language you wish to use. @@ -155,7 +159,9 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need at least the Developer role to delete a wiki page: +Prerequisites: + +- You must have at least the Developer role. 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. @@ -166,7 +172,9 @@ You need at least the Developer role to delete a wiki page: ## Move a wiki page -You need at least the Developer role to move a wiki page: +Prerequisites: + +- You must have at least the Developer role. 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. @@ -245,8 +253,11 @@ Commits to wikis are not counted in [repository analytics](../../analytics/repos > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -You need at least the Developer role to customize the wiki -navigation sidebar. This process creates a wiki page named `_sidebar` which fully +Prerequisites: + +- You must have at least the Developer role. + +This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: 1. On the left sidebar, select **Search or go to** and find your project or group. @@ -312,7 +323,7 @@ To disable a project's internal wiki: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. -1. Scroll down to find **Wiki** and toggle it off (in gray). +1. Scroll down to find and turn off the **Wiki** toggle (in gray). 1. Select **Save changes**. The internal wiki is now disabled, and users and project members: diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 1c60f3bebf3..7d8305519e4 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -61,7 +61,7 @@ Prerequisites: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. In the **Project name** text box, enter your project name. See the [limitations on project names](../../user/reserved_names.md). -1. In the **Project description** text box, enter your project description. The description is limited to 500 characters. +1. In the **Project description** text box, enter your project description. The description is limited to 2,000 characters. 1. Under **Project avatar**, to change your project avatar, select **Choose file**. ## Star a project @@ -121,7 +121,7 @@ You can [view projects that are pending deletion](#view-projects-pending-deletio and use the Rails console to [find projects that are pending deletion](#find-projects-that-are-pending-deletion). -### Delete a project immediately +### Delete a project immediately **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. > - Option to delete projects immediately from the Admin Area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. @@ -144,7 +144,7 @@ To immediately delete a project marked for deletion: 1. In the **Delete this project** section, select **Delete project**. 1. On the confirmation dialog, enter the project name and select **Yes, delete project**. -### View projects pending deletion +### View projects pending deletion **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. > - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. @@ -309,7 +309,7 @@ Prerequisites: 1. [Create a group](../group/index.md#create-a-group) to track membership of your project. 1. [Set up LDAP synchronization](../../administration/auth/ldap/ldap_synchronization.md) for that group. 1. To use LDAP groups to manage access to a project, -[add the LDAP-synchronized group as a member](../group/manage.md) to the project. + [add the LDAP-synchronized group as a member](../group/manage.md) to the project. ## Troubleshooting diff --git a/doc/user/public_access.md b/doc/user/public_access.md index b7ee354ed9a..826f9548982 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -8,11 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w Projects and groups in GitLab can be private, internal, or public. -The visibility level of the group or project has no influence on whether members within the group or project can see each other. -A group or project is an object to allow collaborative work. This is only possible if all members know about each other. +The visibility level of the project or group does not affect whether members of the project or group can see each other. +Projects and groups are intended for collaborative work. This work is only possible if all members know about each other. -Group or project members can see all members of the group or project they belong to. -Group or project owners can see the origin of membership (the original group or project) of all members. +Project or group members can see all members of the project or group they belong to. +Project or group members can see the origin of membership (the original project or group) of all members for the projects and groups they have access to. ## Private projects and groups @@ -38,15 +38,9 @@ Only internal members can view internal content. Internal groups can have internal or private subgroups. -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. For more information, see -[issue 12388](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). - ## Public projects and groups -For public projects, **users who are not authenticated**, including users with the Guest role, can: +For public projects, **unauthenticated users**, including users with the Guest role, can: - Clone the project. - View the public access directory (`/public`). @@ -56,7 +50,7 @@ Public groups can have public, internal, or private subgroups. NOTE: If an administrator restricts the [**Public** visibility level](../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels), -then `/public` is visible only to authenticated users. +then the public access directory (`/public`) is visible only to authenticated users. ## Change project visibility @@ -85,7 +79,7 @@ Prerequisites: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. -1. To enable or disable a feature, turn on or off the feature toggle. +1. To enable or disable a feature, turn on or turn off the feature toggle. 1. Select **Save changes**. ## Change group visibility @@ -95,9 +89,9 @@ You can change the visibility of all projects in a group. Prerequisites: - You must have the Owner role for a group. -- Subgroups and projects must already have visibility settings that are at least as +- Projects and subgroups must already have visibility settings that are at least as restrictive as the new setting of the parent group. For example, you cannot set a group - to private if a subgroup or project in that group is public. + to private if a project or subgroup in that group is public. 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 3b715fb13da..757231ffb80 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -30,10 +30,10 @@ You can use advanced search in: ## Enable advanced search -- On GitLab.com, advanced search is enabled for groups with paid subscriptions. -- For self-managed GitLab instances, an administrator must +- For [GitLab SaaS](../../subscriptions/gitlab_com/index.md) and [GitLab Dedicated](../../subscriptions/gitlab_dedicated/index.md), + advanced search is enabled in paid subscriptions. +- For [GitLab self-managed](../../subscriptions/self_managed/index.md), an administrator must [enable advanced search](../../integration/advanced_search/elasticsearch.md#enable-advanced-search). -- For GitLab Dedicated, advanced search is enabled. ## Syntax diff --git a/doc/user/storage_management_automation.md b/doc/user/storage_management_automation.md index f25ae8ba92d..e04a7f1bdee 100644 --- a/doc/user/storage_management_automation.md +++ b/doc/user/storage_management_automation.md @@ -78,7 +78,7 @@ For more information, see the [GitLab CLI endpoint documentation](../editor_exte The storage management and cleanup automation methods described in this page use: - The [`python-gitlab`](https://python-gitlab.readthedocs.io/en/stable/) library, which provides -a feature-rich programming interface. + a feature-rich programming interface. - The `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` script in the [GitLab API with Python](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/) project. For more information about use cases for the `python-gitlab` library, diff --git a/doc/user/tasks.md b/doc/user/tasks.md index 1ec211dcab3..3f26329485b 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -366,7 +366,7 @@ To copy the task reference to your clipboard: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select your task. -1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. You can now paste the reference into another description or comment. @@ -386,7 +386,7 @@ To copy the task's email address: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. -1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy task email address**. +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy task email address**. ## Set an issue as a parent @@ -442,7 +442,7 @@ Check that box and select **Create task**. To change the confidentiality of an existing task: 1. [Open the task](#view-tasks). -1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Turn on confidentiality**. ### Who can see confidential tasks @@ -497,6 +497,7 @@ or assignees, on the right. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7. +> - Adding related items by entering their URLs and IDs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427594) in GitLab 16.8. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `linked_work_items`. @@ -524,7 +525,7 @@ To link an item to a task: - **relates to** - **blocks** - **is blocked by** -1. Enter the search text of the item. +1. Enter the search text of the item, URL, or its reference ID. 1. When you have added all the items to be linked, select **Add** below the search box. When you have finished adding all linked items, you can see diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 973ad9d0b07..2dc5c1ef819 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -163,11 +163,11 @@ Storage limits are included in GitLab subscription terms but do not apply. At le GitLab will notify you of namespaces that exceed, or are close to exceeding, the storage limit. - In the command-line interface, a notification displays after each `git push` -action when your namespace has reached between 95% and 100% of your namespace storage quota. + action when your namespace has reached between 95% and 100% of your namespace storage quota. - In the GitLab UI, a notification displays when your namespace has reached between -75% and 100% of your namespace storage quota. + 75% and 100% of your namespace storage quota. - GitLab sends an email to members with the Owner role to notify them when namespace -storage usage is at 70%, 85%, 95%, and 100%. + storage usage is at 70%, 85%, 95%, and 100%. ## Manage storage usage diff --git a/doc/user/version.md b/doc/user/version.md index d39c0394610..2dcaf16d53b 100644 --- a/doc/user/version.md +++ b/doc/user/version.md @@ -1,6 +1,7 @@ --- stage: none group: none +description: Version information. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/workspace/gitlab_agent_configuration.md b/doc/user/workspace/gitlab_agent_configuration.md index 0e35c72c5ef..bef935f2426 100644 --- a/doc/user/workspace/gitlab_agent_configuration.md +++ b/doc/user/workspace/gitlab_agent_configuration.md @@ -20,12 +20,14 @@ provided that the agent is properly configured for remote development. ## Remote development settings -| Setting | Description | -|-------------------------------------------------------|:---------------------------------------------------------------------| -| [`enabled`](#enabled) | Indicates whether remote development is enabled for the GitLab agent | -| [`dns_zone`](#dns_zone) | DNS zone where workspaces are available | -| [`gitlab_workspaces_proxy`](#gitlab_workspaces_proxy) | Namespace where [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed | -| [`network_policy`](#network_policy) | Firewall rules for workspaces | +| Setting | Description | +|-------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------| +| [`enabled`](#enabled) | Indicates whether remote development is enabled for the GitLab agent. | +| [`dns_zone`](#dns_zone) | DNS zone where workspaces are available. | +| [`gitlab_workspaces_proxy`](#gitlab_workspaces_proxy) | Namespace where [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed. | +| [`network_policy`](#network_policy) | Firewall rules for workspaces. | +| [`default_resources_per_workspace_container`](#default_resources_per_workspace_container) | Default requests and limits for CPU and memory per workspace container. | +| [`max_resources_per_workspace`](#max_resources_per_workspace) | Maximum requests and limits for CPU and memory per workspace. | NOTE: If a setting has an invalid value, it's not possible to update any setting until you fix that value. @@ -85,6 +87,7 @@ The default value is: ```yaml remote_development: network_policy: + enabled: true egress: - allow: "0.0.0.0/0" except: @@ -141,6 +144,64 @@ In this example, traffic from the workspace is allowed if: - The destination IP is any range except `10.0.0.0/8`, `172.16.0.0/12`, or `192.168.0.0/16`. - The destination IP is `172.16.123.1/32`. +### `default_resources_per_workspace_container` + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11625) in GitLab 16.8. + +Use this setting to define the default [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) +for CPU and memory per workspace container. +Any resources you define in your [devfile](index.md#devfile) override this setting. + +For `default_resources_per_workspace_container`, `requests` and `limits` are required. +For more information about possible CPU and memory values, see [Resource units in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes). + +When you change any of these values, existing workspaces restart immediately for the changes to take effect. + +**Example configuration:** + +```yaml +remote_development: + default_resources_per_workspace_container: + requests: + cpu: "0.5" + memory: "512Mi" + limits: + cpu: "1" + memory: "1Gi" +``` + +### `max_resources_per_workspace` + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11625) in GitLab 16.8. + +Use this setting to define the maximum [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) +for CPU and memory per workspace. + +For `max_resources_per_workspace`, `requests` and `limits` are required. +For more information about possible CPU and memory values, see: + +- [Resource units in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) +- [Resource quotas](https://kubernetes.io/docs/concepts/policy/resource-quotas/) + +When you change any of these values, existing workspaces restart immediately for the changes to take effect. +Workspaces fail when they exceed the values you set for `requests` and `limits`. + +**Example configuration:** + +```yaml +remote_development: + max_resources_per_workspace: + requests: + cpu: "1" + memory: "1Gi" + limits: + cpu: "2" + memory: "2Gi" +``` + +The maximum resources you define must include any resources required for init containers +to perform bootstrapping operations such as cloning the project repository. + ## Configuring user access with remote development You can configure the `user_access` module to access the connected Kubernetes cluster with your GitLab credentials. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index d24102afcf9..5fa6108de6f 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -67,32 +67,37 @@ The devfile is used to automatically configure the development environment with This way, you can create consistent and reproducible development environments regardless of the machine or platform you use. -### Relevant schema properties - -GitLab only supports the `container` and `volume` components in [devfile 2.2.0](https://devfile.io/docs/2.2.0/devfile-schema). -Use the `container` component to define a container image as the execution environment for a devfile workspace. +### Validation rules + +- `schemaVersion` must be [`2.2.0`](https://devfile.io/docs/2.2.0/devfile-schema). +- The devfile must have at least one component. +- For `components`: + - Names must not start with `gl-`. + - Only [`container`](#container-component-type) and `volume` are supported. +- For `commands`, IDs must not start with `gl-`. +- For `events`: + - Names must not start with `gl-`. + - Only `preStart` is supported. +- `parent`, `projects`, and `starterProjects` are not supported. +- For `variables`, keys must not start with `gl-`, `gl_`, `GL-`, or `GL_`. + +### `container` component type + +Use the `container` component type to define a container image as the execution environment for a workspace. You can specify the base image, dependencies, and other settings. -Only these properties are relevant to the GitLab implementation of the `container` component: - -| Properties | Definition | -|----------------| ----------------------------------------------------------------------------------| -| `image` | Name of the container image to use for the workspace. | -| `memoryRequest`| Minimum amount of memory the container can use. | -| `memoryLimit` | Maximum amount of memory the container can use. | -| `cpuRequest` | Minimum amount of CPU the container can use. | -| `cpuLimit` | Maximum amount of CPU the container can use. | -| `env` | Environment variables to use in the container. | -| `endpoints` | Port mappings to expose from the container. | -| `volumeMounts` | Storage volume to mount in the container. | - -### Using variables in a devfile - -You can define variables to use in your devfile. -The `variables` object is a map of name-value pairs that you can use for string replacement in the devfile. - -Variables cannot have names that start with `gl-`, `gl_`, `GL-`, or `GL_`. -For more information about how and where to use variables, see the [devfile documentation](https://devfile.io/docs/2.2.0/defining-variables). +The `container` component type supports the following schema properties only: + +| Property | Description | +|----------------| -------------------------------------------------------------------------------------------------------------------------------| +| `image` | Name of the container image to use for the workspace. | +| `memoryRequest`| Minimum amount of memory the container can use. | +| `memoryLimit` | Maximum amount of memory the container can use. | +| `cpuRequest` | Minimum amount of CPU the container can use. | +| `cpuLimit` | Maximum amount of CPU the container can use. | +| `env` | Environment variables to use in the container. Names must not start with `gl-`. | +| `endpoints` | Port mappings to expose from the container. Names must not start with `gl-`. | +| `volumeMounts` | Storage volume to mount in the container. | ### Example configurations |
