diff options
Diffstat (limited to 'doc/user')
316 files changed, 5972 insertions, 4315 deletions
diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md index 9558e40d56f..feea06666dc 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -5,62 +5,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# AI/ML powered features +# GitLab Duo GitLab is creating AI-assisted features across our DevSecOps platform. These features aim to help increase velocity and solve key pain points across the software development lifecycle. -## Enable AI/ML features - -> Introduced in GitLab 16.0 and [actively being rolled out](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118222). - -Prerequisites: - -- You must have the Owner role for the group. - -To enable AI/ML features for a top-level group: - -- Enable [Experiment features](group/manage.md#enable-experiment-features). -- Enable [third-party AI features](group/manage.md#enable-third-party-ai-features) (enabled by default). - To disable AI features powered by third-party APIs, clear this setting. +| Feature | Purpose | Large Language Model | Current availability | Maturity | +|-|-|-|-|-| +| [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | Assists in creating faster and higher-quality reviews by automatically suggesting reviewers for your merge request. | GitLab creates a machine learning model for each project, which is used to generate reviewers <br><br> [View the issue](https://gitlab.com/gitlab-org/modelops/applied-ml/applied-ml-updates/-/issues/10) | SaaS only | [Generally Available (GA)](../policy/experiment-beta-support.md#generally-available-ga) | +| [Code Suggestions](project/repository/code_suggestions/index.md) | Helps you write code more efficiently by viewing code suggestions as you type. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS <br> Self-managed | [Beta](../policy/experiment-beta-support.md#beta) | +| [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | Helps you remediate vulnerabilities more efficiently, uplevel your skills, and write more secure code. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) <br><br> Anthropic's claude model if degraded performance | SaaS only <br><br> Ultimate tier | [Beta](../policy/experiment-beta-support.md#beta) | +| [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | Helps you understand code by explaining it in English language. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Chat](#answer-questions-with-chat) | Process and generate 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. | Anthropic's claude model <br><br> OpenAI Embeddings | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | Assists you with predicting productivity metrics and identifying anomalies across your software development lifecycle. | Statistical forecasting | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | Assists with quickly getting everyone up to speed on lengthy conversations to help ensure you are all on the same page. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Merge request summary](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) | Efficiently communicate the impact of your merge request changes. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Code review summary](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) | Helps ease merge request handoff between authors and reviewers and help reviewers efficiently understand suggestions. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | Generate a description for the merge request based on the contents of the template. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | Automates repetitive tasks and helps catch bugs early. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | Helps you discover or recall Git commands when and where you need them. | OpenAI | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| **Root cause analysis** | Assists you in determining the root cause for a pipeline failure and failed CI/CD build. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | +| [Issue description generation](#summarize-an-issue-with-issue-description-generation) | Generate issue descriptions. | [Google Vertex Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) | SaaS only | [Experiment](../policy/experiment-beta-support.md#experiment) | -These settings work together so you can have a mix of both experimental and third-party AI features. - -## Generally Available AI features - -When a feature is [Generally Available](../policy/experiment-beta-support.md#generally-available-ga), -it does not require [Experiment features to be enabled](group/manage.md#enable-experiment-features). -Some of these features might require [third-party AI features to be enabled](group/manage.md#enable-third-party-ai-features). - -The following feature is Generally Available: - -- [Suggested Reviewers](project/merge_requests/reviews/index.md#suggested-reviewers) +## Enable AI/ML features -## Beta AI features +The [Generally Available](../policy/experiment-beta-support.md#generally-available-ga) features listed in the previous table do not need to be enabled. -[Beta features](../policy/experiment-beta-support.md#beta) do not require -[Experiment features to be enabled](group/manage.md#enable-experiment-features). +[Experiment features](../policy/experiment-beta-support.md#experiment) and [Beta features](../policy/experiment-beta-support.md#beta) (besides Code Suggestions) on SaaS must be enabled by a user who has the Owner role in the group. Their usage is subject to the [Testing Terms of Use](https://about.gitlab.com/handbook/legal/testing-agreement/). -The following features are in Beta: +In addition, all features built on large language models (LLM) from Google, Anthropic or OpenAI require that [third-party AI features are enabled](group/manage.md#enable-third-party-ai-features) (which they are by default). The table above shows which features are built on which LLM. To disable AI features powered by third-party APIs, clear this setting. -- [Code Suggestions](project/repository/code_suggestions.md) -- [Explain this vulnerability](application_security/vulnerabilities/index.md#explaining-a-vulnerability-beta) +Code Suggestions currently has its own settings: -## Experiment AI features +- View [how to enable for self-managed](project/repository/code_suggestions/saas.md#enable-code-suggestions). +- View [how to enable for SaaS](project/repository/code_suggestions/self_managed.md#enable-code-suggestions-on-self-managed-gitlab). -[Experiment](../policy/experiment-beta-support.md#experiment) AI features require -[Experiment features to be enabled](group/manage.md#enable-experiment-features) as well as [third-party AI services to be enabled](group/manage.md#enable-third-party-ai-features). +The use of Code Suggestions is also subject to the [Testing Terms of Use](https://about.gitlab.com/handbook/legal/testing-agreement/). -The following features are in Experiment: + -- [Fill in merge request templates](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) -- [Summarize merge request changes](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) -- [Summarize my merge request review](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) -- [Suggested merge or squash commit message](project/merge_requests/ai_in_merge_requests.md#suggested-merge-or-squash-commit-message) -- [Generate suggested tests in merge requests](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) +## Experimental AI features and how to use them -The rest of the features described on this page are also in the Experiment phase. +The following subsections describe the experimental AI features in more detail. -### Explain Selected Code in the Web UI **(ULTIMATE SAAS)** +### Explain code in the Web UI with Code explanation **(ULTIMATE SAAS EXPERIMENT)** > Introduced in GitLab 15.11 as an [Experiment](../policy/experiment-beta-support.md#experiment) on GitLab.com. @@ -75,7 +62,7 @@ By using a large language model, GitLab can explain the code in natural language Prerequisites: -Additional prerequisites [beyond the two above](#experiment-ai-features). +Additional prerequisites in addition to [the settings listed previously](#enable-aiml-features). - The project must be on GitLab.com. - You must have the GitLab Ultimate subscription tier. @@ -83,7 +70,7 @@ Additional prerequisites [beyond the two above](#experiment-ai-features). To explain your code: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select any file in your project that contains code. 1. On the file, select the lines that you want to have explained. 1. On the left side, select the question mark (**{question}**). You might have to scroll to the first line of your selection to view it. This sends the selected code, together with a prompt, to provide an explanation to the large language model. @@ -93,7 +80,7 @@ To explain your code: You can also have code explained in the context of a merge request. To explain code in a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Code > Merge requests**, then select your merge request. 1. On the secondary menu, select **Changes**. 1. On the file you would like explained, select the three dots (**{ellipsis_v}**) and select **View File @ $SHA**. @@ -109,7 +96,7 @@ code in a merge request: We cannot guarantee that the large language model produces results that are correct. Use the explanation with caution. -### GitLab Duo Chat **(ULTIMATE SAAS)** +### Answer questions with Chat **(ULTIMATE SAAS EXPERIMENT)** > Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). @@ -154,7 +141,7 @@ Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/ NOTE: Only the last 50 messages are retained in the chat history. The chat history expires 3 days after last use. -### Summarize issue discussions **(ULTIMATE SAAS)** +### Summarize issue discussions with Discussion summary **(ULTIMATE SAAS EXPERIMENT)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). @@ -174,7 +161,7 @@ Provide feedback on this experimental feature in [issue 407779](https://gitlab.c **Data usage**: When you use this feature, the text of public comments on the issue are sent to the large language model referenced above. -### Show deployment frequency forecast **(ULTIMATE SAAS)** +### Forecast deployment frequency with Value stream forecasting **(ULTIMATE ALL EXPERIMENT)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10228) in GitLab 16.2 as an [Experiment](../policy/experiment-beta-support.md#experiment). @@ -182,7 +169,7 @@ This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab. In CI/CD Analytics, you can view a forecast of deployment frequency: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > CI/CD analytics**. 1. Select the **Deployment frequency** tab. 1. Turn on the **Show forecast** toggle. @@ -191,9 +178,11 @@ In CI/CD Analytics, you can view a forecast of deployment frequency: The forecast is displayed as a dotted line on the chart. Data is forecasted for a duration that is half of the selected date range. For example, if you select a 30-day range, a forecast for the following 15 days is displayed. + + Provide feedback on this experimental feature in [issue 416833](https://gitlab.com/gitlab-org/gitlab/-/issues/416833). -### Generate issue descriptions **(ULTIMATE SAAS)** +### Summarize an issue with Issue description generation **(ULTIMATE SAAS EXPERIMENT)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10762) in GitLab 16.3 as an [Experiment](../policy/experiment-beta-support.md#experiment). diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index 49870e8c66c..68b9fef5cc7 100644 --- a/doc/user/analytics/analytics_dashboards.md +++ b/doc/user/analytics/analytics_dashboards.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://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Analytics dashboards (Experiment) **(ULTIMATE ALL)** +# Analytics dashboards **(ULTIMATE ALL EXPERIMENT)** > Introduced in GitLab 15.9 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. Disabled by default. @@ -29,15 +29,16 @@ The following data sources are configured for analytics dashboards: ## Built-in dashboards To help you get started with analytics, GitLab provides built-in dashboards with predefined visualizations. +These dashboards are labeled **By GitLab**, and you cannot edit them. +Instead, you can create a custom dashboard with a similar style. ### Product analytics +When [product analytics](../product_analytics/index.md) is enabled and onboarded, two built-in dashboard are added: + - **Audience** displays metrics related to traffic, such as the number of users and sessions. - **Behavior** displays metrics related to user activity, such as the number of page views and events. -These dashboards are labeled **By GitLab**, and you cannot edit them. -Instead, you can create a custom dashboard with a similar style. - ### Value Stream Management - **Value Streams Dashboard** displays metrics related to [DevOps performance, security exposure, and workstream optimization](../analytics/value_streams_dashboard.md#devsecops-metrics-comparison-panel). @@ -64,9 +65,6 @@ On self-managed GitLab, by default this feature is not available. To make it ava On GitLab.com, this feature is not available. This feature is not ready for production use. -NOTE: -This feature does not work in conjunction with the `product_analytics_snowplow_support` feature flag. - You can use the dashboard designer to: - Create custom dashboards. @@ -82,7 +80,7 @@ Prerequisite: To view a list of dashboards (both built-in and custom) for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Analytics dashboards**. 1. From the list of available dashboards, select the dashboard you want to view. @@ -97,9 +95,9 @@ This feature will be connected to group-level dashboards as part of [issue #4115 To change the location of a group's dashboards: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project you want to store your dashboard files in. +1. On the left sidebar, select **Search or go to** and find the project you want to store your dashboard files in. The project must belong to the group for which you create the dashboards. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Analytics**. 1. In the **Analytics Dashboards** section, select your dashboard files project. @@ -116,10 +114,10 @@ You can share dashboards only between projects that are located in the same grou To change the location of project dashboards: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project, +1. On the left sidebar, select **Search or go to** and find your project, or select **Create new...** (**{plus}**) and **New project/repository** to create the project to store your dashboard files. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and find the analytics project. +1. On the left sidebar, select **Search or go to** and find the analytics project. 1. Select **Settings > General**. 1. Expand **Analytics**. 1. In the **Analytics Dashboards** section, select your dashboard files project. @@ -180,7 +178,7 @@ create a `line_chart.yaml` file with the following required fields: To create a custom dashboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Analytics dashboards**. 1. Select **New dashboard**. 1. In the **New dashboard** input, enter the name of the dashboard. @@ -194,7 +192,7 @@ You can edit your custom dashboard's title and add or resize visualizations in t To edit an existing custom dashboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Analytics dashboards**. 1. From the list of available dashboards, select a custom dashboard (one without the `By GitLab` label) you want to edit. 1. Select **Edit**. @@ -209,9 +207,13 @@ To edit an existing custom dashboard: If the dashboard displays a global error message that data could not be loaded, first try reloading the page. If the error persists: -- Check that your configurations match the [JSON schema](#define-a-dashboard) defined in `ee/app/validators/json_schemas/analytics_dashboard.json`. +- Check that your configurations match the [dashboard JSON schema](#define-a-dashboard) defined in `ee/app/validators/json_schemas/analytics_dashboard.json`. - For product analytics, check your [admin and project settings](../product_analytics/index.md#project-level-settings), and make sure they are set up correctly. +### `Invalid visualization configuration` + +If a dashboard panel displays a message that the visualization configuration is invalid, check that your visualization configurations match the [visualization JSON schema](#define-a-chart-visualization) defined in `ee/app/validators/json_schemas/analytics_visualization.json`. + ### Dashboard panel error If a dashboard panel displays an error message: diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 8dc69b2f664..61bc77e4469 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -32,7 +32,7 @@ View pipeline duration history: To view CI/CD analytics: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > CI/CD analytics**. ## View DORA deployment frequency chart **(ULTIMATE ALL)** @@ -50,7 +50,7 @@ The deployment frequency chart is available for groups and projects. To view the deployment frequency chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > CI/CD analytics**. 1. Select the **Deployment frequency** tab. @@ -72,7 +72,7 @@ merge requests to be deployed to a production environment. This chart is availab To view the lead time for changes chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > CI/CD analytics**. 1. Select the **Lead time** tab. @@ -88,7 +88,7 @@ Time to restore service is one of the four DORA metrics that DevOps teams use fo To view the time to restore service chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > CI/CD analytics**. 1. Select the **Time to restore service** tab. @@ -104,6 +104,6 @@ Change failure rate is one of the four DORA metrics that DevOps teams use for me To view the change failure rate chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > CI/CD analytics**. 1. Select the **Change failure rate** tab. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 27d3e45803e..e5b475d0e45 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -34,7 +34,7 @@ Prerequisite: To view code review analytics: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Code review analytics**. 1. Optional. Filter results: 1. Select the filter bar. diff --git a/doc/user/analytics/contributor_statistics.md b/doc/user/analytics/contributor_statistics.md index 514f1ca42ab..ee10522e80b 100644 --- a/doc/user/analytics/contributor_statistics.md +++ b/doc/user/analytics/contributor_statistics.md @@ -15,7 +15,7 @@ and line charts with the number of commits by each project member. To view contributor statistics for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Contributor statistics**. 1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. 1. To view the number of commits made on a specific day, hover over the line chart. @@ -28,7 +28,7 @@ To view contributor statistics for a project: To view a list of commits made by project members per day: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Contributor statistics**. 1. Select **History**. 1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. @@ -42,7 +42,7 @@ To view a list of commits made by project members per day: To view the list of commits to the project as an RSS feed in Atom format: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Contributor statistics**. 1. Select **History**. 1. In the upper-right corner, select the feed symbol (**{rss}**). diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index 0efe4a53427..391a1c7965f 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # DevOps Research and Assessment (DORA) metrics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. -> - [Added support](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) for lead time for changes in GitLab 13.10. +> - Lead time for changes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) in GitLab 13.10. The [DevOps Research and Assessment (DORA)](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance) team has identified four metrics that measure DevOps performance. @@ -33,7 +33,7 @@ This enables teams and managers to understand all aspects of productivity, quali ## Deployment frequency -> [Fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/394712) the frequency calculation formula for the `all` and `monthly` intervals in GitLab 16.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394712) fix for the frequency calculation formula for `all` and `monthly` intervals in GitLab 16.0. Deployment frequency is the frequency of successful deployments to production over the given date range (hourly, daily, weekly, monthly, or yearly). @@ -144,6 +144,24 @@ The table below provides an overview of the DORA metrics' data aggregation in di | Time to restore service | Number of seconds an incident was open for | daily median per month | daily median | `day` (default) or `month` | | Change failure rate | percentage of deployments that cause an incident in production | daily median per month | percentage of failed deployments | `day` (default) or `month` | +## Configure DORA metrics calculation **(ULTIMATE ALL BETA)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96561) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `dora_configuration`. 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 per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `dora_configuration`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +You can configure the behavior of DORA metrics calculations. +To do this, in the Rails console run the following command: + +```ruby +Dora::Configuration.create!(project: my_project, ltfc_target_branches: \['master', 'main'\]) +``` + +This feature is in [Beta](../../policy/experiment-beta-support.md). + ## Retrieve DORA metrics data To retrieve DORA data, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs. diff --git a/doc/user/analytics/img/dora_performers_score_panel_v16_3.png b/doc/user/analytics/img/dora_performers_score_panel_v16_3.png Binary files differdeleted file mode 100644 index 9f59667f9e9..00000000000 --- a/doc/user/analytics/img/dora_performers_score_panel_v16_3.png +++ /dev/null diff --git a/doc/user/analytics/img/issues_closed_analytics_v16_4.png b/doc/user/analytics/img/issues_closed_analytics_v16_4.png Binary files differnew file mode 100644 index 00000000000..5e1fe4eaa8c --- /dev/null +++ b/doc/user/analytics/img/issues_closed_analytics_v16_4.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index abeda983dad..f096d1e2882 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -6,84 +6,63 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Analyze GitLab usage **(FREE ALL)** -## Instance-level analytics +GitLab provides different types of analytics insights at the instance, group, and project level. +These insights appear on the left sidebar, under [**Analyze**](../project/settings/index.md#disable-project-analytics). -Instance-level analytics make it possible to aggregate analytics across -GitLab, so that users can view information across multiple projects and groups -in one place. +## Instance-level analytics -For more information, see [instance-level analytics](../admin_area/analytics/index.md). +Use [instance-level analytics](../../administration/analytics/index.md) to aggregate analytics across GitLab, +so that you can view information across multiple projects and groups in one place. ## Group-level analytics > Moved to GitLab Premium in 13.9. -GitLab provides several analytics features at the group level. Some of these features require you to use a higher tier than GitLab Free. +Use group-level analytics to get insights into your groups': -- [Application Security](../application_security/security_dashboard/index.md) -- [Contribution](../group/contribution_analytics/index.md) -- [DevOps Adoption](../group/devops_adoption/index.md) +- [Security Dashboards](../application_security/security_dashboard/index.md) +- [Contribution analytics](../group/contribution_analytics/index.md) +- [DevOps adoption](../group/devops_adoption/index.md) - [Insights](../group/insights/index.md) -- [Issue](../group/issues_analytics/index.md) -- [Productivity](productivity_analytics.md) -- [Repositories](../group/repositories_analytics/index.md) -- [Value Stream Management Analytics](../group/value_stream_analytics/index.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) +- [Issue analytics](../group/issues_analytics/index.md) +- [Productivity analytics](productivity_analytics.md) +- [Repositories analytics](../group/repositories_analytics/index.md) +- [Value Stream Management Analytics](../group/value_stream_analytics/index.md) and [Value Stream Management Dashboard](value_streams_dashboard.md) ## Project-level analytics -You can use GitLab to review analytics at the project level. Some of these features require you to use a higher tier than GitLab Free. +Use project-level analytics to get insights into your projects': - [Analytics dashboards](analytics_dashboards.md), enabled with the `combined_analytics_dashboards_editor` [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) -- [Application Security](../application_security/security_dashboard/index.md) -- [CI/CD & DORA](ci_cd_analytics.md) -- [Code Review](code_review_analytics.md) +- [Security Dashboards](../application_security/security_dashboard/index.md) +- [CI/CD analytics and DORA metrics](ci_cd_analytics.md) +- [Code review analytics](code_review_analytics.md) - [Contributor statistics](../../user/analytics/contributor_statistics.md) - [Insights](../project/insights/index.md) -- [Issue](../../user/analytics/issue_analytics.md) -- [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` +- [Issue analytics](../../user/analytics/issue_analytics.md) +- [Merge request analytics](merge_request_analytics.md), enabled with the `project_merge_request_analytics` [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) -- [Repository](repository_analytics.md) -- [Value Stream Management Analytics](../group/value_stream_analytics/index.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) - -### Remove project analytics from the left sidebar - -By default, analytics for a project are displayed under the **Analyze** item in the left sidebar. To remove this item: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Turn off the **Analytics** toggle. -1. Select **Save changes**. +- [Repository analytics](repository_analytics.md) +- [Value Stream Management Analytics](../group/value_stream_analytics/index.md) and [Value Stream Management Dashboard](value_streams_dashboard.md) ## User-configurable analytics -The following analytics features are available for users to create personalized views: - -- [Application Security](../application_security/security_dashboard/index.md#security-center) - -Be sure to review the documentation page for this feature for GitLab tier requirements. +View vulnerabilities of your selected projects in the [Security Center](../application_security/security_dashboard/index.md#security-center). ## Value streams management -You can use the following analytics features to analyze and visualize the performance of your projects and groups: +Analyze and visualize the performance of your projects and groups with: - [Value stream analytics for projects and groups](../group/value_stream_analytics/index.md) - [Value streams dashboard](value_streams_dashboard.md) ## Glossary -We use the following terms to describe GitLab analytics: - -- **Mean Time to Change (MTTC):** The average duration between idea and delivery. GitLab measures -MTTC from issue creation to the issue's latest related merge request's deployment to production. -- **Mean Time to Detect (MTTD):** The average duration that a bug goes undetected in production. -GitLab measures MTTD from deployment of bug to issue creation. -- **Mean Time To Merge (MTTM):** The average lifespan of a merge request. GitLab measures MTTM from -merge request creation to merge request merge (and closed/un-merged merge requests are excluded). -For more information, see [Merge Request Analytics](merge_request_analytics.md). -- **Mean Time to Recover/Repair/Resolution/Resolve/Restore (MTTR):** The average duration that a bug -is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. -- **Velocity:** The total issue burden completed in some period of time. The burden is usually measured -in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab -measures velocity as the total points or weight of issues closed in a given period of time. +| Metric | Definition | Measurement in GitLab | +| ------ | ---------- | --------------------- | +| Mean Time to Change (MTTC) | The average duration between idea and delivery. | From issue creation to the issue's latest related merge request's deployment to production. | +| Mean Time to Detect (MTTD) | The average duration that a bug goes undetected in production. | From deployment of bug to issue creation. | +| Mean Time To Merge (MTTM) | The average lifespan of a merge request. | From merge request creation to merge request merge (excluding closed and unmerged merge requests). For more information, see [Merge Request Analytics](merge_request_analytics.md). | +| Mean Time to Recover/Repair/Resolution/Resolve/Restore (MTTR) | The average duration that a bug is not fixed in production. | From deployment of bug to deployment of fix. | +| Velocity | The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. | Total points or weight of issues closed in a given period of time. Expressed as, for example, "30 points per sprint". | diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 7caee947318..8f29c008d75 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -15,9 +15,11 @@ prior. To access the chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 @@ -36,6 +38,20 @@ 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. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 998f56ac40a..0f8eb9ac211 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -29,7 +29,7 @@ Prerequisite: To view merge request analytics: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Merge request analytics**. ## View the number of merge requests in a date range @@ -39,7 +39,7 @@ To view merge request analytics: To view the number of merge requests merged during a specific date range: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Merge request analytics**. 1. Optional. Filter results: 1. Select the filter bar. @@ -73,6 +73,6 @@ created and when it's merged. Closed and not yet merged merge requests are not i To view **Mean time to merge**: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index ea896f07204..a17eb08c53c 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -26,7 +26,7 @@ Prerequisite: - You must have at least the Reporter role for the group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. 1. Optional. Filter results: 1. Select a project from the dropdown list. @@ -44,7 +44,7 @@ Use the following charts in productivity analytics to view the velocity of your merge requests to merge after they were created. - **Trendline**: number of merge requests that were merged in a specific time period. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. To filter time metrics: @@ -56,7 +56,7 @@ To filter time metrics: To view commit statistics for your group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. 1. Under the **Trendline** scatterplot, view the commit statistics: - The left histogram shows the number of hours between commits, comments, and merges. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 46fa36658c4..26bce8a20c2 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -20,7 +20,7 @@ Repository analytics is part of [GitLab Community Edition](https://gitlab.com/gi Repository analytics requires: - An initialized Git repository. -- At least one commit in the default branch (`master` by default). +- At least one commit in the default branch (`main` by default). NOTE: Without a Git commit in the default branch, the menu item isn't visible. @@ -30,7 +30,7 @@ Commits in a project's [wiki](../project/wiki/index.md#track-wiki-events) are no To review repository analytics for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Repository analytics**. ## How repository analytics chart data is updated diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index 2c6626ad315..ed637dd886f 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Released in GitLab 15.11 as an Open [Beta](../../policy/experiment-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392734) in GitLab 16.0. Feature flag `group_analytics_dashboards_page` removed. -You can leave feedback on dashboard bugs or functionality in [issue 419488](https://gitlab.com/gitlab-org/gitlab/-/issues/419488). +To help us improve the Value Streams Dashboard, please share feedback about your experience in this [survey](https://gitlab.fra1.qualtrics.com/jfe/form/SV_50guMGNU2HhLeT4). For more information, see also the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). The Value Streams Dashboard is a customizable dashboard you can use to identify trends, patterns, and opportunities for digital transformation improvements. @@ -71,22 +71,46 @@ 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). +## 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. +> - [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. + +Prerequisite: + +- You must have administrator access to the instance. + +To enable or disable the overview count aggregation for the Value Streams Dashboard: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand **Analytics**. +1. In **Value Streams Dashboard**, select or clear the **Enable overview background aggregation for Value Streams Dashboard** checkbox. + +To retrieve aggregated usage counts in the group, use the [GraphQL API](../../api/graphql/reference/index.md#groupvaluestreamdashboardusageoverview). + ## View the value streams dashboard Prerequisite: - You must have at least the Reporter role for the group. +- Overview background aggregation for Value Streams Dashboards must be enabled. To view the value streams dashboard: - From Analytics Dashboards: - 1. On the group left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. On the group left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Analytics Dashboards**. - From Value Stream Analytics: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value stream analytics**. 1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. 1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL (for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards/value_streams_dashboard`). @@ -118,7 +142,7 @@ Prerequisite: - You must have at least the Maintainer role for the group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Analytics**. 1. Select the project where you would like to store your YAML configuration file. @@ -126,7 +150,7 @@ Prerequisite: After you have set up the project, set up the configuration file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. In the default branch, create the configuration file: `.gitlab/analytics/dashboards/value_streams/value_streams.yaml`. 1. In the `value_streams.yaml` configuration file, fill in the configuration options: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index c365c7f6bab..1bac636ac3f 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -101,7 +101,7 @@ a YAML snippet that you can paste in your GitLab CI/CD configuration. To generate an API Fuzzing configuration snippet: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **API Fuzzing** row, select **Enable API Fuzzing**. 1. Complete the fields. For details see [Available CI/CD variables](#available-cicd-variables). diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 10e16a173d8..1e9163a4c26 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Secure group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments @@ -7,11 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Security configuration **(FREE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in GitLab 12.6. -> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. -> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. -> - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. -> - [Redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.2. +> Security configuration page was [redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in GitLab 14.2. The **Security configuration** page lists the following for the security testing and compliance tools: @@ -40,7 +35,7 @@ all security features are configured by default. To view a project's security configuration: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. Select **Configuration history** to see the `.gitlab-ci.yml` file's history. diff --git a/doc/user/application_security/continuous_vulnerability_scanning/index.md b/doc/user/application_security/continuous_vulnerability_scanning/index.md new file mode 100644 index 00000000000..4094a0add28 --- /dev/null +++ b/doc/user/application_security/continuous_vulnerability_scanning/index.md @@ -0,0 +1,59 @@ +--- +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Continuous Vulnerability Scanning **(ULTIMATE EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) in GitLab 16.4 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) with two [features flags](../../../administration/feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. Enabled by default. + +NOTE: +This feature is an [Experiment](../../../policy/experiment-beta-support.md#experiment) and subject to change without notice. +If you have any feedback, you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/425072). + +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 GitLab.com, this feature is available. + +Continuous Vulnerability Scanning detects new vulnerabilities outside a pipeline. +Your projects are automatically scanned whenever advisories are added to the [`GitLab Advisory Database`](https://advisories.gitlab.com/). +Projects that depend on the affected components have new vulnerabilities automatically created. + +Continuous Vulnerability Scanning detects vulnerabilities in the latest CycloneDX SBOM reports for the default branch. +[Dependency Scanning](../dependency_scanning/index.md) is used to generate these reports. + +## Configuration + +To enable Continuous Vulnerability Scanning: + +- Enable the Continuous Vulnerability Scanning setting in the project's [security configuration](../configuration/index.md). +- Enable [Dependency Scanning](../dependency_scanning/index.md#configuration) and ensure that its prerequisites are met. + +On GitLab self-managed only, you can [choose package registry metadata to sync](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. + +### Requirements for offline environments + +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, +some adjustments are required to successfully scan CycloneDX reports for vulnerabilities. +For more information, see the offline [quick start guide](../../../topics/offline/quick_start_guide.md#enabling-the-package-metadata-database). + +## Supported languages and package managers + +The supported files and versions are the ones supported by +[Dependency Scanning](../dependency_scanning/index.md#supported-languages-and-package-managers). + +Go pseudo versions are not supported. A project dependency that references a Go pseudo version is never considered as affected. This might result in false negatives. + +## Checking new vulnerabilities + +New vulnerabilities detected by Continuous Vulnerability Scanning are visible on the [Vulnerability Report](../vulnerability_report/index.md). +However, they are not listed on the [Dependency List](../dependency_list/index.md) or in the pipeline where the affected SBOM component was detected. + +After an advisory is added to the [`GitLab Advisory Database`](https://advisories.gitlab.com/), +it might take a few hours before the corresponding vulnerabilities are added to your projects. + +## Contributing to the vulnerability database + +To find a vulnerability, you can search the [`GitLab Advisory Database`](https://advisories.gitlab.com/). +You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 59bd2b1ffb3..599203dedcc 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -58,7 +58,7 @@ You can use the following fuzzing engines to test the specified languages. To confirm the status of coverage-guided fuzz testing: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section the status is: - **Not configured** @@ -172,7 +172,7 @@ artifacts files you can download from the CI/CD pipeline. Also, a project member To view details of the corpus registry: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. @@ -200,7 +200,7 @@ provided by the `COVFUZZ_CORPUS_NAME` variable. The corpus is updated on every p To upload an existing corpus file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. 1. Select **New corpus**. diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index b13b41e4a37..aed4066bc52 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -412,9 +412,12 @@ Authentication failed because a home page should be displayed after login. Inste ### Configure the authentication report +WARNING: +The authentication report can contain sensitive information such as the credentials used to perform the login. + An authentication report can be saved as a CI/CD job artifact to assist with understanding the cause of an authentication failure. -The report contains steps during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots. +The report contains steps performed during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots.  diff --git a/doc/user/application_security/dast/checks/113.1.md b/doc/user/application_security/dast/checks/113.1.md new file mode 100644 index 00000000000..44c3be330f2 --- /dev/null +++ b/doc/user/application_security/dast/checks/113.1.md @@ -0,0 +1,27 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Improper Neutralization of CRLF Sequences in HTTP Headers + +## Description + +By inserting Carriage Return / Line Feed (CRLF) characters, malicious users could potentially inject arbitrary data into HTTP responses. By modifying HTTP responses, attackers could conduct cross-site scripting or cache poisoning attacks against other users of the system. + +## Remediation + +User input should never be used in constructing HTTP header responses without some form +of validation against newlines. This includes URLs supplied by the user for HTTP redirects. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 113.1 | false | 113 | Active | high | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/HTTP_Response_Splitting) +- [CWE](https://cwe.mitre.org/data/definitions/113.html) diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index edaace407ae..d407234d2c2 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.md @@ -22,8 +22,8 @@ Only three directives are applicable for the `Strict-Transport-Security` header. 1. `includeSubDomains`: This optional, valueless directive signals that the policy applies to this host as well as any subdomains found under this host's domain. 1. `preload`: While not part of the specification, setting this optional value allows major browser organizations to add this site into the browser's preloaded set of HTTPS sites. This requires further action on behalf of the website operator to submit their domain to the browser's HSTS preload list. See [hstspreload.org](https://hstspreload.org/) for more information. -Invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the -values are different) is considered invalid. +Note that invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the values are +different) is considered invalid. Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org [Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). diff --git a/doc/user/application_security/dast/checks/16.9.md b/doc/user/application_security/dast/checks/16.9.md index c63a620794e..b0ba502b578 100644 --- a/doc/user/application_security/dast/checks/16.9.md +++ b/doc/user/application_security/dast/checks/16.9.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description A `Content-Security-Policy-Report-Only` (CSPRO) was identified on the target site. CSP-Report-Only headers -aid in determining how to implement a `Content-Security-Policy` that does not disrupt use of the target +aid in determining how to implement a `Content-Security-Policy` that does not disrupt normal use of the target site. ## Remediation diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 1b3ce45dc43..035f4a4b486 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -4,7 +4,7 @@ group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# DAST browser-based crawler vulnerability checks **(ULTIMATE ALL)** +# DAST browser-based crawler vulnerability checks **(ULTIMATE)** The [DAST browser-based crawler](../browser_based.md) provides a number of vulnerability checks that are used to scan for vulnerabilities in the site under test. @@ -167,4 +167,5 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | ID | Check | Severity | Type | |:---|:------|:---------|:-----| +| [113.1](113.1.md) | Improper Neutralization of CRLF Sequences in HTTP Headers | High | Active | | [22.1](22.1.md) | Improper limitation of a pathname to a restricted directory (Path traversal) | High | Active | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 24aadd14dd1..4ec693593fb 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -81,8 +81,8 @@ analyzer-specific configuration instructions. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. -Detected vulnerabilities are shown in [Merge requests](../index.md#view-security-scan-information-in-merge-requests), the [Pipeline security tab](../index.md#view-security-scan-information-in-the-pipeline-security-tab), -and the [Vulnerability report](../index.md#view-security-scan-information-in-the-vulnerability-report). +Detected vulnerabilities appear in [merge requests](../index.md#merge-request), the [pipeline security tab](../index.md#pipeline-security-tab), +and the [vulnerability report](../index.md#vulnerability-report). 1. To see all vulnerabilities detected, either: - From your project, select **Security & Compliance**, then **Vulnerability report**. diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 7538bd38d9f..86af7d4c5da 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -89,7 +89,7 @@ In this method you manually edit the existing `.gitlab-ci.yml` file. Use this me To include the DAST template: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -156,7 +156,7 @@ snippet is created that you paste into the `.gitlab-ci.yml` file. To configure DAST using the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 **Enable DAST** or **Configure DAST**. @@ -467,6 +467,9 @@ The DAST job does not require the project's repository to be present when runnin > - Runner tags selection [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345430) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `on_demand_scans_runner_tags. Disabled by default. > - 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 @@ -483,7 +486,7 @@ An on-demand scan can be run in active or passive mode: To view on-demand scans: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +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 @@ -499,7 +502,7 @@ Prerequisites: To run an existing on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -522,7 +525,7 @@ Create an on-demand scan to: To create an on-demand DAST scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +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. @@ -550,7 +553,7 @@ The on-demand DAST scan runs as specified and the project's dashboard shows the To view details of an on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -559,7 +562,7 @@ To view details of an on-demand scan: To edit an on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -570,7 +573,7 @@ To edit an on-demand scan: To delete an on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -632,7 +635,7 @@ equivalent in functionality, so use whichever is most suitable: To create a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -654,7 +657,7 @@ When a validated site profile's file, header, or meta tag is edited, the site's To edit a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -669,7 +672,7 @@ See [Scan execution policies](../policies/scan-execution-policies.md) for more i To delete a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -687,7 +690,7 @@ Prerequisites: To validate a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -724,7 +727,7 @@ page. To retry a site profile's failed validation: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -738,7 +741,7 @@ have their validation status revoked. To revoke a site profile's validation status: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -809,7 +812,7 @@ A scanner profile contains: To create a scanner profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -824,7 +827,7 @@ For more information, see [Scan execution policies](../policies/scan-execution-p To edit a scanner profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -840,7 +843,7 @@ page. For more information, see [Scan execution policies](../policies/scan-execu To delete a scanner profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png b/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png Binary files differdeleted file mode 100644 index 5b2bd985ce4..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png b/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png Binary files differindex f3a8f3d8d5d..7e4e80f9c00 100644 --- a/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png +++ b/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index a55f26f529d..d8726cbd456 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -9,17 +9,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - System dependencies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6698) in GitLab 14.6. > - Group-level dependency list [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8090) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies`. Disabled by default. +> - Group-level dependency list [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/411257) in GitLab 16.4. -Use the dependency list to review your project or group's dependencies and key -details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. +Use the dependency list to review your project or group's dependencies and key details about those +dependencies, including their known vulnerabilities. This list is a collection of dependencies in your +project, including existing and new findings. This information is sometimes referred to as a +Software Bill of Materials, SBOM, or BOM. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Project Dependency](https://www.youtube.com/watch?v=ckqkn9Tnbw4). -To see the dependency list, go to your project or group and select **Secure > Dependency list**. - -This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. - ## Prerequisites To view your project's dependencies, ensure you meet the following requirements: @@ -34,21 +33,33 @@ To view your project's dependencies, ensure you meet the following requirements: You should not change the default behavior of allowing the [application security jobs](../../application_security/index.md#application-coverage) to fail. -## View a project's dependencies +## View project dependencies + +To view the dependencies of a project or all projects in a group: - +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Secure > Dependency list**. -GitLab displays dependencies with the following information: +Details of each dependency are listed, sorted by decreasing severity of vulnerabilities (if any). You can sort the list instead by component name or packager. | Field | Description | -|-----------|-------------| +|:----------|:-----------| | Component | The dependency's name and version. | | Packager | The packager used to install the dependency. | | Location | For system dependencies, this lists the image that was scanned. For application dependencies, this shows a link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | -| License | Links to dependency's software licenses. | +| License<sup>1</sup> | Links to dependency's software licenses. A warning badge that includes the number of vulnerabilities detected in the dependency. | +| Projects<sup>2</sup> | Links to the project with the dependency. If multiple projects have the same dependency, the total number of these projects is shown. To go to a project with this dependency, select the **Projects** number, then search for and select its name. The project search feature is supported only on groups that have up to 600 occurrences in their group hierarchy. | + +<html> +<small>Footnotes: + <ol> + <li>Project-level only.</li> + <li>Group-level only.</li> + </ol> +</small> +</html> -Displayed dependencies are initially sorted by the severity of their known vulnerabilities, if any. They -can also be sorted by name or by the packager that installed them. + ### Vulnerabilities @@ -60,7 +71,7 @@ select the vulnerability's description. The [vulnerability's details](../vulnera ### Dependency paths The dependency list shows the path between a dependency and a top-level dependency it's connected -to, if any. There are many possible paths connecting a transient dependency to top-level +to, if any. Multiple paths may connect a transient dependency to top-level dependencies, but the user interface shows only one of the shortest paths. NOTE: @@ -73,42 +84,20 @@ Dependency paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) - [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) - [sbt](https://www.scala-sbt.org) +- [Conan](https://conan.io) ### Licenses -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab 12.3. - If the [Dependency Scanning](../../application_security/dependency_scanning/index.md) CI job is configured, -[discovered licenses](../../compliance/license_scanning_of_cyclonedx_files/index.md#enable-license-scanning) are displayed on this page. - -## View a group's dependencies - -FLAG: -On self-managed GitLab, and GitLab.com the feature is disabled by default. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies`. - - - -GitLab displays dependencies with the following information: - -| Field | Description | -|-----------|-------------| -| Component | The dependency's name and version. | -| Packager | The packager used to install the dependency. | -| Location | For operating system dependencies, this lists the image that was scanned. For application dependencies, this shows a link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. If there are multiple locations, the total number of locations is displayed. | -| Projects | Links to the project related to the dependency. If there are multiple projects, the total number of projects is displayed. | - -Displayed dependencies are initially sorted by packager. They -can also be sorted by name. - -## Downloading the dependency list - -You can download the full list of dependencies and their details in -`JSON` format. +[discovered licenses](../../compliance/license_scanning_of_cyclonedx_files/index.md) are displayed on this page. -### In the UI +## Download the dependency list -You can download your group's or project's list of dependencies and their details in JSON format by selecting the **Export** button. The dependency list only shows the results of the last successful pipeline to run on the default branch. +You can download the full list of dependencies and their details in JSON format. The dependency +list shows only the results of the last successful pipeline that ran on the default branch. -### Using the API +To download the dependency list: -You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the [Gemnasium family of analyzers](../dependency_scanning/index.md#dependency-analyzers) and not any other of the GitLab dependency analyzers. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Secure > Dependency list**. +1. Select **Export**. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 5a2394113cb..f8bd5b99cb6 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -18,6 +18,8 @@ Dependency Scanning can run in the development phase of your application's life pipeline runs, vulnerabilities are identified and compared between the source and target branches. Vulnerabilities and their severity are listed in the merge request, enabling you to proactively address the risk to your application, before the code change is committed. +Vulnerabilities can also be identified outside a pipeline by +[Continuous Vulnerability Scanning](../continuous_vulnerability_scanning/index.md). GitLab offers both Dependency Scanning and [Container Scanning](../container_scanning/index.md) to ensure coverage for all of these dependency types. To cover as much of your risk area as possible, @@ -327,7 +329,7 @@ GitLab analyzers obtain dependency information using one of the following two me The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: -| Package Manager | Supported File Format Versions | Tested Versions | +| Package Manager | Supported File Format Versions | Tested Package Manager Versions | | ------ | ------ | ------ | | Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | | Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | @@ -335,7 +337,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | | NuGet | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | | npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | -| pnpm | v5.3, v5.4, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | +| pnpm | v5, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | | yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup> | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2), [2.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock), [3.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock) | | Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | @@ -559,7 +561,7 @@ always take the latest dependency scanning artifact available. To enable Dependency Scanning in a project, you can create a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dependency Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable Dependency Scanning. @@ -1019,62 +1021,7 @@ variables: See explanations of the variables above in the [configuration section](#configuration). -### Specific settings for languages and package managers - -See the following sections for configuring specific languages and package managers. - -#### Python (pip) - -If you need to install Python packages before the analyzer runs, you should use `pip install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. - -#### Python (setuptools) - -If you need to install Python packages before the analyzer runs, you should use `python setup.py install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. - -When using self-signed certificates for your private PyPi repository, no extra job configuration (aside -from the template `.gitlab-ci.yml` above) is needed. However, you must update your `setup.py` to -ensure that it can reach your private repository. Here is an example configuration: - -1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each - dependency in the `install_requires` list: - - ```python - install_requires=['pyparsing>=2.0.3'], - dependency_links=['https://pypi.example.com/simple/pyparsing'], - ``` - -1. Fetch the certificate from your repository URL and add it to the project: - - ```shell - printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt - ``` - -1. Point `setup.py` at the newly downloaded certificate: - - ```python - import setuptools.ssl_support - setuptools.ssl_support.cert_paths = ['internal.crt'] - ``` - -#### Python (Pipenv) - -If running in a limited network connectivity environment, you must configure the `PIPENV_PYPI_MIRROR` -variable to use a private PyPi mirror. This mirror must contain both default and development dependencies. - -```yaml -variables: - PIPENV_PYPI_MIRROR: https://pypi.example.com/simple -``` - -<!-- markdownlint-disable MD044 --> -Alternatively, if it's not possible to use a private registry, you can load the required packages -into the Pipenv virtual environment cache. For this option, the project must check in the -`Pipfile.lock` into the repository, and load both default and development packages into the cache. -See the example [python-pipenv](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/41cc017bd1ed302f6edebcfa3bc2922f428e07b6/.gitlab-ci.yml#L20-42) -project for an example of how this can be done. -<!-- markdownlint-enable MD044 --> - -## Hosting a copy of the `gemnasium_db` advisory database +### Hosting a copy of the `gemnasium_db` advisory database The [`gemnasium_db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) Git repository is used by `gemnasium`, `gemnasium-maven`, and `gemnasium-python` as the source of vulnerability data. @@ -1085,7 +1032,7 @@ one of the following: - [Host a copy of the advisory database](#host-a-copy-of-the-advisory-database) - [Use a local clone](#use-a-local-clone) -### Host a copy of the advisory database +#### Host a copy of the advisory database If [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is not reachable from within the environment, the user can host their own Git copy. Then the analyzer can be @@ -1098,7 +1045,7 @@ variables: ... ``` -### Use a local clone +#### Use a local clone If a hosted copy is not possible, then the user can clone [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) or create an archive before the scan and point the analyzer to the directory (using: @@ -1129,6 +1076,61 @@ variables: GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost" ``` +## Specific settings for languages and package managers + +See the following sections for configuring specific languages and package managers. + +### Python (pip) + +If you need to install Python packages before the analyzer runs, you should use `pip install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. + +### Python (setuptools) + +If you need to install Python packages before the analyzer runs, you should use `python setup.py install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. + +When using self-signed certificates for your private PyPi repository, no extra job configuration (aside +from the template `.gitlab-ci.yml` above) is needed. However, you must update your `setup.py` to +ensure that it can reach your private repository. Here is an example configuration: + +1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each + dependency in the `install_requires` list: + + ```python + install_requires=['pyparsing>=2.0.3'], + dependency_links=['https://pypi.example.com/simple/pyparsing'], + ``` + +1. Fetch the certificate from your repository URL and add it to the project: + + ```shell + printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt + ``` + +1. Point `setup.py` at the newly downloaded certificate: + + ```python + import setuptools.ssl_support + setuptools.ssl_support.cert_paths = ['internal.crt'] + ``` + +### Python (Pipenv) + +If running in a limited network connectivity environment, you must configure the `PIPENV_PYPI_MIRROR` +variable to use a private PyPi mirror. This mirror must contain both default and development dependencies. + +```yaml +variables: + PIPENV_PYPI_MIRROR: https://pypi.example.com/simple +``` + +<!-- markdownlint-disable MD044 --> +Alternatively, if it's not possible to use a private registry, you can load the required packages +into the Pipenv virtual environment cache. For this option, the project must check in the +`Pipfile.lock` into the repository, and load both default and development packages into the cache. +See the example [python-pipenv](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/41cc017bd1ed302f6edebcfa3bc2922f428e07b6/.gitlab-ci.yml#L20-42) +project for an example of how this can be done. +<!-- markdownlint-enable MD044 --> + ## Warnings We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. diff --git a/doc/user/application_security/gitlab_advisory_database/index.md b/doc/user/application_security/gitlab_advisory_database/index.md new file mode 100644 index 00000000000..e59eaccf8f8 --- /dev/null +++ b/doc/user/application_security/gitlab_advisory_database/index.md @@ -0,0 +1,95 @@ +--- +stage: Secure +group: Vulnerability Research +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab Advisory Database + +The [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db) serves as a repository for security advisories related to software dependencies. + +The database is an essential component of both [Dependency Scanning](../dependency_scanning/index.md) and [Container Scanning](../container_scanning/index.md). + +A free and open-source version of the GitLab Advisory Database is also available as [GitLab Advisory Database (Open Source Edition)](https://gitlab.com/gitlab-org/advisories-community). However, there is a 30-day delay in updates. + +## Standardization + +In our advisories, we adopt standardized practices to effectively communicate vulnerabilities and their impact. + +- [CVE](../terminology/index.md#cve) +- [CVSS](../terminology/index.md#cvss) +- [CWE](../terminology/index.md#cwe) + +## Explore the database + +To view the database content, go to the [GitLab Advisory Database](https://advisories.gitlab.com) home page. On the home page you can: + +- Search the database, by identifier, package name, and description. +- View advisories that were added recently. +- View statistical information, including coverage and update frequency. + +### Search + +Each advisory has a page with the following details: + +- **Identifiers**: Public identifiers. For example, CVE ID, GHSA ID, or the GitLab internal ID (`GMS-<year>-<nr>`). +- **Package Slug**: Package type and package name separated by a slash. +- **Vulnerability**: A short description of the security flaw. +- **Description**: A detailed description of the security flaw and potential risks. +- **Affected Versions**: The affected versions. +- **Solution**: How to remediate the vulnerability. +- **Last Modified**: The date when the advisory was last modified. + +### Statistics + +The home page also offers a [statistic section](https://advisories.gitlab.com/stats/index.html) that provides valuable insights into advisory distribution, the origins of vulnerabilities, dependency scanning coverage, and timelines for vulnerability resolution. + +## Open Source Edition + +GitLab provides a free and open-source version of the database, the [GitLab Advisory Database (Open Source Edition)](https://gitlab.com/gitlab-org/advisories-community). + +The open-source version is a time-delayed clone of the GitLab Advisory Database, MIT-licensed and contains all advisories from the GitLab Advisory Database that are older than 30 days or with the `community-sync` flag. + +## Integrations + +- [Dependency Scanning](../dependency_scanning/index.md) +- [Container Scanning](../container_scanning/index.md) +- Third-party tools + +NOTE: +GitLab Advisory Database Terms prohibit the use of data contained in the GitLab Advisory Database by third-party tools. Third-party integrators can use the MIT-licensed, time-delayed [repository clone](https://gitlab.com/gitlab-org/advisories-community) instead. + +### How the database can be used + +As an example, we highlight the use of the database as a source for an Advisory Ingestion process as part of Continuous Vulnerability Scans. + +```mermaid +flowchart TB + subgraph Dependency Scanning + A[GitLab Advisory Database] + end + subgraph Container Scanning + C[GitLab Advisory Database \n Open Source Edition \n integrated into Trivy] + end + A --> B{Ingest} + C --> B + B --> |store| D{{"Cloud Storage \n (NDJSON format)"}} + F[\GitLab Instance/] --> |pulls data| D + F --> |stores| G[(Relational Database)] +``` + +## Maintenance + +The [Vulnerability Research](https://about.gitlab.com/handbook/engineering/development/sec/secure/vulnerability-research/) team is responsible for the maintenance and regular updates of the GitLab Advisory Database and the GitLab Advisory Database (Open Source Edition). + +Community contributions are accessible in [advisories-community](https://gitlab.com/gitlab-org/advisories-community) via the `community-sync` flag. + +## Contributing to the vulnerability database + +If you know about a vulnerability that is not listed, you can contribute to the GitLab Advisory Database by either opening an issue or submit the vulnerability. + +For more information, see [Contribution Guidelines](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/CONTRIBUTING.md). + +## License + +The GitLab Advisory Database is freely accessible in accordance with the [GitLab Advisory Database Terms](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/LICENSE.md#gitlab-advisory-database-term). diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 334e8c28378..8cdeeb92e09 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -121,7 +121,7 @@ The **Configure with a merge request** button been temporarily disabled due to a To enable IaC Scanning in a project, you can create a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable IaC Scanning. @@ -130,7 +130,7 @@ Pipelines now include an IaC Scanning job. ## Customize rulesets **(ULTIMATE ALL)** -> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. +> Support for overriding rules [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) in GitLab 14.8. You can customize the default IaC Scanning rules provided with GitLab. diff --git a/doc/user/application_security/img/security_widget_v13_7.png b/doc/user/application_security/img/security_widget_v13_7.png Binary files differdeleted file mode 100644 index fb1eaf9a2be..00000000000 --- a/doc/user/application_security/img/security_widget_v13_7.png +++ /dev/null diff --git a/doc/user/application_security/img/security_widget_v16_4.png b/doc/user/application_security/img/security_widget_v16_4.png Binary files differnew file mode 100644 index 00000000000..dfed372ba31 --- /dev/null +++ b/doc/user/application_security/img/security_widget_v16_4.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 615ff7e3fda..62155e07fbc 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -103,7 +103,7 @@ The following vulnerability scanners and their databases are regularly updated: |:----------------------------------------------------------------|:---------------------------------| | [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. GitLab monitors this job through an internal alert that tells the engineering team when the database becomes more than 48 hours old. For more information, see the [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database). | | [Dependency Scanning](dependency_scanning/index.md) | Relies on the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). It is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | -| [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | +| [Dynamic Application Security Testing (DAST)](dast/index.md) | [DAST proxy-based](dast/proxy-based.md) and [browser-based](dast/browser_based.md) engines are updated on a periodic basis. [DAST proxy-based](dast/proxy-based.md) analyzer downloads the scanning rules at scan runtime. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L27). [DAST browser-based](dast/browser_based.md) rules run [different vulnerability checks](dast/checks/index.md). | | [Secret Detection](secret_detection/index.md#detected-secrets) | GitLab maintains the [detection rules](secret_detection/index.md#detected-secrets) and [accepts community contributions](secret_detection/index.md#adding-new-patterns). The scanning engine is updated at least once per month if a relevant update is available. | | [Static Application Security Testing (SAST)](sast/index.md) | The source of scan rules depends on which [analyzer](sast/analyzers.md) is used for each [supported programming language](sast/index.md#supported-languages-and-frameworks). GitLab maintains a ruleset for the Semgrep-based analyzer and updates it regularly based on internal research and user feedback. For other analyzers, the ruleset is sourced from the upstream open-source scanner. Each analyzer is updated at least once per month if a relevant update is available. | @@ -223,20 +223,30 @@ We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/ind The artifact generated by the secure analyzer contains all findings it discovers on the target branch, regardless of whether they were previously found, dismissed, or completely new (it puts in everything that it finds). -## View security scan information in merge requests **(FREE ALL)** +## View security scan information + +Security scan information appears in multiple locations and formats: + +- Merge request +- Pipeline security tab +- Security dashboard +- Vulnerability report +- GitLab Workflow extension for VS Code + +### 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. -### All tiers +#### All tiers Merge requests which have run security scans let you know that the generated reports are available to download. To download a report, select **Download results**, and select the desired report. - + Security scans produce at least one of these [CI `artifacts:reports` types](../../ci/yaml/artifacts_reports.md): @@ -248,7 +258,9 @@ Security scans produce at least one of these [CI `artifacts:reports` types](../. - `artifacts:reports:sast` - `artifacts:reports:secret_detection` -### Ultimate +In the Free tier, the reports above aren't parsed by GitLab. As a result, the widget does not change based on the results of the security scans. + +#### Ultimate A merge request contains a security widget which displays a summary of the _new_ results. New results are determined by comparing the findings of the merge request against the findings of the most recent completed pipeline (`success`, `failed`, `canceled` or `skipped`) for the commit when the feature branch was created from the target branch. @@ -263,26 +275,32 @@ findings, select **View full report** to go directly to the **Security** tab in  -## View security scan information in the pipeline Security tab +### Pipeline security tab A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch and existing vulnerabilities already present when you created the branch. These results likely do not match the findings displayed in the Merge Request security widget, as those do not include the existing vulnerabilities. Refer to [View vulnerabilities in a pipeline](vulnerability_report/pipeline.md) for more information. -## View security scan information in the Security Dashboard +### Security dashboard -The Security Dashboard show vulnerabilities present in a project's default branch. Data is updated every 24 hours. Vulnerability count updates resulting from any feature branches introducing new vulnerabilities that are merged to default are included after the daily data refresh. +The security dashboard shows the vulnerabilities on a project's default branch. Data is updated every 24 hours. Vulnerability count updates resulting from any feature branches introducing new vulnerabilities that are merged to default are included after the daily data refresh. For more details, see [Security Dashboard](security_dashboard/index.md). -## View security scan information in the Vulnerability Report +### Vulnerability report -The vulnerability report shows the results of the last completed pipeline on the default branch. It is updated on every pipeline completion. All detected vulnerabilities are shown as well as any previous ones that are no longer detected in the latest scan. Vulnerabilities that are no longer detected may have been remediated or otherwise removed and can be marked as `Resolved` after proper verification. Vulnerabilities that are no longer detected are denoted with an icon for filtering and review. +The vulnerability report shows the results of the last completed pipeline on the default branch. It is updated on every pipeline completion. All detected vulnerabilities are shown and any previous ones that are no longer detected in the latest scan. Vulnerabilities that are no longer detected may have been remediated or otherwise removed and can be marked as `Resolved` after proper verification. Vulnerabilities that are no longer detected are denoted with an icon for filtering and review. By default, the vulnerability report does not show vulnerabilities of `dismissed` or `resolved` status so you can focus on open vulnerabilities. You can change the Status filter to see these. [Read more about the Vulnerability report](vulnerability_report/index.md). +### GitLab Workflow extension for VS Code + +You can now see security findings directly in Visual Studio Code (VS Code) using [GitLab Workflow VS Code extension](../../editor_extensions/visual_studio_code/index.md), just as you would in a merge request. + +For more details, see [extension page](https://marketplace.visualstudio.com/items?itemName=gitlab.gitlab-workflow#security-findings). + ## Security approvals in merge requests > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in GitLab 12.2. @@ -453,7 +471,7 @@ You can always find supported and deprecated schema versions in the [source code You can interact with the results of the security scanning tools in several locations: -- [Scan information in merge requests](#view-security-scan-information-in-merge-requests) +- [Scan information in merge requests](#merge-request) - [Project Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-project) - [Security pipeline tab](security_dashboard/index.md) - [Group Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-group) @@ -526,7 +544,7 @@ Additional details about the differences between the two solutions are outlined | **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, SAST IaC, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | | **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | | **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job. | -| **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | +| **Schedulable** | Has to be scheduled through a scheduled pipeline on each project. | Can be scheduled natively through the policy configuration itself. | | **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | | **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | @@ -721,8 +739,8 @@ Instructions are available in the [legacy template project](https://gitlab.com/g In these circumstances, that the job succeeds is the default behavior. The job's status indicates success or failure of the analyzer itself. Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), -[Merge Request widget](#view-security-scan-information-in-merge-requests) or -[Security Dashboard](security_dashboard/index.md). +[merge request widget](#merge-request), or +[security dashboard](security_dashboard/index.md). ### Error: job `is used for configuration only, and its script should not be executed` diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 25e2f523f08..84c28d4008c 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -58,7 +58,7 @@ to select, edit, and unlink a security policy project. As a project owner, take the following steps to create or edit an association between your current project and a project that you would like to designate as the security policy project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. 1. Select **Edit Policy Project**, and search for and select the project you would like to link from the dropdown list. @@ -82,7 +82,7 @@ policies for all available environments. You can check a policy's information (for example, description or enforcement status), and create and edit deployed policies: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**.  @@ -93,7 +93,7 @@ status), and create and edit deployed policies: You can use the policy editor to create, edit, and delete policies: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. - To create a new policy, select **New policy** which is located in the **Policies** page's header. You can then select which type of policy to create. @@ -142,12 +142,13 @@ The workaround is to amend your group or instance push rules to allow branches f ### Troubleshooting common issues configuring security policies - Confirm that scanners are properly configured and producing results for the latest branch. Security Policies are designed to require approval when there are no results (no security report), as this ensures that no vulnerabilities are introduced. We cannot know if there are any vulnerabilities unless the scans enforced by the policy complete successfully and are evaluated. +- For scan result policies, we require artifacts for each scanner defined in the policy for both the source and target branch. To ensure scan result policies capture the necessary results, confirm your scan execution is properly implemented and enforced. If using scan execution policies, enforcing on `all branches` often address this need. - When running scan execution policies based on a SAST action, ensure target repositories contain proper code files. SAST runs different analyzers [based on the types of files in the repo](../sast/index.md#supported-languages-and-frameworks), and if no supported files are found it will not run any jobs. See the [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) for more details. -- Check for any branch configuration conflicts. If your policy is configured to enforce rules on `main` but some projects within the scope are using `master` as their default branch, the policy is not applied for the latter. Support for specifying the `default` branch in your policies is proposed in [epic 9468](https://gitlab.com/groups/gitlab-org/-/epics/9468). +- Check for any branch configuration conflicts. If your policy is configured to enforce rules on `main` but some projects within the scope are using `master` as their default branch, the policy is not applied for the latter. You can define policies to enforce rules generically on `default` branches regardless of the name used in the project or on `all protected branches` to address this issue. - Scan result policies created at the group or sub-group level can take some time to apply to all the merge requests in the group. - Scheduled scan execution policies run with a minimum 15 minute cadence. Learn more [about the schedule rule type](../policies/scan-execution-policies.md#schedule-rule-type). - When scheduling pipelines, keep in mind that CRON scheduling is based on UTC on GitLab SaaS and is based on your server time for self managed instances. When testing new policies, it may appear pipelines are not running properly when in fact they are scheduled in your server's timezone. -- When enforcing scan execution policies, security policies creates a bot in the target project that will trigger scheduled pipelines to ensure enforcement. If the bot is +- When enforcing scan execution policies, security policies creates a bot in the target project that will trigger scheduled pipelines to ensure enforcement. If the bot is deleted or missing, the target project's pipeline will not be executed. To recreate a security policy bot user unlink and link the security policy project again. - You should not link a security policy project to a development project and to the group or sub-group the development project belongs to at the same time. Linking this way will result in approval rules from the Scan Result Policy not being applied to merge requests in the development project. - When creating a Scan Result Policy, neither the array `severity_levels` nor the array `vulnerability_states` in the [scan_finding rule](../policies/scan-result-policies.md#scan_finding-rule-type) can be left empty; for a working rule, at least one entry must exist. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index 834a50f39ef..ac15dfc0a47 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -97,7 +97,12 @@ the following sections and tables provide an alternative. ## `pipeline` rule type > - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. -> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. +> - Generally available in GitLab 16.2. Feature flag `security_policies_branch_type` removed. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. This rule enforces the defined actions whenever the pipeline runs for a selected branch. @@ -106,33 +111,35 @@ This rule enforces the defined actions whenever the pipeline runs for a selected | `type` | `string` | true | `pipeline` | The rule's type. | | `branches` <sup>1</sup> | `array` of `string` | true if `branch_type` field does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `branch_type` <sup>1</sup> | `string` | true if `branches` field does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | 1. You must specify only one of `branches` or `branch_type`. ## `schedule` rule type > - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. -> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. -> - The security policy bot users were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394958) in GitLab 16.3 [with flags](../../../administration/feature_flags.md) named `scan_execution_group_bot_users` and `scan_execution_bot_users`. Enabled by default. +> - Generally available in GitLab 16.2. Feature flag `security_policies_branch_type` removed. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. FLAG: -On self-managed GitLab, security policy bot users are available. To hide the feature, an administrator can [disable the feature flags](../../../administration/feature_flags.md) named `scan_execution_group_bot_users` and `scan_execution_bot_users`. +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. On GitLab.com, this feature is available. -This rule enforces the defined actions and schedules a scan on the provided date/time. +This rule schedules a scan pipeline, enforcing the defined actions on the schedule defined in the `cadence` field. A scheduled pipeline does not run other jobs defined in the project's `.gitlab-ci.yml` file. When a project is linked to a security policy project, a security policy bot is created in the project and will become the author of any scheduled pipelines. | Field | Type | Required | Possible values | Description | |------------|------|----------|-----------------|-------------| | `type` | `string` | true | `schedule` | The rule's type. | | `branches` <sup>1</sup> | `array` of `string` | true if either `branch_type` or `agents` fields does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `branch_type` <sup>1</sup> | `string` | true if either `branches` or `agents` fields does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `cadence` | `string` | true | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. Minimum of 15 minute intervals when used together with the `branches` field. | | `timezone` | `string` | false | Time zone identifier (for example, `America/New_York`) | Time zone to apply to the cadence. Value must be an IANA Time Zone Database identifier. | | `agents` <sup>1</sup> | `object` | true if either `branch_type` or `branches` fields do not exists | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. | 1. You must specify only one of `branches`, `branch_type`, or `agents`. -Scheduled scan pipelines are triggered by a security policy bot user that is a guest member of the project. Security policy bot users are automatically created when the security policy project is linked, and removed when the security policy project is unlinked. +Scheduled scan pipelines are triggered by a security policy bot user that is a guest member of the project with elevated permissions for users of type `security_policy_bot` so it may carry out this task. Security policy bot users are automatically created when the security policy project is linked, and removed when the security policy project is unlinked. If the project does not have a security policy bot user, the scheduled scan pipeline will not be triggered. To recreate a security policy bot user unlink and link the security policy project again. @@ -214,11 +221,12 @@ Note the following: is not scheduled successfully. - For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) are not supported. -- A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in +- A secret detection scan runs in `default` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-detection) mode when executed as part of a scheduled scan. - 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). ## Example security policies project diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index c5cfd63641b..a42b3f02c26 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -84,23 +84,36 @@ the following sections and tables provide an alternative. ## Scan result policy schema +> The `approval_settings` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. +On GitLab.com, this feature is not available. + | Field | Type | Required |Possible values | Description | |-------|------|----------|----------------|-------------| | `name` | `string` | true | | Name of the policy. Maximum of 255 characters.| | `description` (optional) | `string` | true | | Description of the policy. | | `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | | `rules` | `array` of rules | true | | List of rules that the policy applies. | -| `actions` | `array` of actions | true | | List of actions that the policy enforces. | +| `actions` | `array` of actions | false| | List of actions that the policy enforces. | +| `approval_settings` | `object` | false | `{prevent_approval_by_author: boolean, prevent_approval_by_commit_author: boolean, remove_approvals_with_new_commit: boolean, require_password_to_approve: boolean}` | Project settings that the policy overrides. | ## `scan_finding` rule type > - The scan result policy field `vulnerability_attributes` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123052) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/418784) in GitLab 16.3. > - The scan result policy field `vulnerability_age` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123956) in GitLab 16.2. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. FLAG: On self-managed GitLab, by default the `vulnerability_attributes` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. On GitLab.com, this feature is available. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. + This rule enforces the defined actions based on security scan findings. | Field | Type | Required | Possible values | Description | @@ -108,6 +121,7 @@ This rule enforces the defined actions based on security scan findings. | `type` | `string` | true | `scan_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | | `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `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. | @@ -119,6 +133,11 @@ This rule enforces the defined actions based on security scan findings. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. This rule enforces the defined actions based on license findings. @@ -127,10 +146,30 @@ This rule enforces the defined actions based on license findings. | `type` | `string` | true | `license_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | | `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `match_on_inclusion` | `boolean` | true | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | | `license_types` | `array` of `string` | true | license types | [SPDX license names](https://spdx.org/licenses) to match on, for example `Affero General Public License v1.0` or `MIT License`. | | `license_states` | `array` of `string` | true | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. The `newly_detected` state triggers approval when either a new package is introduced or when a new license for an existing package is detected. | +## `any_merge_request` rule type + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. + +This rule enforces the defined actions for any merge request based on the commits signature. + +| Field | Type | Required | Possible values | Description | +|---------------|---------------------|--------------------------------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | `string` | true | `any_merge_request` | The rule's type. | +| `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | +| `commits` | `string` | true | `any`, `unsigned` | Whether the rule matches for any commits, or only if unsigned commits are detected in the merge request. | + ## `require_approval` action type This action sets an approval rule to be required when conditions are met for at least one rule in diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 832ad100701..f896616d537 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -64,7 +64,7 @@ content directly. Instead, it enhances the results with additional properties, i - CWEs. - Location tracking fields. -- A means of identifying false positives or insignificant findings. **(ULTIMATE)** +- A means of identifying false positives or insignificant findings. **(ULTIMATE ALL)** ## Transition to Semgrep-based scanning diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 4ae8f1c4f8b..90731114303 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -7,10 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Customize rulesets **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for > passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. -> - [Added](https://gitlab.com/gitlab-org/security-products/analyzers/ruleset/-/merge_requests/18) support for specifying ambiguous passthrough refs in GitLab 16.2. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. +> - [Enabled](https://gitlab.com/gitlab-org/security-products/analyzers/ruleset/-/merge_requests/18) support for specifying ambiguous passthrough refs in GitLab 16.2. You can customize the behavior of our SAST analyzers by [defining a ruleset configuration file](#create-the-configuration-file) in the repository being scanned. There are two kinds of customization: @@ -29,8 +29,8 @@ 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). -- Findings for the disabled rule no longer appear in the [Pipeline Security tab](../index.md#view-security-scan-information-in-the-pipeline-security-tab). -- Existing findings for the disabled rule on the default branch are marked ["No longer detected"](../vulnerability_report/index.md#activity-filter) in the [Vulnerability Report](../index.md#view-security-scan-information-in-the-vulnerability-report). +- 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). The Semgrep-based analyzer handles disabled rules differently: diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 717608274e5..acc7e9d9e84 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -55,21 +55,16 @@ 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 Core<sup>3</sup> | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 11.0 | -| .NET Framework<sup>3</sup> | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 13.0 | | .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 | | 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/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<sup>2</sup> | [Gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | 10.7 | | 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 | | 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<sup>1, 2</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (SBT) | | Java (Android) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | -| JavaScript<sup>2</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.8 | | 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 | | 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 | @@ -77,24 +72,34 @@ For more information about our plans for language support in SAST, see the [cate | 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<sup>2</sup> | [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | 10.3 | | 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<sup>2</sup> | [ESLint react plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 12.5 | | 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 | | 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) | | Swift (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | -| TypeScript<sup>2</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | | 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 | 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. -1. These analyzers reached [End of Support](https://about.gitlab.com/handbook/product/gitlab-the-product/#end-of-support) status [in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554). -1. Security Code Scan reached [End of Support](https://about.gitlab.com/handbook/product/gitlab-the-product/#end-of-support) status [in GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/390416). + +## End of supported analyzers + +GitLab has reached [End of Support](https://about.gitlab.com/handbook/product/gitlab-the-product/#end-of-support) for the below analyzers. These analyzers have been replaced by the Semgrep-based analyzer. + +| Language / framework | [Analyzer](analyzers.md) used for scanning | Minimum supported GitLab version | End Of Support GitLab version | +|------------------------------|--------------------------------------------------------------------------------------------------------------| --------------------------------- | ------------------------------------------------------------- | +| .NET Core | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 11.0 | [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/390416) | +| .NET Framework | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 13.0 | [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/390416) | +| Go | [Gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | 10.7 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| Java | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (SBT) | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| Python | [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | 10.3 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| React | [ESLint react plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 12.5 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| JavaScript | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.8 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| TypeScript | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.9, with ESLint in 13.2 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | ## Multi-project support @@ -151,8 +156,9 @@ Advanced vulnerability tracking is available in a subset of the [supported langu - C++, in the Flawfinder analyzer only - C#, in the Semgrep-based analyzer only - Go, in the Semgrep-based analyzer only -- Java, in the Semgrep-based and mobsf analyzers +- Java, in the mobsf, Semgrep-based and SpotBugs analyzers - JavaScript, in the Semgrep-based and NodeJS-Scan analyzers +- PHP, in the phpcs-security-audit analyzer - Python, in the Semgrep-based analyzer only - Ruby, in the Brakeman-based analyzer @@ -278,7 +284,7 @@ successfully, and an error may occur. To enable and configure SAST with customizations: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. If the project does not have a `.gitlab-ci.yml` file, select **Enable SAST** in the Static Application Security Testing (SAST) row, otherwise select **Configure SAST**. @@ -300,7 +306,7 @@ successfully, and an error may occur. To enable and configure SAST with default settings: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the SAST section, select **Configure with a merge request**. 1. Review and merge the merge request to enable SAST. @@ -619,7 +625,7 @@ For information, see [Download job artifacts](../../../ci/jobs/job_artifacts.md# 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-secret-detection-report.json`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/qa/expect/secrets/gl-secret-detection-report.json) example. +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 diff --git a/doc/user/application_security/sast/rules.md b/doc/user/application_security/sast/rules.md new file mode 100644 index 00000000000..4e7a6387f9b --- /dev/null +++ b/doc/user/application_security/sast/rules.md @@ -0,0 +1,101 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# SAST rules **(FREE)** + +GitLab SAST uses a set of [analyzers](analyzers.md) to scan code for potential vulnerabilities. +Each analyzer processes the code then uses rules to find possible weaknesses in source code. +The rules determine what types of weaknesses the analyzer reports. + +## Source of rules + +### Semgrep-based analyzer + +GitLab creates, maintains, and supports the rules that are used in the Semgrep-based GitLab SAST analyzer. +This analyzer scans [many languages](index.md#supported-languages-and-frameworks) in a single CI/CD pipeline job. +It combines: + +- the Semgrep open-source engine. +- GitLab-managed detection rules. +- GitLab proprietary technology for [vulnerability tracking](index.md#advanced-vulnerability-tracking) and [false positive detection](index.md#false-positive-detection). + +### Other analyzers + +GitLab SAST uses other analyzers to scan the remaining [supported languages](index.md#supported-languages-and-frameworks). +The rules for these scans are defined in the upstream projects for each scanner. + +## How rule updates are released + +GitLab updates rules regularly based on customer feedback and internal research. +Rules are released as part of the container image for each analyzer. +You automatically receive updated analyzers and rules unless you [manually pin analyzers to a specific version](index.md#pinning-to-minor-image-version). + +Analyzers and their rules are updated [at least monthly](../index.md#vulnerability-scanner-maintenance) if relevant updates are available. + +The GitLab ruleset for the Semgrep-based analyzer is managed in [the GitLab-managed open-source `sast-rules` project](https://gitlab.com/gitlab-org/security-products/sast-rules). +When rules are updated, they're released as part of the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep)'s container image. + +## Configure rules in your projects + +You should use the default SAST rules unless you have a specific reason to make a change. +The default ruleset is designed to be relevant to most projects. + +However, you can [customize which rules are used](#apply-local-rule-preferences) or [control how rule changes are rolled out](#coordinate-rule-rollouts) if needed. + +### Apply local rule preferences + +You may want to customize the rules used in SAST scans because: + +- Your organization has assigned priorities to specific vulnerability classes, such as choosing to address Cross-Site Scripting (XSS) or SQL Injection before other classes of vulnerabilities. +- You believe that a specific rule is a false positive result or isn't relevant in the context of your codebase. + +To change which rules are used to scan your projects, adjust their severity, or apply other preferences, see [Customize rulesets](customize_rulesets.md). +If your customization would benefit other users, consider [reporting a problem to GitLab](#report-a-problem-with-a-gitlab-sast-rule). + +### Coordinate rule rollouts + +To control the rollout of rule changes, you can [pin SAST analyzers to a specific version](index.md#pinning-to-minor-image-version). + +If you want to make these changes at the same time across multiple projects, consider setting the variables in: + +- [Group-level CI/CD variables](../../../ci/variables/index.md#for-a-group). +- Custom CI/CD variables in a [Scan Execution Policy](../policies/scan-execution-policies.md). + +## Report a problem with a GitLab SAST rule +<!-- This title is intended to match common search queries users might make. --> + +GitLab welcomes contributions to the rulesets used in SAST. +Contributions might address: + +- False positive results, where the potential vulnerability is incorrect. +- False negative results, where SAST did not report a potential vulnerability that truly exists. +- The name, severity rating, description, guidance, or other explanatory content for a rule. + +If you believe a detection rule could be improved for all users, consider: + +- Submitting a merge request to [the `sast-rules` repository](https://gitlab.com/gitlab-org/security-products/sast-rules). See the [contribution instructions](https://gitlab.com/gitlab-org/security-products/sast-rules#contributing) for details. +- Filing an issue in [the `gitlab-org/gitlab` issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues/). + - Post a comment that says `@gitlab-bot label ~"group::static analysis" ~"Category:SAST"` so your issue lands in the correct triage workflow. + +## Important rule changes + +GitLab updates SAST rules [regularly](#how-rule-updates-are-released). +This section highlights the most important changes. +More details are available in release announcements and in the CHANGELOG links provided. + +### Rule changes in the Semgrep-based analyzer + +Key changes to the GitLab-managed ruleset for Semgrep-based scanning include: + +- Beginning in GitLab 16.3, the GitLab Static Analysis and Vulnerability Research teams are working to remove rules that tend to produce too many false positive results or not enough actionable true positive results. Existing findings from these removed rules are [automatically resolved](index.md#automatic-vulnerability-resolution); they no longer appear in the [Security Dashboard](../security_dashboard/index.md#view-vulnerabilities-over-time-for-a-project) or in the default view of the [Vulnerability Report](../vulnerability_report/index.md). This work is tracked in [epic 10907](https://gitlab.com/groups/gitlab-org/-/epics/10907). +- In GitLab 16.0 through 16.2, the GitLab Vulnerability Research team updated the guidance that's included in each result. +- In GitLab 15.10, the `detect-object-injection` rule was [removed by default](https://gitlab.com/gitlab-org/gitlab/-/issues/373920) and its findings were [automatically resolved](index.md#automatic-vulnerability-resolution). + +For more details, see the [CHANGELOG for `sast-rules`](https://gitlab.com/gitlab-org/security-products/sast-rules/-/blob/main/CHANGELOG.md). + +### Rule changes in other analyzers + +See the CHANGELOG file for each [analyzer](analyzers.md) for details of the changes, including new or updated rules, included in each version. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 10e8356de16..a10c029bec6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -27,7 +27,7 @@ You can run scans and view [Secret Detection JSON report artifacts](../../../ci/ With GitLab Ultimate, Secret Detection results are also processed so you can: -- See them in the [merge request widget](../index.md#view-security-scan-information-in-merge-requests), [pipeline security report](../vulnerability_report/pipeline.md), and [Vulnerability Report](../vulnerability_report/index.md). +- See them in the [merge request widget](../index.md#merge-request), [pipeline security report](../vulnerability_report/pipeline.md), and [vulnerability report](../vulnerability_report/index.md) UIs. - Use them in approval workflows. - Review them in the security dashboard. - [Automatically respond](automatic_response.md) to leaks in public repositories. @@ -155,7 +155,7 @@ To enable Secret Detection, either: This method requires you to manually edit the existing `.gitlab-ci.yml` file. Use this method if your GitLab CI/CD configuration file is complex. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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: @@ -188,7 +188,7 @@ error may occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manu To enable Secret Detection: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Secret Detection** row, select **Configure with a merge request**. 1. Optional. Complete the fields. @@ -338,12 +338,14 @@ To enable full history Secret Detection, set the variable `SECRET_DETECTION_HIST ## Custom rulesets **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for passthrough chains. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for passthrough chains. > Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in > GitLab 14.8. -You can customize the default Secret Detection rules provided with GitLab. +You can customize which [secrets are reported in the GitLab UI](#secret-detection). +However, the `secret_detection` job logs always include the number +of secrets detected by the default Secret Detection rules. The following customization options can be used separately, or in combination: @@ -510,7 +512,7 @@ optional authentication, and optional Git SHA. The variable uses the following f ``` NOTE: -Loading local project configuration takes precedence over `SECRET_DETECTION_RULESET_GIT_REFERENCE` values. +A local `.gitlab/secret-detection-ruleset.toml` file in the project takes precedence over `SECRET_DETECTION_RULESET_GIT_REFERENCE`. The following example includes the Secret Detection template in a project to be scanned and specifies the `SECRET_DETECTION_RULESET_GIT_REFERENCE` variable for referencing a separate project configuration. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md index 0b028f6936d..f4fb8c49277 100644 --- a/doc/user/application_security/secure_your_application.md +++ b/doc/user/application_security/secure_your_application.md @@ -27,3 +27,4 @@ GitLab can check your applications for security vulnerabilities. - [Policies](policies/index.md) - [Security scanner integration](../../development/integrations/secure.md) - [Secure and Govern Terminology](terminology/index.md) +- [GitLab Advisory Database](gitlab_advisory_database/index.md) diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b6d95e53227..53a6dfe6d0a 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -66,7 +66,7 @@ Project Security Dashboards show statistics for all vulnerabilities with a curre To view total number of vulnerabilities over time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security dashboard**. 1. Filter and search for what you need. - To filter the chart by severity, select the legend name. @@ -79,7 +79,7 @@ To view total number of vulnerabilities over time: To download an SVG image of the vulnerabilities chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security dashboard**. 1. Select **Save chart as an image** (**{download}**). @@ -90,7 +90,7 @@ branches of projects in a group and its subgroups. To view vulnerabilities over time for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Security > Security dashboard**. 1. Hover over the chart to get more details about vulnerabilities. - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). @@ -104,7 +104,7 @@ Use the group Security Dashboard to view the security status of projects. To view project security status for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Security dashboard**. Each project is assigned a letter [grade](#project-vulnerability-grades) according to the highest-severity open vulnerability. @@ -142,7 +142,7 @@ The Security Center includes: To view the Security Center: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Select **Security > Security dashboard**. @@ -150,7 +150,7 @@ To view the Security Center: To add projects to the Security Center: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Expand **Security**. 1. Select **Settings**. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index fa0027754ad..34c57292767 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -24,10 +24,10 @@ change its status to **Resolved**. This ensures that if it is accidentally reint merge, it is reported again as a new record. To change the status of multiple vulnerabilities, use the Vulnerability Report's [Activity filter](../vulnerability_report/index.md#activity-filter). -## Explaining a vulnerability (Beta) **(ULTIMATE SAAS)** +## Explaining a vulnerability **(ULTIMATE SAAS BETA)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10368) in GitLab 16.0 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) on GitLab.com. -> - Promoted to [Beta](../../../policy/experiment-beta-support.md#beta) status in 16.2. +> - Promoted to [Beta](../../../policy/experiment-beta-support.md#beta) status in GitLab 16.2. GitLab can help you with a vulnerability by using a large language model to: @@ -37,8 +37,8 @@ GitLab can help you with a vulnerability by using a large language model to: ### Explain a vulnerability -Use the explain this vulnerability feature to better understand a vulnerability and its possible -mitigation. +Explain a vulnerability with GitLab Duo Vulnerability summary. Use the explanation to better +understand a vulnerability and its possible mitigation. Prerequisites: @@ -46,11 +46,11 @@ Prerequisites: - You must be a member of the project. - The vulnerability must be a SAST finding. -Learn more about [how to enable all AI features](../../ai_features.md#enable-aiml-features). +Learn more about [how to enable all GitLab Duo features](../../ai_features.md#enable-aiml-features). To explain the vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Security and Compliance > Vulnerability report**. 1. In the **Tool** dropdown list, select **SAST**. 1. Select the SAST vulnerability you want explained. @@ -108,7 +108,7 @@ When dismissing a vulnerability, one of the following reasons must be chosen to To change a vulnerability's status from its Vulnerability Page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Status** dropdown list select a status, then select **Change status**. @@ -130,15 +130,11 @@ You can create either: - [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). - [A Jira issue](#create-a-jira-issue-for-a-vulnerability). -Creating a Jira issue requires that -[Jira integration](../../../integration/jira/index.md) is enabled on the project. Note -that when Jira integration is enabled, the GitLab issue feature is not available. - ### Create a GitLab issue for a vulnerability To create a GitLab issue for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create issue**. @@ -157,7 +153,7 @@ Prerequisites: To create a Jira issue for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create Jira issue**. @@ -169,28 +165,21 @@ fields are pre-populated from the vulnerability's details. Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the GitLab user interface. -## Linking a vulnerability to issues - -NOTE: -If Jira issue support is enabled, GitLab issues are disabled so this feature is not available. +## Linking a vulnerability to GitLab and Jira issues -You can link a vulnerability to one or more existing GitLab issues. Adding a link helps track -the issue that resolves or mitigates a vulnerability. +You can link a vulnerability to one or more existing [GitLab](#create-a-gitlab-issue-for-a-vulnerability) +or [Jira](#create-a-jira-issue-for-a-vulnerability) issues. Only one linking feature is available at the same time. +Adding a link helps track the issue that resolves or mitigates a vulnerability. -Issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page. +### Link a vulnerability to existing GitLab issues -Be aware of the following conditions between a vulnerability and a linked issue: +Prerequisite: -- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability - it's related to. -- An issue can only be related to one vulnerability at a time. -- Issues can be linked across groups and projects. +- [Jira issue integration](../../../integration/jira/configure.md) must not be enabled. -## Link a vulnerability to existing issues +To link a vulnerability to existing GitLab issues: -To link a vulnerability to existing issues: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. In the **Linked issues** section, select the plus icon (**{plus}**). @@ -199,9 +188,43 @@ To link a vulnerability to existing issues: - Enter the issue's ID (prefixed with a hash `#`). 1. Select **Add**. -The selected issues are added to the **Linked issues** section, and the linked issues counter is +The selected GitLab issues are added to the **Linked items** section, and the linked issues counter is +updated. + +GitLab issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page. + +Be aware of the following conditions between a vulnerability and a linked GitLab issue: + +- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability + it's related to. +- An issue can only be related to one vulnerability at a time. +- Issues can be linked across groups and projects. + +### Link a vulnerability to existing Jira issues + +Prerequisite: + +- [Jira issue integration](../../../integration/jira/configure.md) must be enabled, with option **Enable Jira issue creation from vulnerabilities** also enabled. + +To link a vulnerability to existing Jira issues, add the following line to the Jira issue's description: + +```plaintext +/-/security/vulnerabilities/<id> +``` + +`<id>` is any [vulnerability ID](../../../api/vulnerabilities.md#single-vulnerability). +You can add several lines with different IDs to one description. + +Jira issues with appropriate description are added to the **Related Jira issues** section, and the linked issues counter is updated. +Jira issues linked to a vulnerability are shown only on the vulnerability page. + +Be aware of the following conditions between a vulnerability and a linked Jira issue: + +- The vulnerability page and the issue page show the vulnerability they are related to. +- An issue can be related to one or more vulnerabilities at the same time. + ## Resolve a vulnerability For some vulnerabilities a solution is already known. In those instances, a vulnerability's page @@ -225,7 +248,7 @@ To resolve a vulnerability, you can either: To resolve the vulnerability with a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Resolve with merge request**. @@ -237,7 +260,7 @@ Process the merge request according to your standard workflow. To manually apply the patch that GitLab generated for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Download patch to resolve**. @@ -260,7 +283,7 @@ Security training helps your developers learn how to fix vulnerabilities. Develo To enable security training for vulnerabilities in your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. On the tab bar, select **Vulnerability Management**. 1. To enable a security training provider, turn on the toggle. @@ -280,7 +303,7 @@ Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability for which you want to view security training. 1. Select **View training**. diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 46ce3173ee7..3ec1151b1d6 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -40,8 +40,6 @@ status of a Jira issue is not shown in the GitLab UI. ## Project-level Vulnerability Report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in GitLab 11.1. - At the project level, the Vulnerability Report also contains: - A time stamp showing when it was updated, including a link to the latest pipeline. @@ -55,7 +53,7 @@ this page displays the vulnerabilities that originate from the selected project. To view the project-level vulnerability report: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. ## Vulnerability Report actions @@ -129,8 +127,6 @@ The content of the Project filter depends on the current level: ### Activity filter -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259255) in GitLab 13.9 - The Activity filter behaves differently from the other filters. The selected values form mutually exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not all options can be selected in combination. @@ -150,8 +146,6 @@ To view more details of a vulnerability, select the vulnerability's **Descriptio ## View vulnerable source location -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267509) in GitLab 13.10. - Some security scanners output the filename and line number of a potential vulnerability. When that information is available, the vulnerability's details include a link to the relevant file, in the default branch. @@ -160,8 +154,7 @@ To view the relevant file, select the filename in the vulnerability's details. ## Change status of vulnerabilities -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292636) in GitLab 13.10, all statuses became selectable. -> - Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0. +> Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0. From the Vulnerability Report you can change the status of one or more vulnerabilities. @@ -184,9 +177,6 @@ To sort vulnerabilities by the date each vulnerability was detected, select the ## Export vulnerability details -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in GitLab 13.0. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in GitLab 13.1. - 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. @@ -229,8 +219,6 @@ thousands of vulnerabilities. Do not close the page until the download finishes. ## Dismiss a vulnerability -> The option of adding a dismissal reason was introduced in GitLab 12.0. - When you evaluate a vulnerability and decide it requires no more action, you can mark it as **Dismissed**. Dismissed vulnerabilities do not appear in the merge request security widget @@ -260,7 +248,7 @@ To undo this action, select a different status from the same menu. To add a new vulnerability finding from your project level Vulnerability Report page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 7a414e9a4ae..ef66925b9c9 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w To view vulnerabilities in a pipeline: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipelines**. 1. From the list, select the pipeline you want to check for vulnerabilities. 1. Select the **Security** tab. @@ -25,9 +25,11 @@ For example, if a pipeline contains DAST and SAST jobs, but the DAST job fails b [exit code](../../../development/integrations/secure.md#exit-code), the report doesn't show DAST results. The pipeline vulnerability report only shows results contained in the security report artifacts. This report differs from -the [Vulnerability Report](index.md), which contains cumulative results of all successful jobs, and from the merge request -[security widget](../index.md#view-security-scan-information-in-merge-requests), which combines the branch results with -cumulative results. +the [vulnerability report](index.md), which contains cumulative results of all successful jobs, and from the merge request +[security widget](../index.md#merge-request), which contains new vulnerability findings that don't already exist on the default branch. + +NOTE: +If a new advisory is added to our advisory database and the last pipeline for the default branch is stale, the resulting vulnerability may appear in the MR widget as "New" when it is already in the default branch. This will be resolved by [Continuous Vulnerability Scans](https://gitlab.com/groups/gitlab-org/-/epics/7886). The pipeline vulnerability report only displays after the pipeline is complete. If the pipeline has a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), the pipeline waits for the manual job and the vulnerabilities cannot be displayed if the blocking manual job did not run. diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index a7c58b4d2a8..26cccd7584e 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -47,7 +47,7 @@ To remove an emoji reaction, select the emoji again. > - [Introduced for GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../administration/feature_flags.md) named `custom_emoji`. Disabled by default. > - Enabled on GitLab.com in GitLab 14.0. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/333095) UI to add emoji in GitLab 16.2. +> - UI to add emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333095) in GitLab 16.2. Custom emoji show in the emoji picker everywhere you can react with emoji. To add an emoji reaction to a comment or description: diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 260263632c5..a1281d3d75c 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -15,9 +15,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - The ability to switch between certificate-based clusters and agents was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335089) in GitLab 14.9. The certificate-based cluster context is always called `gitlab-deploy`. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80508) from _CI/CD tunnel_ to _CI/CD workflow_ in GitLab 14.9. -You can use a GitLab CI/CD workflow to safely deploy to and update your Kubernetes clusters. +You can use GitLab CI/CD to safely connect, deploy, and update your Kubernetes clusters. -To do so, you must first [install an agent in your cluster](install/index.md). When done, you have a Kubernetes context and can +To do so, [install an agent in your cluster](install/index.md). When done, you have a Kubernetes context and can run Kubernetes API commands in your GitLab CI/CD pipeline. To ensure access to your cluster is safe: @@ -25,11 +25,11 @@ To ensure access to your cluster is safe: - Each agent has a separate context (`kubecontext`). - Only the project where the agent is configured, and any additional projects you authorize, can access the agent in your cluster. -The CI/CD workflow requires runners to be registered with GitLab, but these runners do not have to be in the cluster where the agent is. +To use GitLab CI/CD to interact with your cluster, runners must be registered with GitLab. However, these runners do not have to be in the cluster where the agent is. -## GitLab CI/CD workflow steps +## Use GitLab CI/CD with your cluster -To update a Kubernetes cluster by using GitLab CI/CD, complete the following steps. +To update a Kubernetes cluster with GitLab CI/CD: 1. Ensure you have a working Kubernetes cluster and the manifests are in a GitLab project. 1. In the same GitLab project, [register and install the GitLab agent](install/index.md). @@ -64,7 +64,7 @@ Authorization configuration can take one or two minutes to propagate. To authorize the agent to access the GitLab project where you keep Kubernetes manifests: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the left sidebar, select **Search or go to** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `projects` attribute. 1. For the `id`, add the path to the project. Do not wrap the path in quotation marks. @@ -89,7 +89,7 @@ Choose the context to run `kubectl` commands from your CI/CD scripts. To authorize the agent to access all of the GitLab projects in a group or subgroup: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the left sidebar, select **Search or go to** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `groups` attribute. 1. For the `id`, add the path: diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index f2d65b900f0..27724a95291 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -83,7 +83,7 @@ You must register `agentk` before you install it in your cluster. To register `agentk`: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. If you have an [agent configuration file](../install/index.md#create-an-agent-configuration-file), it must be in this project. Your cluster manifest files should also be in this project. 1. Select **Operate > Kubernetes clusters**. @@ -123,9 +123,7 @@ To install `agentk`: name: gitlab-agent-token type: Opaque stringData: - values.yaml: |- - config: - token: "<your-token-here>" + token: "<your-token-here>" ``` 1. Apply `secret.yaml` to your cluster: @@ -173,12 +171,11 @@ To install `agentk`: values: config: kasAddress: "wss://kas.gitlab.com" - valuesFrom: - - kind: Secret - name: gitlab-agent-token - valuesKey: values.yaml + secretName: gitlab-agent-token ``` + The Helm release uses the secret from the previous step. + 1. To verify that `agentk` is installed and running in the cluster, run the following command: ```shell diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 75571d1a4f5..d620a9f658c 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -43,7 +43,7 @@ To install the agent in your cluster: For configuration settings, the agent uses a YAML file in the GitLab project. You must create this file if: - You use [a GitOps workflow](../gitops/agent.md#gitops-workflow-steps). -- You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent. +- You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#use-gitlab-cicd-with-your-cluster) and want to authorize a different project to use the agent. - You [allow specific project or group members to access Kubernetes](../user_access.md). To create an agent configuration file: @@ -76,11 +76,11 @@ In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `ce Prerequisites: - For a [GitLab CI/CD workflow](../ci_cd_workflow.md), ensure that - [GitLab CI/CD is enabled](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). + [GitLab CI/CD is not disabled](../../../../ci/enable_or_disable_ci.md#disable-cicd-in-a-project). You must register an agent before you can install the agent in your cluster. To register an agent: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. If you have an [agent configuration file](#create-an-agent-configuration-file), it must be in this project. Your cluster manifest files should also be in this project. 1. Select **Operate > Kubernetes clusters**. @@ -114,22 +114,26 @@ To connect to multiple clusters, you must configure, register, and install an ag #### Install the agent with Helm +WARNING: +For simplicity, the default Helm chart configuration sets up a service account for the agent with `cluster-admin` rights. You should not use this on production systems. To deploy to a production system, follow the instructions in [Customize the Helm installation](#customize-the-helm-installation) to create a service account with the minimum permissions required for your deployment and specify that during installation. + To install the agent on your cluster using Helm: 1. [Install Helm](https://helm.sh/docs/intro/install/). 1. In your computer, open a terminal and [connect to your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/). 1. Run the command you copied when you [registered your agent with GitLab](#register-the-agent-with-gitlab). - -Optionally, you can [customize the Helm installation](#customize-the-helm-installation). If you install the agent on a production system, you should customize the Helm installation to skip creating the service account. +1. Optional. [Customize the Helm installation](#customize-the-helm-installation). + If you install the agent on a production system, you should customize the Helm installation to restrict the permissions of the service account. See [How to deploy the GitLab Agent for Kubernetes with limited permissions](https://about.gitlab.com/blog/2021/09/10/setting-up-the-k-agent/). ##### Customize the Helm installation By default, the Helm installation command generated by GitLab: - Creates a namespace `gitlab-agent` for the deployment (`--namespace gitlab-agent`). You can skip creating the namespace by omitting the `--create-namespace` flag. -- Sets up a service account for the agent with `cluster-admin` rights. You can: +- Sets up a service account for the agent and assigns it the `cluster-admin` role. You can: - Skip creating the service account by adding `--set serviceAccount.create=false` to the `helm install` command. In this case, you must set `serviceAccount.name` to a pre-existing service account. - - Skip creating the RBAC permissions by adding `--set rbac.create=false` to the `helm install` command. In this case, you must bring your own RBAC permissions for the agent. Otherwise, it has no permissions at all. + - Customise the role assigned to the service account by adding `--set rbac.useExistingRole <your role name>` to the `helm install` command. In this case, you should have a pre-created role with restricted permissions that can be used by the service account. + - Skip role assignment altogether by adding `--set rbac.create=false` to your `helm install` command. In this case, you must create `ClusterRoleBinding` manually. - 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. diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index a5989d823f6..21dc249b1d1 100644 --- a/doc/user/clusters/agent/user_access.md +++ b/doc/user/clusters/agent/user_access.md @@ -4,7 +4,7 @@ group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Grant users Kubernetes access (Beta) **(FREE ALL)** +# Grant users Kubernetes access **(FREE ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). > - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2. @@ -141,6 +141,60 @@ subjects: kind: Group ``` +## Access a cluster with the Kubernetes API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131144) in GitLab 16.4. + +You can configure an agent to allow GitLab users to access a cluster with the Kubernetes API. + +Prerequisite: + +- You have an agent configured with the `user_access` entry. + +To grant Kubernetes API access: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Operate > Kubernetes clusters** and retrieve the numerical ID of the agent you want to access. You need the ID to construct the full API token. +1. Create a [personal access token](../../profile/personal_access_tokens.md) with the `k8s_proxy` scope. You need the access token to construct the full API token. +1. Construct `kube config` entries to access the cluster: + 1. Make sure that the proper `kube config` is selected. + For example, you can set the `KUBECONFIG` environment variable. + 1. Add the GitLab KAS proxy cluster to the `kube config`: + + ```shell + kubectl config set-cluster <cluster_name> --server "https://kas.gitlab.com/k8s-proxy" + ``` + + The `server` argument points to the KAS address of your GitLab instance. + On GitLab.com, this is `https://kas.gitlab.com/k8s-proxy`. + You can get the KAS address of your instance when you register an agent. + + 1. Use your numerical agent ID and personal access token to construct an API token: + + ```shell + kubectl config set-credentials <gitlab_user> --token "pat:<agent-id>:<token>" + ``` + + 1. Add the context to combine the cluster and the user: + + ```shell + kubectl config set-context <gitlab_agent> --cluster <cluster_name> --user <gitlab_user> + ``` + + 1. Activate the new context: + + ```shell + kubectl config use-context <gitlab_agent> + ``` + +1. Check that the configuration works: + + ```shell + kubectl get nodes + ``` + +The configured user can access your cluster with the Kubernetes API. + ## Related topics - [Architectural blueprint](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kubernetes_user_access.md) diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index a967ec9ea24..a2dc50e43d7 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -9,9 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive is scheduled for removal in GitLab 16.0. -To view cluster vulnerabilities, you can view the [vulnerability report](../../application_security/vulnerabilities/index.md). -You can also configure your agent so the vulnerabilities are displayed with other agent information in GitLab. - ## Enable operational container scanning You can use operational container scanning to scan container images in your cluster for security vulnerabilities. You @@ -24,7 +21,7 @@ If both `agent config` and `scan execution policies` are configured, the configu ### Enable via agent configuration To enable scanning of all images within your Kubernetes cluster via the agent configuration, add a `container_scanning` configuration block to your agent -configuration with a `cadence` field containing a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run. +configuration with a `cadence` field containing a [CRON expression](https://en.wikipedia.org/wiki/Cron) for when the scans are run. ```yaml container_scanning: @@ -129,7 +126,7 @@ Resource requirements can only be set up using the agent configuration. If you e To view vulnerability information in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains the agent configuration file. 1. Select **Operate > Kubernetes clusters**. 1. Select the **Agent** tab. 1. Select an agent to view the cluster vulnerabilities. @@ -140,3 +137,9 @@ This information can also be found under [operational vulnerabilities](../../../ NOTE: You must have at least the Developer role. + +## Scanning private images + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415451) in GitLab 16.4. + +To scan private images, the scanner relies on the image pull secrets (direct references and from the service account) to pull the image. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 08e1021f886..70abbebaaad 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -4,9 +4,9 @@ group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Working with the agent for Kubernetes **(FREE ALL)** +# Managing the agent for Kubernetes instances **(FREE ALL)** -Use the following tasks when working with the agent for Kubernetes. +Use the following tasks when you work with the agent for Kubernetes. ## View your agents @@ -18,7 +18,7 @@ Prerequisite: To view the list of agents: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains your agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains your agent configuration file. You cannot view registered agents from a project that does not contain the agent configuration file. 1. Select **Operate > Kubernetes clusters**. 1. Select **Agent** tab to view clusters connected to GitLab through the agent. @@ -40,7 +40,7 @@ is shared with a project, it automatically appears in the project agent tab. To view the list of shared agents: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Kubernetes clusters**. 1. Select the **Agent** tab. @@ -54,7 +54,7 @@ The activity logs help you to identify problems and get the information you need for troubleshooting. You can see events from a week before the current date. To view an agent's activity: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains your agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains your agent configuration file. 1. Select **Operate > Kubernetes clusters**. 1. Select the agent you want to see activity for. @@ -115,7 +115,7 @@ An agent can have only two active tokens at one time. To reset the agent token without downtime: 1. Create a new token: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Kubernetes clusters**. 1. Select the agent you want to create a token for. 1. On the **Access tokens** tab, select **Create token**. @@ -137,7 +137,7 @@ clean up those resources manually. To remove an agent from the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains the agent configuration file. 1. Select **Operate > Kubernetes clusters**. 1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Delete agent**. diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md deleted file mode 100644 index a155dcf4a3c..00000000000 --- a/doc/user/clusters/cost_management.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Deploy -group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../index.md' ---- - -# Cluster cost management (removed) **(ULTIMATE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md deleted file mode 100644 index 0f389b94a33..00000000000 --- a/doc/user/clusters/integrations.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Deploy -group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../index.md' ---- - -# Cluster integrations (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 3341074f54d..3c5c90abdae 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -62,7 +62,7 @@ To associate a cluster management project with your cluster: - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - [Instance-level cluster](../instance/clusters/index.md): - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Kubernetes**. 1. Expand **Advanced settings**. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index f4f42f4dc27..a40fc5a262e 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -86,9 +86,7 @@ cluster applications with [Helm v3](https://helm.sh/). This file has a list of paths to other Helm files for each app. They're all commented out by default, so you must uncomment the paths for the apps that you would like to use in your cluster. -By default, each `helmfile.yaml` in these sub-paths has the attribute `installed: true`. This means that every time -the pipeline runs, Helmfile tries to either install or update your apps according to the current state of your -cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile tries try to uninstall this app +By default, each `helmfile.yaml` in these sub-paths has the attribute `installed: true`. This means that, depending on the state of your cluster and Helm releases, Helmfile attempts to install or update apps every time the pipeline runs. If you change this attribute to `installed: false`, Helmfile tries to uninstall this app from your cluster. [Read more](https://helmfile.readthedocs.io/en/latest/) about how Helmfile works. ### Built-in applications @@ -101,7 +99,6 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp - [Cert-manager](../infrastructure/clusters/manage/management_project_applications/certmanager.md) - [GitLab Runner](../infrastructure/clusters/manage/management_project_applications/runner.md) - [Ingress](../infrastructure/clusters/manage/management_project_applications/ingress.md) -- [Prometheus](../../operations/metrics/index.md) - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) Each application has an `applications/{app}/values.yaml` file. diff --git a/doc/user/compliance/compliance_center/index.md b/doc/user/compliance/compliance_center/index.md index bd3409abe01..2510b5e73a7 100644 --- a/doc/user/compliance/compliance_center/index.md +++ b/doc/user/compliance/compliance_center/index.md @@ -32,7 +32,7 @@ Prerequisites: To view the standards adherence dashboard for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. ### GitLab standard @@ -75,13 +75,13 @@ information, see [Merge request approval rules](../../project/merge_requests/app > - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. > - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/5237) in GitLab 14.10. [Feature flag `compliance_violations_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/346266) removed. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112111) to compliance violations report in GitLab 15.9. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/394950) ability to create/edit compliance frameworks in GitLab 16.0. +> - Ability to create and edit compliance frameworks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394950) in GitLab 16.0. With compliance violations report, you can see a high-level view of merge request activity for all projects in the group. When you select a row in the compliance report, a drawer appears that provides: -- The project name and [compliance framework label](../../project/settings/index.md#add-a-compliance-framework-to-a-project), +- The project name and [compliance framework label](../../project/working_with_projects.md#add-a-compliance-framework-to-a-project), if the project has one assigned. - A link to the merge request that introduced the violation. - The merge request's branch path in the format `[source] into [target]`. @@ -100,7 +100,7 @@ Prerequisites: To view the compliance violations report: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. You can sort the compliance report on: @@ -207,7 +207,7 @@ If the commit has a related merge commit, then the following are also included: To generate the Chain of Custody report: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. Select **List of all merge commits**. @@ -223,7 +223,7 @@ details for the provided commit SHA. To generate a commit-specific Chain of Custody report: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. At the top of the compliance report, to the right of **List of all commits**, select the down arrow (**{chevron-lg-down}**). @@ -254,7 +254,7 @@ Prerequisites: To view the compliance frameworks report: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. @@ -271,7 +271,7 @@ Prerequisites: To apply a compliance framework to one project in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. 1. Next to the project you want to add the compliance framework to, select **{plus}** **Add framework**. @@ -279,7 +279,7 @@ To apply a compliance framework to one project in a group: To apply a compliance framework to multiple projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. 1. Select multiple projects. @@ -300,20 +300,46 @@ Prerequisites: To remove a compliance framework from one project in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. 1. Next to the compliance framework to remove from the project, select **{close}** on the framework label. To remove a compliance framework from multiple projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. 1. Select multiple projects. 1. From the **Choose one bulk action** dropdown list, select **Remove framework from selected projects**. 1. Select **Remove**. +### Export a report of merge request compliance violations on projects in a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356791) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_violation_csv_export`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named +`compliance_violation_csv_export`. On GitLab.com, this feature is not available. The feature is not ready for production use. + +Export a report of merge request compliance violations on merge requests belonging to projects in a group. Reports: + +- Do not use filters on the violations report. +- Are truncated at 15 MB so the email attachment is not too large. + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To export a report of merge request compliance violations for projects in a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. On the left sidebar, select **Secure > Compliance center**. +1. On the page, select the **Violations** tab. +1. On the Violations tab, select the **Export full report as CSV** action in the top right corner + +A report is compiled and delivered to your email inbox as an attachment. + ### Export a report of compliance frameworks on projects in a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387912) in GitLab 16.0. @@ -329,7 +355,7 @@ Prerequisites: To export a report of compliance frameworks on projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. 1. On the Frameworks tab, select the **Export as CSV** action in the top right corner @@ -342,7 +368,7 @@ A report is compiled and delivered to your email inbox as an attachment. To filter the list of compliance frameworks: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. 1. In the search field: diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md index e3350b1ae10..cf5f340c0f6 100644 --- a/doc/user/compliance/license_approval_policies.md +++ b/doc/user/compliance/license_approval_policies.md @@ -41,7 +41,7 @@ Create a license approval policy to enforce license compliance. To create a license approval policy: 1. [Link a security policy project](../application_security/policies/index.md#managing-the-linked-security-policy-project) to your development group, subgroup, or project (the Owner role is required). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. 1. Create a new [Scan Result Policy](../application_security/policies/scan-result-policies.md). 1. In your policy rule, select **License scanning**. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md deleted file mode 100644 index 00578219016..00000000000 --- a/doc/user/compliance/license_compliance/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -type: reference, howto -stage: Secure -group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../license_approval_policies.md' ---- - -# License Compliance (removed) **(ULTIMATE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421363) in GitLab 16.3. -Use [License Approval Policies](https://gitlab.com/groups/gitlab-org/-/epics/8092) instead. diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md index 96ea43e5ce2..f315f319b71 100644 --- a/doc/user/compliance/license_list.md +++ b/doc/user/compliance/license_list.md @@ -20,7 +20,7 @@ requirements must be met: Alternatively, licenses will also appear under the license list when using our deprecated [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) as long as the following requirements are met: -1. The Dependency Scanning CI/CD job must be [enabled](license_scanning_of_cyclonedx_files/index.md#enable-license-scanning) for your project. +1. The Dependency Scanning CI/CD job must be [enabled](license_scanning_of_cyclonedx_files/index.md#configuration) for your project. 1. Your project must use at least one of the [supported languages and package managers](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md index 97f9f277776..98404ecd2ed 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -7,13 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # License scanning of CycloneDX files **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 for GitLab SaaS [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags are disabled by default and both flags must be enabled for this feature to work. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.10 for GitLab SaaS. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.10 for self-managed GitLab [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`, both of which must be enabled for this feature to work. The flags are disabled by default due to the initial performance load when the license database is first imported. Work to improve performance is being tracked in [issue 397670](https://gitlab.com/gitlab-org/gitlab/-/issues/397670). -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385173) in GitLab 15.11 for self-managed GitLab. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 for GitLab SaaS [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385176) in GitLab 16.4. Feature flags `license_scanning_sbom_scanner` and `package_metadata_synchronization` removed. -FLAG: -The legacy License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. To continue using GitLab for License Compliance, remove the License Compliance template from your CI/CD pipeline and add the [Dependency Scanning template](../../application_security/dependency_scanning/index.md#configuration). The Dependency Scanning template is now capable of gathering the required license information so it is no longer necessary to run a separate License Compliance job. The License Compliance CI/CD template should not be removed prior to verifying that the `license_scanning_sbom_scanner` and `package_metadata_synchronization` flags are enabled for the instance and that the instance has been upgraded to a version that supports the new method of license scanning. To begin using the Dependency Scanner quickly at scale, you may set up a [scan execution policy](../../application_security/policies/scan-execution-policies.md) at the group level to enforce the SBOM-based license scan for all projects in the group. Then, you may remove the inclusion of the `Jobs/License-Scanning.gitlab-ci.yml` template from your CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do so by setting the `LICENSE_MANAGEMENT_VERSION CI` variable to `4`. This variable can be set at the [project](../../../ci/variables/index.md#for-a-project), [group](../../../ci/variables/index.md#for-a-group) or [instance](../../../ci/variables/index.md#for-an-instance) level. This configuration change will allow you to continue using an existing version of the License Compliance without having to adopt the new approach. **Bugs and vulnerabilities in this legacy analyzer will no longer be fixed.** +NOTE: +The legacy License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. To continue using GitLab for License Compliance, remove the License Compliance template from your CI/CD pipeline and add the [Dependency Scanning template](../../application_security/dependency_scanning/index.md#configuration). The Dependency Scanning template is now capable of gathering the required license information so it is no longer necessary to run a separate License Compliance job. The License Compliance CI/CD template should not be removed prior to verifying that the instance has been upgraded to a version that supports the new method of license scanning. To begin using the Dependency Scanner quickly at scale, you may set up a [scan execution policy](../../application_security/policies/scan-execution-policies.md) at the group level to enforce the SBOM-based license scan for all projects in the group. Then, you may remove the inclusion of the `Jobs/License-Scanning.gitlab-ci.yml` template from your CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do so by setting the `LICENSE_MANAGEMENT_VERSION CI` variable to `4`. This variable can be set at the [project](../../../ci/variables/index.md#for-a-project), [group](../../../ci/variables/index.md#for-a-group) or [instance](../../../ci/variables/index.md#for-an-instance) level. This configuration change will allow you to continue using the existing version of License Compliance to generate [license scanning report](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) artifacts in your pipelines. However, since legacy license scanning support is being removed from our codebase, switching back to this legacy analyzer prevents other License Compliance features from working as expected, so this approach is not recommended. In addition to this, **bugs and vulnerabilities in this legacy analyzer will no longer be fixed.** To detect the licenses in use, License Compliance relies on running the [Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), @@ -22,17 +20,16 @@ Other 3rd party scanners may also be used as long as they produce a CycloneDX fi This method of scanning is also capable of parsing and identifying over 500 different types of licenses, as defined in [the SPDX list](https://spdx.org/licenses/). Licenses not in the SPDX list are reported as "Unknown". License information can also be extracted from packages that are dual-licensed, or have multiple different licenses that apply. -## Enable license scanning +## Configuration -Prerequisites: - -- On GitLab self-managed only, enable [Synchronization with the GitLab License Database](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in Admin Area for the GitLab instance. On GitLab SaaS this step has already been completed. -- Enable [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration) - and ensure that its prerequisites are met. +Enable [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration) +and ensure that its prerequisites are met. From the `.gitlab-ci.yml` file, remove the deprecated line `Jobs/License-Scanning.gitlab-ci.yml`, if it's present. +On GitLab self-managed only, you can [choose package registry metadata to sync](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. + ## Supported languages and package managers License scanning is supported for the following languages and package managers: @@ -164,3 +161,29 @@ gemnasium-dependency_scanning: - apk update && apk add jq - jq '.components |= unique' gl-sbom-gem-bundler.cdx.json > tmp.json && mv tmp.json gl-sbom-gem-bundler.cdx.json ``` + +### Remove unused license data + +License scanning changes (released in GitLab 15.9) required a significant amount of additional disk space to be available on the instances. This issue was resolved in GitLab 16.3 by the [Reduce package metadata table on-disk footprint](https://gitlab.com/groups/gitlab-org/-/epics/10415) epic. But if your instance was running license scanning between GitLab 15.9 and 16.3, you may want to remove the unneeded data. + +To remove the unneeded data: + +1. Check if the [package_metadata_synchronization](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#new-license-compliance-scanner) feature flag is currently, or was previously enabled, and if so, disable it. Use [Rails console](../../../administration/operations/rails_console.md) to execute the following commands. + + ```ruby + Feature.enabled?(:package_metadata_synchronization) && Feature.disable(:package_metadata_synchronization) + ``` + +1. Check if there is deprecated data in the database: + + ```ruby + PackageMetadata::PackageVersionLicense.count + PackageMetadata::PackageVersion.count + ``` + +1. If there is deprecated data in the database, remove it by running the following commands in order: + + ```ruby + PackageMetadata::PackageVersionLicense.delete_all + PackageMetadata::PackageVersion.delete_all + ``` diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 53add75ee19..46e395af5bc 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -36,7 +36,7 @@ you must enable CRM features for the subgroup. To enable customer relations management in a group or subgroup: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group or subgroup. +1. On the left sidebar, select **Search or go to** and find your group or subgroup. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Customer relations is enabled**. @@ -52,7 +52,7 @@ Prerequisites: To view a group's contacts: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer contacts**.  @@ -65,7 +65,7 @@ Prerequisites: To create a contact: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer contacts**. 1. Select **New contact**. 1. Complete all required fields. @@ -82,7 +82,7 @@ Prerequisites: To edit an existing contact: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer contacts**. 1. Next to the contact you wish to edit, select **Edit** (**{pencil}**). 1. Edit the required fields. @@ -100,7 +100,7 @@ Each contact can be in one of two states: To change the state of a contact: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer contacts**. 1. Next to the contact you wish to edit, select **Edit** (**{pencil}**). 1. Select or clear the **Active** checkbox. @@ -116,7 +116,7 @@ Prerequisites: To view a group's organizations: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer organizations**.  @@ -129,7 +129,7 @@ Prerequisites: To create an organization: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer organizations**. 1. Select **New organization**. 1. Complete all required fields. @@ -146,7 +146,7 @@ Prerequisites: To edit an existing organization: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer organizations**. 1. Next to the organization you wish to edit, select **Edit** (**{pencil}**). 1. Edit the required fields. @@ -168,7 +168,7 @@ Prerequisites: To view a contact's issues, select a contact from the issue sidebar, or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer contacts**. 1. Next to the contact whose issues you wish to view, select **View issues** (**{issues}**). @@ -180,7 +180,7 @@ Prerequisites: To view an organization's issues: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Customer organizations**. 1. Next to the organization whose issues you wish to view, select **View issues** (**{issues}**). diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 0bdbfe79775..9d4a151cc53 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -13,7 +13,7 @@ type: reference, howto > - Paginated merge request discussions [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370075) in GitLab 15.8. Feature flag `paginated_mr_discussions` removed. GitLab encourages communication through comments, threads, and -[code suggestions](../project/merge_requests/reviews/suggestions.md). +[Code Suggestions](../project/merge_requests/reviews/suggestions.md). Two types of comments are available: @@ -275,3 +275,29 @@ To create a thread: A threaded comment is created.  + +## Resolve a thread + +> - Resolvable threads for issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. Disabled by default. +> - Resolvable threads for issues [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.4. + +FLAG: +On self-managed GitLab, resolvable threads _for issues_ are available by default. +To hide the feature, an administrator can +[disable the feature flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. +On GitLab.com, this feature is available. + +You can resolve a thread when you want to finish a conversation. + +Prerequisites: + +- You must be in an issue or merge request. +- You must have at least the Developer role or be the author of the issue or merge request. + +To resolve a thread: + +1. Go to the thread. +1. Do one of the following: + - In the upper-right corner of the original comment, select **Resolve thread** (**{check-circle}**). + - Below the last reply, in the **Reply** field, select **Resolve thread**. + - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index e7be5bfb140..04683620ba9 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference @@ -79,7 +79,7 @@ For more information on group-level domain verification, see [epic 5299](https:/ The custom domain must match the email domain exactly. For example, if your email is `username@example.com`, verify the `example.com` domain. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. On the left sidebar, select **Search or go to** and find your top-level group. 1. Select **Settings > Domain Verification**. 1. In the upper-right corner, select **Add Domain**. 1. In **Domain**, enter the domain name. @@ -105,7 +105,7 @@ and paste them in your domain's control panel as a `TXT` record. After you have added all the DNS records: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Domain Verification**. 1. On the domain table row, Select **Retry verification** (**{retry}**). @@ -125,7 +125,7 @@ For GitLab instances with domain verification enabled, if the domain cannot be v To view all configured domains in your group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. On the left sidebar, select **Search or go to** and find your top-level group. 1. Select **Settings > Domain Verification**. You then see: @@ -138,7 +138,7 @@ You then see: To edit or remove a domain: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. On the left sidebar, select **Search or go to** and find your top-level group. 1. Select **Settings > Domain Verification**. 1. When viewing **Domain Verification**, select the project listed next to the relevant domain. 1. Edit or remove a domain following the relevant [GitLab Pages custom domains](../project/pages/custom_domains_ssl_tls_certification/index.md) instructions. @@ -159,7 +159,7 @@ Top-level group Owners can disable two-factor authentication (2FA) for enterpris To disable 2FA: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Find a user with the **Enterprise** and **2FA** badges. 1. Select **More actions** (**{ellipsis_v}**) and select **Disable two-factor authentication**. diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index 0af5c76ade8..c978105c13b 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -25,7 +25,7 @@ Prerequisite: - You must have the Owner role for the group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. To view all members, select the **Seats** tab. 1. To remove a member, select **Remove user**. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 47f6e0ac1d9..09e05538fd7 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -18,7 +18,7 @@ GitLab.com has the: - [`email_confirmation_setting`](../../administration/settings/sign_up_restrictions.md#confirm-user-email) setting set to **Hard**. - [`unconfirmed_users_delete_after_days`](../../administration/moderate_users.md#automatically-delete-unconfirmed-users) - setting set to one day. + setting set to three days. ## Password requirements @@ -82,7 +82,7 @@ The IP addresses for `mg.gitlab.com` are subject to change at any time. On GitLab.com, there's a mailbox configured for Service Desk with the email address: `contact-project+%{key}@incoming.gitlab.com`. To use this mailbox, configure the -[custom suffix](../project/service_desk/index.md#configure-a-suffix-for-service-desk-alias-email) in project +[custom suffix](../project/service_desk/configure.md#configure-a-suffix-for-service-desk-alias-email) in project settings. ## Backups @@ -217,7 +217,7 @@ the default value [is the same as for self-managed instances](../../administrati | Maximum remote file size for imports from external object storages | 10 GB | | Maximum download file size when importing from source GitLab instances by direct transfer | 5 GB | | Maximum attachment size | 100 MB | -| [Maximum decompressed file size for imported archives](../../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives) | 25 GB | +| [Maximum decompressed file size for imported archives](../../administration/settings/import_and_export_settings.md#maximum-decompressed-file-size-for-imported-archives) | 25 GB | If you are near or over the repository size limit, you can either [reduce your repository size with Git](../project/repository/reducing_the_repo_size_using_git.md) @@ -225,7 +225,7 @@ or [purchase additional storage](https://about.gitlab.com/pricing/licensing-faq/ NOTE: `git push` and GitLab project imports are limited to 5 GB per request through -Cloudflare. Git LFS and imports other than a file upload are not affected by +Cloudflare. Imports other than a file upload are not affected by this limit. Repository limits apply to both public and private projects. ## Default import sources @@ -236,7 +236,7 @@ The import sources that are available 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 - [enabled](../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [enabled](../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources). | Import source | GitLab.com default | GitLab self-managed default | |:----------------------------------------------------------------------------------------------------|:-----------------------|:----------------------------| diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 0ccd4512039..428c87143f6 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -46,7 +46,7 @@ configured by an administrator. To change the permitted Git access protocols for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Choose the permitted protocols from **Enabled Git access protocols**. @@ -71,7 +71,7 @@ Administrators can combine restricted access by IP address with To restrict group access by IP address: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. In the **Restrict access by IP address** text box, enter a list of IPv4 or IPv6 @@ -102,6 +102,15 @@ Keep in mind that restricting group access by IP address has the following impli IP access restrictions applied to self-managed instances are possible with [`gitlab-sshd`](../../administration/operations/gitlab_sshd.md) with [PROXY protocol](../../administration/operations/gitlab_sshd.md#proxy-protocol-support) enabled. - IP restriction is not applicable to shared resources belonging to a group. Any shared resource is accessible to a user even if that user is not able to access the group. +- While IP restrictions apply to public projects, they aren't a complete firewall and cached files for a project may still be accessible to users not in the IP block + +### GitLab.com access restrictions + +On GitLab.com shared runners are added to the [global allowlist](../../administration/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges), so that they are available regardless of IP restrictions. + +Artifact and Registry downloading from runners is sourced from any Google or, in the case of MacOS runners, Amazon IP address in that region. +The download is therefore not added to the global allowlist. +To allow runner downloading, add the [outbound runner CIDR ranges](../gitlab_com/index.md#ip-range) to your group allowlist. ## Restrict group access by domain **(PREMIUM ALL)** @@ -113,7 +122,7 @@ You can prevent users with email addresses in specific domains from being added To restrict group access by domain: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. In the **Restrict membership by email** field, enter the domain names. @@ -157,7 +166,7 @@ If you prevent group sharing outside the hierarchy for the **Animals** group: To prevent sharing outside of the group's hierarchy: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Select **Members cannot invite groups outside of `<group_name>` and its subgroups**. @@ -173,7 +182,7 @@ which can be confusing and difficult to control. To restrict the permission to invite project members to a single source, prevent a project from being shared with other groups: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Projects in `<group_name>` cannot be shared with other groups**. @@ -187,7 +196,7 @@ added to a project lose access when the setting is enabled. As a group Owner, you can prevent non-members from requesting access to your group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Clear the **Allow users to request access** checkbox. @@ -207,7 +216,7 @@ If even one is set to `true`, then the group does not allow outside forks. To prevent projects from being forked outside the group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Check **Prevent project forking outside current group**. @@ -232,7 +241,7 @@ The setting does not cascade. Projects in subgroups observe the subgroup configu To prevent members from being added to projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Under **Membership**, select **Users cannot be added to projects in this group**. @@ -254,7 +263,7 @@ For more information on the administration of LDAP and group sync, refer to the NOTE: When you add LDAP synchronization, if an LDAP user is a group member and they are not part of the LDAP group, they are removed from the group. -You can use a workaround to [manage project access through LDAP groups](../project/settings/index.md#manage-project-access-through-ldap-groups). +You can use a workaround to [manage project access through LDAP groups](../project/working_with_projects.md#manage-project-access-through-ldap-groups). ### Create group links via CN **(PREMIUM SELF)** @@ -284,7 +293,7 @@ To create group links via filter: LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Manage > Members**. If LDAP synchronization has granted a user a role with: - More permissions than the parent group membership, that user is displayed as having diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index e41991f365c..5c0844dff92 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -21,7 +21,7 @@ your group, enabling you to use the same cluster across multiple projects. To view your group-level Kubernetes clusters: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Operate > Kubernetes**. ## Cluster management project @@ -89,7 +89,7 @@ your cluster, which can cause deployment jobs to fail. To clear the cache: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Operate > Kubernetes**. 1. Select your cluster. 1. Expand **Advanced settings**. diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 35e8ad27bc3..7258791a983 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -15,7 +15,7 @@ requirements or needs additional oversight. The label can optionally enforce Compliance frameworks are created on top-level groups. Group owners can create, edit, and delete compliance frameworks: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. 1. Create, edit, or delete compliance frameworks. @@ -31,7 +31,7 @@ Prerequisite: To assign a compliance framework to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings** > **General**. 1. Expand **Compliance frameworks**. 1. Select a compliance framework. @@ -66,7 +66,7 @@ A compliance framework that is set to default has a **default** label. Group owners can set a compliance framework as default (or remove the setting): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Compliance frameworks** section and locate the compliance framework to set (or remove) as default. 1. Select the vertical ellipsis (**{ellipsis_v}**) for the compliance frame and then select **Set default** (or @@ -155,7 +155,7 @@ Therefore, communicate with project users about compliance pipeline configuratio To configure a compliance pipeline: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. 1. In **Compliance pipeline configuration (optional)**, add the path to the compliance framework configuration. Use the @@ -165,7 +165,7 @@ To configure a compliance pipeline: - `.compliance-ci.yaml@gitlab-org/gitlab`. This configuration is inherited by projects where the compliance framework label is -[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). In projects with the applied compliance +[applied](../project/working_with_projects.md#add-a-compliance-framework-to-a-project). In projects with the applied compliance framework label, the compliance pipeline configuration is run instead of the labeled project's own pipeline configuration. The user running the pipeline in the labeled project must at least have the Reporter role on the compliance project. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 9716143f5e2..96cc9ce974c 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -20,7 +20,7 @@ Use contribution analytics data visualizations to: To view contribution analytics: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Contribution analytics**. Three bar charts and a table illustrate the number of contributions made by each group member: diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 1a481641111..87c1c548abd 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -40,7 +40,7 @@ Projects in nested subgroups are not included in the template list. ## Which projects are available as templates - Public and internal projects can be selected by any authenticated user as a template for a new project, - if all [project features](../project/settings/index.md#configure-project-visibility-features-and-permissions) + if all [project features](../project/settings/index.md#configure-project-features-and-permissions) except for **GitLab Pages** and **Security and Compliance** are set to **Everyone With Access**. - Private projects can be selected only by users who are members of the projects. @@ -69,6 +69,35 @@ gitlab.com/myorganization/ ... ``` +## What is copied from the templates + +The entire custom instance-level project templates repository is copied, including: + +- Branches +- Commits +- Tags + +If the user: + +- Has the Owner role on the custom instance-level project templates project or is a GitLab administrator, + all project settings are copied over to the new project. +- Doesn't have the Owner role or is not a GitLab administrator, + project deploy keys and project webhooks aren't copied over because they contain sensitive data. + +To learn more about what is migrated, see +[Items that are exported](../project/settings/import_export.md#items-that-are-exported). + +## User assignments in templates + +When you use a template created by another user, any items that were assigned +to a user in the template are reassigned to you. It's important to understand +this reassignment when you configure security features like protected branches +and tags. For example, if the template contains a protected branch: + +- In the template, the branch allows the _template owner_ to merge into the default branch. +- In the project created from the template, the branch allows _you_ to merge into + the default branch. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 852d26f3816..5359d7b52a0 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -36,7 +36,7 @@ Prerequisite: To view DevOps Adoption: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > DevOps adoption** ## DevOps Adoption categories @@ -80,7 +80,7 @@ twelve months. The chart only shows data from when you enabled DevOps Adoption f To view feature adoption over time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > DevOps adoption**. 1. Select the **Overview** tab. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 41231db5964..69b64861bd5 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -25,7 +25,7 @@ On the top of each list, you can see the number of epics in the list (**{epic}** To view an epic board: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Epic boards**.  @@ -38,7 +38,7 @@ Prerequisites: To create a new epic board: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Epic boards**. 1. In the upper-left corner, select the dropdown list with the current board name. 1. Select **Create new board**. @@ -87,7 +87,7 @@ Prerequisites: To create a new list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Epic boards**. 1. In the upper-right corner, select **Create list**. 1. In the **New list** column expand the **Select a label** dropdown list and select the label to use as diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index e6116151012..b79177e1571 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -209,7 +209,7 @@ Prerequisites: To view epics in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Epics**. ### Who can view an epic @@ -254,7 +254,7 @@ You can filter the list of epics by: To filter: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Epics**. 1. Select the field **Search or filter results**. 1. From the dropdown list, select the scope or enter plain text to search by epic title or description. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index b645ea04038..a049b4afcc1 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -30,7 +30,7 @@ If you migrate from GitLab.com to self-managed GitLab, an administrator can crea > - `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/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer). +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). Migrating groups by direct transfer copies the groups from one place to another. You can: @@ -47,7 +47,7 @@ Migrating groups by direct transfer copies the groups from one place to another. Not all group and project resources are copied. See list of copied resources below: - [Migrated group items](#migrated-group-items). -- [Migrated project items](#migrated-project-items-beta). +- [Migrated project items](#migrated-project-items). WARNING: Importing groups with projects is in [Beta](../../../policy/experiment-beta-support.md#beta). This feature is not @@ -157,16 +157,20 @@ To migrate groups by direct transfer: - The network connection between instances or GitLab.com must support HTTPS. - Any firewalls must not block the connection between the source and destination GitLab instances. - Both GitLab instances must have group migration by direct transfer - [enabled in application settings](../../../administration/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) + [enabled in application settings](../../../administration/settings/import_and_export_settings.md#enable-migration-of-groups-and-projects-by-direct-transfer) by an instance administrator. - The source GitLab instance must be running GitLab 14.0 or later. -- You must have a [personal access token](../../../user/profile/personal_access_tokens.md) for the source GitLab - instance: - - For GitLab 15.1 and later source instances, the personal access token must have the `api` scope. - - For GitLab 15.0 and earlier source instances, the personal access token must have both the `api` and - `read_repository` scopes. +- You must have a + [personal access token](../../../user/profile/personal_access_tokens.md) for + the source GitLab instance: + - For GitLab 15.1 and later source instances, the personal access token must + have the `api` scope. + - For GitLab 15.0 and earlier source instances, the personal access token must + have both the `api` and `read_repository` scopes. - You must have the Owner role on the source group to migrate from. -- You must have at least the Maintainer role on the destination group to migrate to. +- Your must have a role on the destination namespace the enables you to + [create a subgroup](../../group/subgroups/index.md#create-a-subgroup) in that + namespace. ### Prepare user accounts @@ -287,7 +291,7 @@ 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. @@ -460,7 +464,7 @@ To solve this, you must change the source group path to include a non-numerical - The GitLab UI: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. Under **Change group URL**, change the group URL to include non-numeric characters. @@ -593,7 +597,7 @@ Prerequisite: To enable import and export for a group: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. @@ -607,7 +611,7 @@ Prerequisites: To export the contents of a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your 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) diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 13fba43f8ef..484fd8c533b 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -49,14 +49,14 @@ the immediate parent group. To explore all public groups: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your groups**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my groups**. 1. At the top right, select **Explore groups**. To view groups where you have a direct or indirect membership: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your groups**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my groups**. This page shows groups that you are a member of: @@ -67,7 +67,7 @@ This page shows groups that you are a member of: To view the activity of a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Activity**. 1. Optional. To filter activity by contribution type, select a tab: @@ -106,7 +106,7 @@ For details about groups, watch [GitLab Namespaces (users, groups and subgroups) To remove a group and its contents: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Remove group** section, select **Remove group**. @@ -115,8 +115,8 @@ To remove a group and its contents: A group can also be removed from the groups dashboard: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your groups**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my groups**. 1. Select (**{ellipsis_v}**) for the group you want to delete. 1. Select **Delete**. 1. In the Remove group section, select **Remove group**. @@ -143,7 +143,7 @@ Prerequisites: To immediately remove a group marked for deletion: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the "Permanently remove group" section, select **Remove group**. @@ -158,7 +158,7 @@ are deleted. To restore a group that is marked for deletion: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. In the Restore group section, select **Restore group**. @@ -167,10 +167,12 @@ To restore a group that is marked for deletion: As a user, you can request to be a member of a group, if an administrator allows it. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your groups**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my groups**. 1. At the top right side, select **Explore groups**. -1. Under the group name, select **Request Access**. +1. Search for the group by name. +1. In the search results, select the name of the group. +1. On the group page, under the group name, select **Request Access**. As many as ten of the most-recently-active group owners receive an email with your request. Any group owner can approve or decline the request. @@ -182,7 +184,7 @@ If you change your mind before your request is approved, select To view a group's members: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. A table displays the member's: @@ -219,7 +221,7 @@ In lists of group members, entries can display the following badges: - **SAML**, to indicate the member has a [SAML account](saml_sso/index.md) connected to them. - **Enterprise**, to indicate that the member is an [enterprise user](../enterprise_user/index.md). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Above the list of members, in the **Filter members** box, enter filter criteria. - To view members in the group only, select **Membership = Direct**. @@ -231,7 +233,7 @@ In lists of group members, entries can display the following badges: You can search for members by name, username, or [public email](../profile/index.md#set-your-public-email). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Above the list of members, in the **Filter members** box, enter search criteria. 1. To the right of the **Filter members** box, select the magnifying glass (**{search}**). @@ -240,7 +242,7 @@ You can search for members by name, username, or [public email](../profile/index You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in**. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Above the list of members, in the upper-right corner, from the **Account** list, select the criteria to filter by. @@ -257,7 +259,7 @@ Prerequisite: - You must have the Owner role. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Select **Invite members**. 1. Fill in the fields. @@ -287,7 +289,7 @@ Prerequisites: To remove a member from a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Next to the member you want to remove, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Remove member**. @@ -325,7 +327,7 @@ By default, users with: To change the role that can create projects under a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select the desired option in the **Roles allowed to create projects** dropdown list. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 5cb982a85e4..2ded1b08de2 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -23,7 +23,7 @@ Prerequisites: To access your group's insights: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Insights**. ## Interact with insights charts @@ -65,7 +65,7 @@ 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, at the top, select **Search GitLab** (**{search}**) to find 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. diff --git a/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png b/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png Binary files differnew file mode 100644 index 00000000000..5e1fe4eaa8c --- /dev/null +++ b/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 46ba1747b06..4f1c7b4be7a 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Plan -group: Project Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -15,9 +15,11 @@ prior. To access the chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, 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. + 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 @@ -36,6 +38,20 @@ 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 group 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. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 91e69f3a02d..8c0838cf33c 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -50,7 +50,7 @@ Prerequisites: To create an iteration cadence: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Iterations**. 1. Select **New iteration cadence**. 1. Enter the title and description of the iteration cadence. @@ -70,7 +70,7 @@ If you want to manually manage the created cadence, read [Manual Iteration Manag ### View the iterations list -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Iterations**. To view all the iterations in a cadence, ordered by descending date, select that iteration cadence. @@ -78,7 +78,7 @@ From there you can create a new iteration or select an iteration to get a more d NOTE: If a project has issue tracking -[turned off](../../project/settings/index.md#configure-project-visibility-features-and-permissions), +[turned off](../../project/settings/index.md#configure-project-features-and-permissions), to view the iterations list, enter its URL. To do so, add: `/-/cadences` to your project or group URL. For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences`. This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). @@ -91,7 +91,7 @@ Prerequisites: To edit an iteration cadence: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Iterations**. 1. Select **Edit iteration cadence**. @@ -105,7 +105,7 @@ doesn't delete the eight existing upcoming iterations. #### Turn on and off automatic scheduling for an iteration cadence -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Iterations**. 1. Next to the cadence for which you want to turn on or off automatic scheduling, select the three-dot menu (**{ellipsis_v}**) **> Edit cadence**. @@ -157,7 +157,7 @@ Deleting an iteration cadence also deletes all iterations within that cadence. To delete an iteration cadence: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Iterations**. 1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. 1. Select **Delete cadence**. @@ -178,7 +178,7 @@ Prerequisites: To create an iteration: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Plan > Iterations** and select an iteration cadence. 1. Select **New iteration**. 1. Enter the title, a description (optional), a start date, and a due date. @@ -277,7 +277,7 @@ and get a more accurate understanding of scope attributable to each label. To group issues by label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Iterations**. 1. In the **Group by** dropdown list, select **Label**. 1. Select the **Filter by label** dropdown list. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 743aabd8f4b..65190847b05 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -29,7 +29,7 @@ Prerequisite: To add a group README: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. In the **Group README** section, select **Add README**. This action creates a new project `gitlab-profile` that contains the `README.md` file. 1. On the prompt for creating a README, select **Create and add README**. You're redirected to the Web IDE, where a README file is created. @@ -41,12 +41,12 @@ You can change the owner of a group. Each group must always have at least one member with the Owner role. - As an administrator: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Give a different member the **Owner** role. 1. Refresh the page. You can now remove the **Owner** role from the original owner. - As the current group's owner: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Give a different member the **Owner** role. 1. Have the new owner sign in and remove the **Owner** role from you. @@ -72,7 +72,7 @@ create a new group and transfer projects to it instead. To change your group path (group URL): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Under **Change group URL**, enter a new name. @@ -130,14 +130,15 @@ After sharing the `Frontend` group with the `Engineering` group: - The **Groups** tab lists the `Engineering` group. - The **Groups** tab lists a group regardless of whether it is a public or private group. -- All direct members of the `Engineering` group have access to the `Frontend` group. Direct members of `Engineering` that gain access to the `Frontend` group keep their same access level as in `Engineering`, but up to the maximum access level selected when sharing the group. Inherited members of the `Engineering` group do not gain access to the `Frontend` group. +- All direct members of the `Engineering` group have access to the `Frontend` group. Direct members of `Engineering` that gain access to the `Frontend` group keep their same access level as in `Engineering`, but up to the maximum access level selected when sharing the group. +- Inherited members of the `Engineering` group do not gain access to the `Frontend` group. - Direct members of the `Engineering` group who have the **Group Invite** badge next to their profile on the group's usage quota page count towards the billable members of the `Frontend` group. ## Remove a shared group To unshare a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Select the **Groups** tab. 1. To the right of the account you want to remove, select **Remove group** (**{remove}**). @@ -174,7 +175,7 @@ When transferring groups, note: To transfer a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Remove group** section, select **Transfer group**. @@ -189,7 +190,7 @@ You can disable all email notifications related to the group, which includes its To disable email notifications: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Email notifications are disabled**. @@ -209,7 +210,7 @@ This is particularly helpful for groups with a large number of users. To disable group mentions: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Group mentions are disabled**. @@ -222,7 +223,7 @@ To disable group mentions: You can export a list of members in a group or subgroup as a CSV. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group or subgroup. +1. On the left sidebar, select **Search or go to** and find your group or subgroup. 1. On the left sidebar, **Manage > Members**. 1. Select **Export as CSV**. 1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -252,7 +253,7 @@ Prerequisite: To specify a user cap: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. You can set a cap on the top-level group only. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. @@ -274,7 +275,7 @@ Prerequisite: To remove the user cap: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. In the **User cap** box, delete the value. @@ -295,7 +296,7 @@ Prerequisite: To approve members that are pending because they've exceeded the user cap: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. On the **Seats** tab, under the alert, select **View pending approvals**. 1. For each member you want to approve, select **Approve**. @@ -336,7 +337,7 @@ For more information, see [group-level project templates](custom_project_templat To enable group file templates: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Templates** section. 1. Choose a project to act as the template repository. @@ -369,7 +370,7 @@ Prerequisites: To enable this setting: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Merge requests**. 1. Under **Merge checks**, select **Pipelines must succeed**. @@ -388,7 +389,7 @@ Prerequisite: To change this behavior: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Merge requests**. 1. Under **Merge checks**: @@ -407,7 +408,7 @@ Prerequisite: To enable this setting: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Merge requests**. 1. Under **Merge checks**, select **All threads must be resolved**. @@ -425,7 +426,7 @@ that belong to the group. To view the merge request approval settings for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Merge request approvals** section. 1. Select the settings you want. @@ -443,19 +444,19 @@ for the ability to set merge request approval rules for groups is tracked in WARNING: This feature is in [Beta](../../policy/experiment-beta-support.md#beta). -Beta users should read about the [known limitations](../project/repository/code_suggestions.md#known-limitations). -We look forward to hearing your [feedback](../project/repository/code_suggestions.md#feedback). +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.md). +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. - Each user can - [enable or disable Code Suggestions for themselves](../project/repository/code_suggestions.md#enable-code-suggestions-for-an-individual-user). + [Enable Code Suggestions](../../user/profile/preferences.md#enable-code-suggestions). To enable Code Suggestions for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Code Suggestions**, select the **Projects in this group can use Code Suggestions** checkbox. @@ -476,7 +477,7 @@ that belong to the group. To enable Experiment features for a top-level group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Experiment features**, select the **Use Experiment features** checkbox. @@ -496,7 +497,7 @@ that belong to the group. To disable third-party AI features for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Third-party AI services**, uncheck the **Use third-party AI services** checkbox. @@ -521,7 +522,7 @@ Changes to [group wikis](../project/wiki/group.md) do not appear in group activi You can view the most recent actions taken in a group, either in your browser or in an RSS feed: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Manage > Activity**. To view the activity feed in Atom format, select the diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md index 7e67bb6ddb5..6859125b323 100644 --- a/doc/user/group/moderate_users.md +++ b/doc/user/group/moderate_users.md @@ -1,5 +1,5 @@ --- -stage: Anti-Abuse +stage: Govern group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index abb967ad8b1..1b14edb04d9 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -1,5 +1,5 @@ --- -stage: Anti-Abuse +stage: Govern group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 3e7bacbb817..6f02b27a214 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -37,7 +37,7 @@ The **Analyze > Repository analytics** group page displays the average test cove To see the latest code coverage for each project in your group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Repository analytics**. 1. In the **Latest test coverage results** section, from the **Select projects** dropdown list, choose the projects you want to check. @@ -52,7 +52,7 @@ You can get a CSV of the code coverage data for all of the projects in your grou To get the report: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Repository analytics**. 1. Select **Download historic test coverage data (.csv)**. 1. Select the projects and date range you want to include in the report. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index c5f84510c57..70e01e1d9a9 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index c3edc01fe74..335c989c85f 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -155,10 +155,11 @@ To integrate Microsoft Azure AD, you: To configure for a GitLab.com group: -1. Configure [SAML SSO for the group](../../../user/group/saml_sso/index.md). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. On the left sidebar, select **Search or go to** and find your top-level group. 1. Select **Settings > SAML SSO**. +1. Configure [SAML SSO for the group](../../../user/group/saml_sso/index.md). 1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. + This section will only be visible if SAML SSO is configured and enabled for the group. 1. Enter the **Tenant ID**, **Client ID**, and **Client secret** obtained earlier when configuring Azure Active Directory in the Azure Portal. 1. Optional. If using Azure AD for US Government or Azure AD China, enter the appropriate **Login API endpoint** and **Graph API endpoint**. The default values work for most organizations. 1. Select **Save changes**. @@ -166,7 +167,7 @@ To configure for a GitLab.com group: To configure for self-managed: 1. Configure [SAML SSO for the instance](../../../integration/saml.md). -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. @@ -197,7 +198,7 @@ When global group memberships lock is enabled: To enable global group memberships lock: 1. [Configure SAML](../../../integration/saml.md) for your self-managed GitLab instance. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 41c2090f4bc..734679cf331 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -38,7 +38,7 @@ If you are having issues setting up your identity provider, see the To set up SSO with Azure as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Go to Azure and [follow the instructions for configuring SSO for an application](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso). The following GitLab settings correspond to the Azure fields. @@ -71,7 +71,7 @@ For more information, see an [example configuration page](example_saml_config.md To set up Google Workspace as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Follow the instructions for [setting up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en). The following GitLab settings correspond to the Google Workspace fields. @@ -115,7 +115,7 @@ View a demo of [how to configure SAML with Google Workspaces and set up Group Sy To set up SSO with Okta as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Follow the instructions for [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/). @@ -152,7 +152,7 @@ OneLogin supports its own [GitLab (SaaS) application](https://onelogin.service-n To set up OneLogin as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. If you use the OneLogin generic @@ -179,7 +179,7 @@ To set up OneLogin as your identity provider: To configure some identity providers, you need a GitLab metadata URL. To find this URL: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. 1. Follow your identity provider's documentation and paste the metadata URL when it's requested. @@ -217,7 +217,7 @@ If the **NameID** is configured with the email address, [change the **NameID** f After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Complete the fields: - In the **Identity provider single sign-on URL** field, enter the SSO URL from your identity provider. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 9096824cc2c..a9b9bf26444 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -10,12 +10,14 @@ You can use the open standard System for Cross-domain Identity Management (SCIM) - Create users. - Remove users (deactivate SCIM identity). +- Re-add users (reactivate SCIM identity). GitLab SAML SSO SCIM doesn't support updating users. When SCIM is enabled for a GitLab group, membership of that group is synchronized between GitLab and an identity provider. The [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). +Identity providers can use the [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) to develop a SCIM app. ## Configure GitLab @@ -25,7 +27,7 @@ Prerequisites: To configure GitLab SAML SSO SCIM: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Select **Generate a SCIM token**. 1. For configuration of your identity provider, save the: @@ -40,7 +42,7 @@ You can configure one of the following as an identity provider: - [Okta](#configure-okta). NOTE: -Other providers can work with GitLab but they have not been tested and are not supported. +Other providers can work with GitLab but they have not been tested and are not supported. You should contact the provider for support. GitLab support can assist by reviewing related log entries. ### Configure Azure Active Directory @@ -165,7 +167,8 @@ To configure Okta for SCIM: During the synchronization process, all new users: - Receive GitLab accounts. -- Are welcomed to their groups with an invitation email. You may want to warn your employees to expect this email. +- Are welcomed to their groups with an invitation email. + You can [bypass email confirmation with a verified domain](index.md#bypass-user-email-confirmation-with-verified-domains). The following diagram describes what happens when you add users to your SCIM app: @@ -216,10 +219,11 @@ Remove or deactivate a user on the identity provider to remove their access to: - The top-level group. - All subgroups and projects. -After the identity provider performs a sync based on its configured schedule, the user's membership is revoked and they -lose access. +After the identity provider performs a sync based on its configured schedule, +the user's membership is revoked and they lose access. -When you enable SCIM, this does not automatically remove existing users who do not have a SAML identity. +When you enable SCIM, this does not automatically remove existing users who do +not have a SAML identity. NOTE: Deprovisioning does not delete the GitLab user account. @@ -230,3 +234,14 @@ graph TD B -->|No| C[Nothing to do] B -->|Yes| D[GitLab removes user from GitLab group] ``` + +### Reactivate access + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379149) in GitLab 16.0 [with a flag](../../feature_flags.md) named `skip_saml_identity_destroy_during_scim_deprovision`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121226) in GitLab 16.4. Feature flag `skip_saml_identity_destroy_during_scim_deprovision` removed. + +After a user is removed or deactivated through SCIM, you can reactivate that user by +adding them to the SCIM identity provider. + +After the identity provider performs a sync based on its configured schedule, +the user's SCIM identity is reactivated and their group memberships are restored. diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index 82703893834..cf9b9f5d4eb 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -1,6 +1,6 @@ --- type: reference -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -217,6 +217,18 @@ to [reset their password](https://gitlab.com/users/password/new) if both: - The account was provisioned by SCIM. - They are signing in with username and password for the first time. +### Message: "SAML Name ID and email address do not match your user account" **(PREMIUM SAAS)** + +Users might get an error that states "SAML Name ID and email address do not match your user account. Contact an administrator." +This means: + +- The NameID value sent by SAML does not match the existing SAML identity `extern_uid` value. +- Either the SAML response did not include an email address or the email address did not match the user's GitLab email address. + +The workaround is that a GitLab group Owner uses the [SAML API](../../../api/saml.md) to update the user's SAML `extern_uid`. +The `extern_uid` value must match the Name ID value sent by the SAML identity provider (IdP). Depending on the IdP configuration +this may be a generated unique ID, an email address, or other value. + ## Other user sign in issues ### Verify `NameID` @@ -254,12 +266,24 @@ If all users are receiving a `404` after signing in to the identity provider (Id - In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). - As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. -- Verify if the `404` is related to [the user having too many groups assigned to them in their Azure IdP](group_sync.md#user-that-belongs-to-many-saml-groups-automatically-removed-from-gitlab-group) by checking: +- Verify if the `404` is related to [the user having too many groups assigned to them in their Azure IdP](group_sync.md#user-that-belongs-to-many-saml-groups-automatically-removed-from-gitlab-group). + +If a subset of users are receiving a `404` after signing in to the IdP, first verify audit events if the user gets added to the group and then immediately removed. Alternatively, if the user can successfully sign in, but they do not show as [a member of the top-level group](../index.md#search-a-group): - - If the user has group links configured. - - Audit events if the user gets added to the group and then immediately removed. +- Ensure the user has been [added to the SAML identity provider](index.md#user-access-and-management), and [SCIM](scim_setup.md) if configured. +- Ensure the user's SCIM identity's `active` attribute is `true` using the [SCIM API](../../../api/scim.md). + If the `active` attribute is `false`, you can do one of the following to possibly resolve the issue: -For configuration examples for some of the common providers, see the [example group SAML and SCIM configurations](example_saml_config.md). + - Trigger a sync for the user in the SCIM identity provider. For example, Azure has a "Provision on demand" option. + - Remove and re-add the user in the SCIM identity provider. + - Have the user [unlink their account](index.md#unlink-accounts) if possible, then [link their account](index.md#link-saml-to-your-existing-gitlabcom-account). + - Use the [internal SCIM API](../../../development/internal_api/index.md#update-a-single-scim-provisioned-user) to update the user's SCIM identity using your group's SCIM token. + If you do not know your group's SCIM token, reset the token and update the SCIM identity provider app with the new token. + Example request: + + ```plaintext + curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }' + ``` ### 500 error after login **(FREE SELF)** @@ -283,6 +307,21 @@ Make sure the ACS URL points to `https://gitlab.example.com/users/auth/saml/call If the ACS URL is correct, and you still have errors, review the other Troubleshooting sections. +#### 422 error with non-allowed email + +You might get an 422 error that states "Email is not allowed for sign-up. Please use your regular email address." + +This message might indicate that you must add or remove a domain from your domain allowlist or denylist settings. + +To implement this workaround: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. Select **Settings** > **General**. +1. Expand **Sign-up restrictions**. +1. Add or remove a domain as appropriate to **Allowed domains for sign-ups** and **Denied domains for sign-ups**. +1. Select **Save changes**. + ### User is blocked when signing in through SAML **(FREE SELF)** The following are the most likely reasons that a user is blocked when signing in through SAML: @@ -298,18 +337,6 @@ Pay particular attention to the following 403 errors: - `app_not_configured` - `app_not_configured_for_user` -## SAML Name ID and email address do not match your user account **(PREMIUM SAAS)** - -If users encounter the error `SAML Name ID and email address do not match your user account. Contact an administrator.` -this means: - -- The NameID value sent by SAML does not match the existing SAML identity `extern_uid` value. -- Either the SAML response did not include an email address or the email address did not match the user's GitLab email address. - -A GitLab group Owner can use the [SAML API](../../../api/saml.md) to update the user's SAML `extern_uid`. -The `extern_uid` value must match the Name ID value sent by the SAML identity provider (IdP). Depending on the IdP configuration -this may be a generated unique ID, an email address, or other value. - ## Message: "The member's email address is not linked to a SAML account" **(PREMIUM SAAS)** This error appears when you try to invite a user to a GitLab.com group (or subgroup or project within a group) that has [SAML SSO enforcement](index.md#sso-enforcement) enabled. @@ -318,3 +345,6 @@ If you see this message after trying to invite a user to a group: 1. Ensure the user has been [added to the SAML identity provider](index.md#user-access-and-management). 1. Ask the user to [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account), if they have one. Otherwise, ask the user to create a GitLab.com account by [accessing GitLab.com through the identity provider's dashboard](index.md#user-access-and-management), or by [signing up manually](https://gitlab.com/users/sign_up) and linking SAML to their new account. +1. Ensure the user is a [member of the top-level group](../index.md#search-a-group). + +Additionally, see [troubleshooting users receiving a 404 after sign in](#users-receive-a-404). diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 7d2aa8faa99..63d10f3e932 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -13,7 +13,18 @@ This section contains possible solutions for problems you might encounter. When you remove a user, they are removed from the group but their account is not deleted (see [remove access](scim_setup.md#remove-access)). -When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists. +When the user is added back to the SCIM app, GitLab does not create a new user because the user already exists. + +From August 11, 2023, the `skip_saml_identity_destroy_during_scim_deprovision` feature flag is enabled. + +For a user de-provisioned by SCIM from that date, their SAML identity is not removed. + +When that user is added back to the SCIM app: + +- Their SCIM identity `active` attribute is set to `true`. +- They can sign in using SSO. + +For users de-provisioned by SCIM before that date, their SAML identity is destroyed. To solve this problem: diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 76aa77d026b..795967e9f91 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -1,11 +1,11 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, howto --- -# Group access tokens +# Group access tokens **(FREE)** With group access tokens, you can use a single token to: @@ -57,7 +57,7 @@ all projects that have visibility level set to [Internal](../../public_access.md To create a group access token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the group. 1. Enter an expiry date for the token: @@ -119,7 +119,7 @@ or API. However, administrators can use a workaround: To revoke a group access token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Access Tokens**. 1. Next to the group access token to revoke, select **Revoke**. @@ -138,6 +138,8 @@ token.revoke! ## Scopes for a group access token +> `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default. + The scope determines the actions you can perform when you authenticate with a group access token. | Scope | Description | @@ -149,12 +151,14 @@ The scope determines the actions you can perform when you authenticate with a gr | `read_repository` | Grants read access (pull) to all repositories within a group. | | `write_repository` | Grants read and write access (pull and push) to all repositories within a group. | | `create_runner` | Grants permission to create runners in a group. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in a group. | ## Enable or disable group access token creation To enable or disable group access token creation for all subgroups in a top-level group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Users can create project access tokens and group access tokens in this group**. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 4fb8b293334..e9064ff72a6 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -56,7 +56,7 @@ the private subgroup. To view the subgroups of a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select the **Subgroups and projects** tab. 1. To view a nested subgroup, expand a subgroup in the hierarchy list. @@ -77,14 +77,14 @@ Prerequisites: - At least the Maintainer role for a group to create subgroups for it. - The [role determined by a setting](#change-who-can-create-subgroups). These users can create subgroups even if group creation is - [disabled by an Administrator](../../../administration/admin_area.md#prevent-a-user-from-creating-groups) in the user's settings. + [disabled by an Administrator](../../../administration/admin_area.md#prevent-a-user-from-creating-top-level-groups) in the user's settings. NOTE: You cannot host a GitLab Pages subgroup website with a top-level domain name. For example, `subgroupname.example.io`. To create a subgroup: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a parent group for the subgroup. +1. On the left sidebar, select **Search or go to** and find a parent group for the subgroup. 1. On the parent group's overview page, in the upper-right corner, select **New subgroup**. 1. Select **Create group**. 1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. @@ -99,13 +99,13 @@ Prerequisite: To change who can create subgroups on a group: - As a user with the Owner role on the group: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Select a role from **Roles allowed to create subgroups**. 1. Select **Save changes**. - As an administrator: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Groups**. 1. In the group's row select **Edit**. @@ -161,7 +161,7 @@ Group permissions for a member can be changed only by: To see if a member has inherited the permissions from a parent group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. Members list for an example subgroup _Four_: diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 1e042ab1924..0d91416dfa5 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -212,7 +212,7 @@ Prerequisites: To view value stream analytics for your group or project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value stream analytics**. 1. To view metrics for a particular stage, select a stage below the **Filter results** text box. 1. Optional. Filter the results: @@ -302,7 +302,7 @@ Prerequisite: To view lifecycle metrics: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value stream analytics**. Lifecycle metrics display below the **Filter results** text box. 1. Optional. Filter the results: @@ -316,7 +316,7 @@ To view lifecycle metrics: To view the [Value Streams Dashboard](../../analytics/value_streams_dashboard.md) and [DORA metrics](../../analytics/dora_metrics.md): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value stream analytics**. 1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. 1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL @@ -331,7 +331,7 @@ Value stream analytics shows the median time spent by issues or merge requests i To view the median time spent in each stage by a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value stream analytics**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -355,7 +355,7 @@ group and time frame. To view tasks by type: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Value stream analytics**. 1. Below the **Filter results** text box, select **Overview**. The **Tasks by type** chart displays below the **Total time** chart. 1. To switch between the task type, select the **Settings** (**{settings}**) dropdown list @@ -372,7 +372,7 @@ To view tasks by type: When you create a value stream, you can use GitLab default stages and hide or re-order them. You can also create custom stages in addition to those provided in the default template. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value Stream analytics**. 1. Select **Create new Value Stream**. 1. Enter a name for the value stream. @@ -396,7 +396,7 @@ If you have recently upgraded to GitLab Premium, it can take up to 30 minutes fo When you create a value stream, you can create and add custom stages that align with your own development workflows. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value Stream analytics**. 1. Select **Create value stream**. 1. For each stage: @@ -430,7 +430,7 @@ The first value stream uses standard timestamp-based events for defining the sta After you create a value stream, you can customize it to suit your purposes. To edit a value stream: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value Stream analytics**. 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**. @@ -449,7 +449,7 @@ After you create a value stream, you can customize it to suit your purposes. To To delete a custom value stream: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. In the upper-right corner, select the dropdown list, then select the value stream you would like to delete. 1. Select **Delete (name of value stream)**. 1. To confirm, select **Delete**. @@ -464,7 +464,7 @@ To delete a custom value stream: The **Total time chart** shows the average number of days it takes for development cycles to complete. The chart shows data for the last 500 workflow items. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Analyze > Value stream analytics**. 1. Above the **Filter results** box, select a stage: - To view a summary of the cycle time for all stages, select **Overview**. diff --git a/doc/user/img/enable_AI_ML_features.png b/doc/user/img/enable_AI_ML_features.png Binary files differnew file mode 100644 index 00000000000..577fb367e4d --- /dev/null +++ b/doc/user/img/enable_AI_ML_features.png diff --git a/doc/user/img/forecast_deployment_frequency.png b/doc/user/img/forecast_deployment_frequency.png Binary files differnew file mode 100644 index 00000000000..4c8c6f47a08 --- /dev/null +++ b/doc/user/img/forecast_deployment_frequency.png diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 5010c2e92a3..961914aac9c 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -34,17 +34,17 @@ your cluster's level. **Project-level clusters:** -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Kubernetes clusters**. **Group-level clusters:** -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Operate > Kubernetes clusters**. **Instance-level clusters:** -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Kubernetes**. diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index 91429e203f3..de35b21c8b6 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -35,8 +35,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. In GitLab, on the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**.. +1. In GitLab, on the left sidebar, select **Search or go to**. +1. Select **View all my projects**.. 1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index ef51db097d9..4ec28a7c3c6 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -34,8 +34,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. In GitLab, on the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. In GitLab, on the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 3d717e0f473..96819860a2f 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -41,8 +41,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. In GitLab, on the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. In GitLab, on the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index ad587154021..cace9c66fcf 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -13,9 +13,9 @@ To connect clusters to GitLab, use the [GitLab agent](../../clusters/agent/index WARNING: In GitLab 14.5, the certificate-based method to connect Kubernetes clusters to GitLab was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8), -as well as its related [features](#deprecated-features). In self-managed GitLab 15.0 and later, +as well as its related [features](#deprecated-features). In self-managed GitLab 17.0 and later, this feature is disabled by default. For GitLab SaaS users, this feature is available until -GitLab 15.6 for users who have at least one certificate-based cluster enabled in their namespace hierarchy. +GitLab 15.9 for users who have at least one certificate-based cluster enabled in their namespace hierarchy. For GitLab SaaS users that never used this feature previously, it is no longer available. The certificate-based Kubernetes integration with GitLab is deprecated. @@ -54,12 +54,9 @@ This feature flag re-enables the certificate-based Kubernetes integration. - [GitLab-managed clusters](../../project/clusters/gitlab_managed_clusters.md) - [Deploy applications through certificate-based connection](../../project/clusters/deploy_to_cluster.md) - [Cluster Management Project](../../clusters/management_project.md) -- [Cluster integrations](../../clusters/integrations.md) -- [Cluster cost management](../../clusters/cost_management.md) - [Cluster environments](../../clusters/environments.md) - [Show Canary Ingress deployments on deploy boards](../../project/canary_deployments.md#show-canary-ingress-deployments-on-deploy-boards-deprecated) - [Deploy Boards](../../project/deploy_boards.md) -- [Clusters health](manage/clusters_health.md) - [Web terminals](../../../administration/integration/terminal.md) ### Cluster levels diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md deleted file mode 100644 index cf1b5585a0c..00000000000 --- a/doc/user/infrastructure/clusters/manage/clusters_health.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Deploy -group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../index.md' ---- - -# Clusters health (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index 193e3b70fba..ac61c0c11b4 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -90,7 +90,7 @@ After you have successfully installed Vault, you must and obtain the initial root token. You need access to your Kubernetes cluster that Vault has been deployed into to do this. To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done -by using the `kubectl` command line tool). After you have a shell into the pod, +by using the `kubectl` command-line tool). After you have a shell into the pod, run the `vault operator init` command: ```shell diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 26b4b66ac63..25605cdac62 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -64,7 +64,7 @@ In each GitLab major release (for example, 15.0), the latest templates replace t To use a Terraform template: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project you want to integrate with Terraform. +1. On the left sidebar, select **Search or go to** and find your project you want to integrate with Terraform. 1. Select **Code > Repository**. 1. Edit your `.gitlab-ci.yml` file, use the `include` attribute to fetch the Terraform template: diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 4a8f2f11e58..081e20b158e 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -116,7 +116,7 @@ inconsistent. Instead, use a remote storage resource. [initialized for CI/CD](#initialize-a-terraform-state-as-a-backend-by-using-gitlab-cicd). 1. Copy a pre-populated Terraform `init` command: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Terraform states**. 1. Next to the environment you want to use, select **Actions** (**{ellipsis_v}**) and select **Copy Terraform init command**. @@ -294,7 +294,7 @@ To read the Terraform state in the target project, you need at least the Develop To view Terraform state files: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Terraform states**. [An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/4563) to track improvements to this UI. diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 15a3703adbf..5787051a2c2 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -21,7 +21,7 @@ projects. To view the instance level Kubernetes clusters: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Kubernetes**. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index c724ae465b8..c996b29c9a2 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -691,11 +691,6 @@ To update the rendered references if the assignee, milestone, or health status c edit the comment or description and save it. For more information, see issue [420807](https://gitlab.com/gitlab-org/gitlab/-/issues/420807). -### Embedding metrics - -Metric charts can be embedded in GitLab Flavored Markdown. Read -[Embedding Metrics in GitLab flavored Markdown](../operations/metrics/embed.md) for more details. - ### Embedding Observability dashboards You can embed GitLab Observability UI dashboards descriptions and comments, for example in epics, issues, and MRs. diff --git a/doc/user/okrs.md b/doc/user/okrs.md index f9c242e7c2a..bb58dcf516b 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -60,7 +60,7 @@ Prerequisites: To create an objective: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Plan > Issues**. 1. In the upper-right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. 1. Select **New objective** again. @@ -77,7 +77,7 @@ Prerequisites: To view an objective: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = objective`. @@ -91,7 +91,7 @@ Prerequisites: To view a key result: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = key_result`. @@ -246,7 +246,7 @@ To refer to an objective or key result elsewhere in GitLab, you can use its full To copy the objective or key result reference to your clipboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. @@ -266,7 +266,7 @@ For more information about creating comments by sending an email and the necessa To copy the objective's or key result's email address: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 3f86e945492..3364d927a9b 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -11,7 +11,7 @@ including pipeline and alert status. To access the dashboard: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Select **Operations**. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 0fcc44e8780..3c80e739465 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Composer packages in the Package Registry **(FREE ALL)** +# Composer packages in the Package Registry **(FREE ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab 13.2. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -280,21 +280,53 @@ To install a package: composer req <package-name>:<package-version> ``` - If successful, you should see output indicating that the package installed successfully. - - You can also install from source (by pulling the Git repository directly) using the - `--prefer-source` option: - - ```shell - composer update --prefer-source - ``` - WARNING: Never commit the `auth.json` file to your repository. To install packages from a CI/CD job, consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your access token stored in a [GitLab CI/CD variable](../../../ci/variables/index.md) or in [HashiCorp Vault](../../../ci/secrets/index.md). +### Install from source + +You can install from source by pulling the Git repository directly. To do so, either: + +- Use the `--prefer-source` option: + + ```shell + composer update --prefer-source + ``` + +- In the `composer.json`, use the [`preferred-install` field under the `config` key](https://getcomposer.org/doc/06-config.md#preferred-install): + + ```json + { + ... + "config": { + "preferred-install": { + "<package name>": "source" + } + } + ... + } + ``` + +#### SSH access + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119739) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `composer_use_ssh_source_urls`. 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 `composer_use_ssh_source_urls`. + +When you install from source, the `composer` configures an +access to the project's Git repository. +Depending on the project visibility, the access type is different: + +- On public projects, the `https` Git URL is used. Make sure you can [clone the repository with HTTPS](../../../gitlab-basics/start-using-git.md#clone-with-https). +- On internal or private projects, the `ssh` Git URL is used. Make sure you can [clone the repository with SSH](../../../gitlab-basics/start-using-git.md#clone-with-ssh). + +You can access the `ssh` Git URL from a CI/CD job using [SSH keys with GitLab CI/CD](../../../ci/ssh_keys/index.md). + ### Working with Deploy Tokens Although Composer packages are accessed at the group level, a group or project deploy token can be diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 72c5a1980b5..74152515198 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Conan packages in the Package Registry **(FREE ALL)** +# Conan packages in the Package Registry **(FREE ALL EXPERIMENT)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab 12.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. 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 88a318d0770..0b91a9453a7 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -32,7 +32,7 @@ The online garbage collector is an instance-wide feature, and applies to all nam To delete container images using the GitLab UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: - A group, select **Operate > Container Registry**. - A project, select **Deploy > Container Registry**. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 3ec5ddb235e..1f95d2f9403 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -21,7 +21,7 @@ rate limits and speed up your pipelines. For more information about the Docker R You can view the Container Registry for a project or group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: - A group, select **Operate > Container Registry**. - A project, select **Deploy > Container Registry**. @@ -38,7 +38,7 @@ If a project is public, the Container Registry is also public. You can use the Container Registry **Tag Details** page to view a list of tags associated with a given container image: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: - A group, select **Operate > Container Registry**. - A project, select **Deploy > Container Registry**. @@ -54,7 +54,7 @@ tags on this page. You can share a filtered view by copying the URL from your br To download and run a container image hosted in the Container Registry: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: - A group, select **Operate > Container Registry**. - A project, select **Deploy > Container Registry**. @@ -115,7 +115,7 @@ The Container Registry is enabled by default. You can, however, remove the Container Registry for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand the **Visibility, project features, permissions** section and disable **Container Registry**. @@ -133,7 +133,7 @@ You can, however, change the visibility of the Container Registry for a project. For more information about the permissions that this setting grants to users, see [Container Registry visibility permissions](#container-registry-visibility-permissions). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand the section **Visibility, project features, permissions**. 1. Under **Container Registry**, select an option from the dropdown list: 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 fd781847855..2af16dcc85a 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -229,7 +229,7 @@ For self-managed instances, those settings can be updated in the [Rails console] They are also available in the [administrator area](../../admin_area/index.md): -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > CI/CD** 1. Expand **Container Registry**. diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md index 34c86a90d49..13e14dfdeb4 100644 --- a/doc/user/packages/container_registry/troubleshoot_container_registry.md +++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md @@ -91,7 +91,7 @@ The following procedure uses these sample project names: There may be a delay while the images are queued and deleted. 1. Change the path or transfer the project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Change path** text box, edit the path. @@ -127,3 +127,12 @@ time is set to 15 minutes. If you are using self-managed GitLab, an administrator can [increase the token duration](../../../administration/packages/container_registry.md#increase-token-duration). + +## Slow uploads when using `kaniko` to push large images + +When you push large images with `kaniko`, you might experience uncharacteristically long delays. + +This is typically a result of [a performance issue with `kaniko` and HTTP/2](https://github.com/GoogleContainerTools/kaniko/issues/2751). +The current workaround is to use HTTP/1.1 when pushing with `kaniko`. + +To use HTTP/1.1, set the `GODEBUG` environment variable to `"http2client=0"`. diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index b7fbeb96202..8e555204f80 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Debian packages in the Package Registry **(FREE ALL)** +# Debian packages in the Package Registry **(FREE ALL EXPERIMENT)** > - Debian API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42670) in GitLab 13.5. > - Debian group API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66188) in GitLab 14.2. @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The Debian package registry for GitLab is under development and isn't ready for production use. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining -work and timelines to make it production ready. +work and timelines to make it production ready. Support for [Debian packages is an experiment](../package_registry/supported_package_managers.md), and has known security vulnerabilities. Publish Debian packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -27,8 +27,11 @@ Prerequisites: - The `dpkg-deb` binary must be installed on the GitLab instance. This binary is usually provided by the [`dpkg` package](https://wiki.debian.org/Teams/Dpkg/Downstream), installed by default on Debian and derivatives. +- Support for compression algorithm ZStandard requires version `dpkg >= + 1.21.18` from Debian 12 Bookworm or `dpkg >= 1.19.0.5ubuntu2` from Ubuntu + 18.04 Bionic Beaver. -## Enable the Debian API **(FREE SELF)** +## Enable the Debian API Debian repository support is still a work in progress. It's gated behind a feature flag that's **disabled by default**. @@ -50,7 +53,7 @@ To disable it: Feature.disable(:debian_packages) ``` -## Enable the Debian group API **(FREE SELF)** +## Enable the Debian group API The Debian group repository is also behind a second feature flag that is disabled by default. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 11b67e5cda3..02810bcb922 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -39,7 +39,7 @@ For a list of planned additions, view the To enable or turn off the Dependency Proxy for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Packages and registries**. 1. Expand the **Dependency Proxy** section. 1. To enable the proxy, turn on **Enable Proxy**. To turn it off, turn the toggle off. @@ -52,7 +52,7 @@ for the entire GitLab instance. To view the Dependency Proxy: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Operate > Dependency Proxy**. The Dependency Proxy is not available for projects. @@ -179,7 +179,7 @@ You can also use [custom CI/CD variables](../../../ci/variables/index.md#for-a-p To store a Docker image in Dependency Proxy storage: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Operate > Dependency Proxy**. 1. Copy the **Dependency Proxy image prefix**. 1. Use one of these commands. In these examples, the image is `alpine:latest`. @@ -367,7 +367,12 @@ see [issue 354826](https://gitlab.com/gitlab-org/gitlab/-/issues/354826). ### `exec format error` when running images from the dependency proxy -This error occurs if you try to use the dependency proxy on an ARM-based Docker install. +NOTE: +This issue was [resolved](https://gitlab.com/gitlab-org/gitlab/-/issues/325669) in GitLab 16.3. +For self managed instances that are 16.2 or earlier, you can update your instance to 16.3 +or use the workaround documented below. + +This error occurs if you try to use the dependency proxy on an ARM-based Docker install in GitLab 16.2 or earlier. The dependency proxy only supports the x86_64 architecture when pulling an image with a specific tag. As a workaround, you can specify the SHA256 of the image to force the dependency proxy @@ -378,5 +383,3 @@ docker pull ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/library/docker:20.10.3@sha ``` In this example, `bc9dcf5c8e5908845acc6d34ab8824bca496d6d47d1b08af3baf4b3adb1bd8fe` is the SHA256 of the ARM based image. - -For more information about the work to add support for other architectures, see [issue 325669](https://gitlab.com/gitlab-org/gitlab/-/issues/325669). diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index e309ab002c4..938093f2a27 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -127,7 +127,7 @@ or the UI. In the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Packages and registries**. 1. In the **Generic** row of the **Duplicate packages** table, turn off the **Allow duplicates** toggle. 1. Optional. In the **Exceptions** text box, enter a regular expression that matches the names and versions of packages to allow. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 52f98ecf4dc..6dffd7371b6 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,7 +4,7 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Go proxy for GitLab **(FREE ALL)** +# Go proxy for GitLab **(FREE ALL EXPERIMENT)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab 13.1. > - It's deployed behind a feature flag, disabled by default. diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index 0cdaaf8ece0..d45b6ea7026 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -12,7 +12,7 @@ You can integrate the [Harbor container registry](../../../user/project/integrat You can view the Harbor Registry for a project or group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Operate > Harbor Registry**. You can search, sort, and filter images on this page. You can share a filtered view by copying the URL from your browser. @@ -29,7 +29,7 @@ Default settings for the Harbor integration at the project level are inherited f To download and run a Harbor image hosted in the GitLab Harbor Registry: 1. Copy the link to your container image: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Operate > Harbor Registry** and find the image you want. 1. Select the **Copy** icon next to the image name. @@ -39,7 +39,7 @@ To download and run a Harbor image hosted in the GitLab Harbor Registry: To view the list of tags associated with a specific artifact: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Go to **Operate > Harbor Registry**. 1. Select the image name to view its artifacts. 1. Select the artifact you want. @@ -57,7 +57,7 @@ To build and push to the Harbor Registry: To view these commands: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Operate > Harbor Registry**. 1. Select **CLI Commands**. @@ -65,7 +65,7 @@ To view these commands: To remove the Harbor Registry for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. 1. Select **Harbor** under **Active integrations**. 1. Under **Enable integration**, clear the **Active** checkbox. diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 57aee4fb4ca..b7888fe2d18 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -4,7 +4,7 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Helm charts in the Package Registry **(FREE ALL)** +# Helm charts in the Package Registry **(FREE ALL BETA)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 51755eda7bb..13d84fa3d99 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -480,7 +480,7 @@ To prevent users from publishing duplicate Maven packages, you can use the [Grap In the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Packages and registries**. 1. In the **Maven** row of the **Duplicate packages** table, turn off the **Allow duplicates** toggle. 1. Optional. In the **Exceptions** text box, enter a regular expression that matches the names and versions of packages to allow. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 74daf9fd891..340df4a3c5f 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -432,6 +432,21 @@ choco push MyPackage.1.0.0.nupkg --source "https://gitlab.example.com/api/v4/pro When you publish a package with the same name or version as an existing package, the existing package is overwritten. +### Do not allow duplicate NuGet packages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293748) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `nuget_duplicates_option`. 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 `nuget_duplicates_option`. +The feature is not ready for production use. + +To prevent users from publishing duplicate NuGet packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings). + +WARNING: +If the .nuspec file isn't located in the root of the package, the package might +not be recognized as a duplicate. + ## Install packages If multiple packages have the same name and version, when you install diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 4d9ad03afde..59184b811d4 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -45,7 +45,7 @@ For information on how to create and upload a package, view the GitLab documenta <!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> WARNING: -[External authorization](../../admin_area/settings/external_authorization.md) will be enabled by default in GitLab 16.0. External authorization prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. +In GitLab 16.0 and later, [external authorization](../../admin_area/settings/external_authorization.md) prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. <!--- end_remove --> Authentication depends on the package manager being used. For more information, see the docs on the @@ -104,14 +104,9 @@ You can view which pipeline published the package, and the commit and user who t ### To import packages If you already have packages built in a different registry, you can import them -into your GitLab package registry with the [Packages Importer](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer). +into your GitLab package registry with the [package importer](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer). -The Packages Importer runs a CI/CD pipeline that [can import these package types](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer#formats-supported): - -- Maven -- NPM -- NuGet -- PyPI +For a list of supported packages, see [Importing packages from other repositories](supported_functionality.md#importing-packages-from-other-repositories). ## Reduce storage usage @@ -163,7 +158,7 @@ Registry disables all Package Registry operations. To allow anyone to pull from the Package Registry, regardless of project visibility: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your private or internal project. +1. On the left sidebar, select **Search or go to** and find your private or internal project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Turn on the **Allow anyone to pull from Package Registry** toggle. diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index d3aa522f780..3e8852da808 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -39,7 +39,7 @@ Packages can be pulled from your project, group, or instance. | [Maven (with `mvn`)](../maven_repository/index.md) | Y | Y | Y | | [Maven (with `gradle`)](../maven_repository/index.md) | Y | Y | Y | | [Maven (with `sbt`)](../maven_repository/index.md) | Y | Y | Y | -| [npm](../npm_registry/index.md) | Y | N | Y | +| [npm](../npm_registry/index.md) | Y | Y | Y | | [NuGet](../nuget_repository/index.md) | Y | Y | N | | [PyPI](../pypi_repository/index.md) | Y | Y | N | | [Generic packages](../generic_packages/index.md) | Y | N | N | @@ -72,7 +72,7 @@ Requests for packages not found in your GitLab project are forwarded to the publ | [Go](../go_proxy/index.md) | N | | [Ruby gems](../rubygems_registry/index.md) | N | -### Deleting packages +## Deleting packages When package requests are forwarded to a public registry, deleting packages can be a [dependency confusion vulnerability](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610). @@ -89,6 +89,27 @@ To reduce the associated security risks, before deleting a package you can: - Instance administrators can disable forwarding in the [**Continuous Integration** section](../../../administration/settings/continuous_integration.md#package-registry-configuration) of the Admin Area. - Group owners can disable forwarding in the **Packages and Registries** section of the group settings. +## Importing packages from other repositories + +You can use GitLab pipelines to import packages from other repositories, such as Maven Central or Artifactory with the [package importer tool](https://gitlab.com/gitlab-org/ci-cd/package-stage/pkgs_importer). + +| Package type | Importer available? | +|-------------------------------------------------------|---------------------| +| [Maven (with `mvn`)](../maven_repository/index.md) | Y | +| [Maven (with `gradle`)](../maven_repository/index.md) | Y | +| [Maven (with `sbt`)](../maven_repository/index.md) | Y | +| [npm](../npm_registry/index.md) | Y | +| [NuGet](../nuget_repository/index.md) | Y | +| [PyPI](../pypi_repository/index.md) | Y | +| [Generic packages](../generic_packages/index.md) | N | +| [Terraform](../terraform_module_registry/index.md) | N | +| [Composer](../composer_repository/index.md) | N | +| [Conan](../conan_repository/index.md) | N | +| [Helm](../helm_repository/index.md) | N | +| [Debian](../debian_repository/index.md) | N | +| [Go](../go_proxy/index.md) | N | +| [Ruby gems](../rubygems_registry/index.md) | N | + ## Allow or prevent duplicates **(FREE ALL)** By default, the GitLab package registry either allows or prevents duplicates based on the default of that specific package manager format. diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 1c898ee6d92..361114e6f9e 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -4,7 +4,7 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Ruby gems in the Package Registry **(FREE ALL)** +# Ruby gems in the Package Registry **(FREE ALL EXPERIMENT)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in GitLab 13.10. diff --git a/doc/user/packages/yarn_repository/index.md b/doc/user/packages/yarn_repository/index.md index 262e15fe240..52accfc4fae 100644 --- a/doc/user/packages/yarn_repository/index.md +++ b/doc/user/packages/yarn_repository/index.md @@ -82,7 +82,7 @@ authentication token or use a private runner. To create an authentication token for your project or group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. On the left sidebar, select **Settings > Repository > Deploy Tokens**. 1. Create a deployment token with `read_package_registry` and `write_package_registry` scopes and copy the generated token. 1. On the left sidebar, select **Settings > CI/CD > Variables**. @@ -301,7 +301,7 @@ Then you can use `yarn add` to install your packages. ## Related topics - [npm documentation](../npm_registry/index.md#helpful-hints) -- [Yarn Migration Guide](https://yarnpkg.com/getting-started/migration) +- [Yarn Migration Guide](https://yarnpkg.com/migration/guide/) ## Troubleshooting diff --git a/doc/user/permissions.md b/doc/user/permissions.md index d19f98b98ed..dadfb75ed4e 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -66,10 +66,10 @@ The following table lists project permissions available for each role: | [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>Manage [security policy](application_security/policies/index.md) | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>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) | | | | | ✓ | +| [Application security](application_security/index.md):<br>Create, edit, delete [individual security policies](application_security/policies/index.md) | | | ✓ | ✓ | ✓ | | [GitLab Agent for Kubernetes](clusters/agent/index.md):<br>View agents | | | ✓ | ✓ | ✓ | | [GitLab Agent for Kubernetes](clusters/agent/index.md):<br>Manage agents | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/delete_container_registry_images.md#use-a-cleanup-policy) | | | | ✓ | ✓ | @@ -132,9 +132,6 @@ The following table lists project permissions available for each role: | [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](project/merge_requests/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (6) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Pull a package | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | @@ -173,7 +170,7 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (7) | ✓ (7) | | [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Assign project to a [compliance framework](project/settings/index.md#add-a-compliance-framework-to-a-project) | | | | | ✓ | +| [Projects](project/index.md):<br>Assign project to a [compliance framework](project/working_with_projects.md#add-a-compliance-framework-to-a-project) | | | | | ✓ | | [Projects](project/index.md):<br>Archive project | | | | | ✓ | | [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | | [Projects](project/index.md):<br>Delete project | | | | | ✓ | @@ -384,7 +381,7 @@ The following table lists group permissions available for each role: | Delete [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | | Edit [epic](group/epics/index.md) comments (posted by any user) | | | | ✓ | ✓ | | List group deploy tokens | | | | ✓ | ✓ | -| Manage [group push rules](group/access_and_permissions.md#group-push-rules) | | | | ✓ | ✓ | +| Manage [group push rules](group/access_and_permissions.md#group-push-rules) | | | | ✓ | ✓ | | View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | | Create and manage compliance frameworks | | | | | ✓ | | Create/Delete group deploy tokens | | | | | ✓ | @@ -401,6 +398,7 @@ The following table lists group permissions available for each role: | View 2FA status of members | | | | | ✓ | | View [Billing](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) | | | | | ✓ (3) | | View group [Usage Quotas](usage_quotas.md) page | | | | | ✓ (3) | +| View group runners | | | | ✓ | ✓ | | Manage group runners | | | | | ✓ | | [Migrate groups](group/import/index.md) | | | | | ✓ | | Manage [subscriptions, and purchase storage and compute minutes](../subscriptions/gitlab_com/index.md) | | | | | ✓ | @@ -473,10 +471,10 @@ To work around the issue, give these users the Guest role or higher to any proje > - [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. - -FLAG: -On self-managed GitLab, by default the ability for a custom role to view a vulnerability report is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `elevated_guests`. On GitLab.com, this feature is available. +> - 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. Custom roles allow group members who are assigned the Owner role to create roles specific to the needs of their organization. @@ -488,24 +486,65 @@ The following custom roles are available: - The Guest+1 role, which allows users with the Guest role to view code. - In GitLab 16.1 and later, you can create a custom role that can view vulnerability reports and change the status of the vulnerabilities. +- In GitLab 16.3 and later, you can create a custom role that can view the dependency list. +- In GitLab 16.4 and later, you can create a custom role that can approve merge requests. You can discuss individual custom role and permission requests in [issue 391760](https://gitlab.com/gitlab-org/gitlab/-/issues/391760). -When you enable the view vulnerability custom role for a user with the Guest role, that user has access to elevated permissions, and therefore: +When you enable a custom role for a user with the Guest role, that user has +access to elevated permissions, and therefore: - Is considered a [billable user](../subscriptions/self_managed/index.md#billable-users) on self-managed GitLab. - [Uses a seat](../subscriptions/gitlab_com/index.md#how-seat-usage-is-determined) on GitLab.com. -This does not apply to the Guest+1 custom role because the `view_code` ability is excluded from this behavior. +This does not apply to Guest+1, a Guest custom role that only enables the `read_code` +permission. Users with that specific custom role are not considered billable users +and do not use a seat. ### Create a custom role -To enable custom roles for your group, a group member with the Owner role: +Prerequisites: + +- You must be an administrator for the self-managed instance, or have the Owner + role in the group you are creating the custom role in. +- The group must be in the Ultimate tier. +- You must have: + - At least one private project so that you can see the effect of giving a + user with the Guest role a custom role. The project can be in the group itself + or one of that group's subgroups. + - A [personal access token with the API scope](profile/personal_access_tokens.md#create-a-personal-access-token). + +#### GitLab SaaS + +Prerequisite: + +- You must have the Owner role in the group you are creating the custom role in. + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > Roles and Permissions**. +1. Select **Add new role**. +1. In **Base role to use as template**, select **Guest**. +1. In **Role name**, enter the custom role's title. +1. Select the **Permissions** for the new custom role. +1. Select **Create new role**. + +#### Self Managed GitLab Instances + +Prerequisite: + +- You must be an administrator for the self-managed instance you are creating the custom role in. + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. Select **Settings > Roles and Permissions**. +1. From the top dropdown list, select the group you want to create a custom role in. +1. Select **Add new role**. +1. In **Base role to use as template**, select **Guest**. +1. In **Role name**, enter the custom role's title. +1. Select the **Permissions** for the new custom role. +1. Select **Create new role**. -1. Makes sure that there is at least one private project in this group or one of - its subgroups, so that you can see the effect of giving a Guest a custom role. -1. Creates a personal access token with the API scope. -1. Uses [the API](../api/member_roles.md#add-a-member-role-to-a-group) to create a custom role for the root group. +To create a custom role, you can also [use the API](../api/member_roles.md#add-a-member-role-to-a-group). #### Custom role requirements @@ -518,7 +557,9 @@ You can see the required minimal access levels and abilities requirements in the | Ability | Minimal access level | Required ability | | -- | -- | -- | | `read_code` | Guest | - | +| `read_dependency` | Guest | - | | `read_vulnerability` | Guest | - | +| `admin_merge_request` | Guest | - | | `admin_vulnerability` | Guest | `read_vulnerability` | ### Associate a custom role with an existing group member @@ -529,53 +570,77 @@ the Owner role: 1. Invites a user as a direct member to the root group or any subgroup or project in the root group's hierarchy as a Guest. At this point, this Guest user cannot see any code on the projects in the group or subgroup. -1. Optional. If the Owner does not know the `ID` of the Guest user receiving a custom - role, finds that `ID` by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). +1. Optional. If the Owner does not know the `id` of the Guest user receiving a custom + role, finds that `id` by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). 1. Associates the member with the Guest+1 role using the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) ```shell # to update a project membership - curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": '$MEMBER_ROLE_ID', "access_level": 10}' "https://example.gitlab.com/api/v4/projects/$ID/members/$GUEST_USER_ID" + curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": '<member_role_id>', "access_level": 10}' "https://gitlab.example.com/api/v4/projects/<project_id>/members/<user_id>" # to update a group membership - curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": '$MEMBER_ROLE_ID', "access_level": 10}' "https://example.gitlab.com/api/v4/groups/$ID/members/$GUEST_USER_ID" + curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": '<member_role_id>', "access_level": 10}' "https://gitlab.example.com/api/v4/groups/<group_id>/members/<user_id>" ``` Where: - - `$ID`: The `ID` or [URL-encoded path of the project or group](../api/rest/index.md#namespaced-path-encoding) associated with the membership receiving the custom role. - - `$MEMBER_ROLE_ID`: The `ID` of the member role created in the previous section. - - `$GUEST_USER_ID`: The `ID` of the Guest user receiving a custom role. + - `<project_id` and `<group_id>`: The `id` or [URL-encoded path of the project or group](../api/rest/index.md#namespaced-path-encoding) associated with the membership receiving the custom role. + - `<member_role_id>`: The `id` of the member role created in the previous section. + - `<user_id>`: The `id` of the user receiving a custom role. Now the Guest+1 user can view code on all projects associated with this membership. -### Remove a custom role from a group member +### Remove a custom role + +Prerequisite: + +- You must be an administrator or have the Owner role in the group you are removing the custom role from. + +You can remove a custom role from a group only if no group members have that role. + +To do this, you can either remove the custom role from all group members with that custom role, or remove those members from the group. + +#### Remove a custom role from a group member To remove a custom role from a group member, use 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. ```shell -curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": "", "access_level": 10}' "https://example.gitlab.com/api/v4/groups/$GROUP_PATH/members/$GUEST_USER_ID" +# to update a project membership +curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": "", "access_level": 10}' "https://gitlab.example.com/api/v4/projects/<project_id>/members/<user_id>" + +# to update a group membership +curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"member_role_id": "", "access_level": 10}' "https://gitlab.example.com/api/v4/groups/<group_id>/members/<user_id>" ``` -Now the user is a regular Guest. +#### Remove a group member with a custom role from the group -### Remove a custom role +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. On the member row you want to remove, select the vertical ellipsis + (**{ellipsis_v}**) and select **Remove member**. +1. In the **Remove member** confirmation dialog, do not select any checkboxes. +1. Select **Remove member**. -Removing a custom role also removes all members with that custom role from -the group. If you decide to delete a custom role, you must re-add any users with that custom -role to the group. +#### Delete the custom role -To remove a custom role from a group, a group member with -the Owner role: +After you have made sure no group members have that custom role, delete the +custom role. + +1. On the left sidebar, select **Search or go to**. +1. GitLab.com only. Select **Admin Area**. +1. Select **Settings > Roles and Permissions**. +1. Select **Custom Roles**. +1. In the **Actions** column, select **Delete role** (**{remove}**) and confirm. -1. Optional. If the Owner does not know the `ID` of a custom - role, finds that `ID` by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). -1. Uses [the API](../api/member_roles.md#remove-member-role-of-a-group) to delete the custom role. +To delete a custom role, you can also [use the API](../api/member_roles.md#remove-member-role-of-a-group). +To use the API, you must know the `id` of the custom role. If you do not know this +`id`, find it by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). ### Known issues -- Additional permissions can only be applied to users with the Guest role. -- If a user with a custom role is shared with a group or project, their custom role is not transferred over with them. The user has the regular Guest role in the new group or project. +- If a user with a custom role is shared with a group or project, their custom + role is not transferred over with them. The user has the regular Guest role in + the new group or project. - You cannot use an [Auditor user](../administration/auditor_users.md) as a template for a custom role. diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 06a90af55c7..d90b2d5c882 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -4,26 +4,23 @@ group: Product Analytics info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Product analytics (Experiment) **(ULTIMATE ALL)** +# Product analytics **(ULTIMATE ALL EXPERIMENT)** > - 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. > - `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. -> - Snowplow integration introduced in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. Disabled by default. +> - 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. -FLAG: -On self-managed GitLab, by default the Snowplow integration 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_snowplow_support`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - 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/analytics/product-analytics/). +To leave feedback about Product Analytics bugs or functionality, please comment in [issue 391970](https://gitlab.com/gitlab-org/gitlab/-/issues/391970) or open a new issue with the label `group::product analytics`. ## How product analytics works @@ -66,7 +63,7 @@ flowchart TB > - `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` and `product_analytics_admin_settings`. +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. @@ -77,7 +74,7 @@ Prerequisite: - You must be an administrator of a self-managed GitLab instance. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Analytics** tab and find the **Product analytics** section. @@ -93,8 +90,9 @@ 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. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Analytics**. 1. Expand **Configure** and enter the configuration values. 1. Select **Save changes**. @@ -105,6 +103,9 @@ To instrument code to collect data, use one or more of the existing SDKs: - [Browser SDK](https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-browser) - [Ruby SDK](https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-rb) +- [Python SDK](https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-python) +- [Node SDK](https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-node) +- [.NET SDK](https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-dotnet) ## Product analytics dashboards diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index f2f1921f0bb..c3612b787ac 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -1,6 +1,6 @@ --- type: reference -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -33,7 +33,7 @@ Prerequisite: To create a user manually: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Overview > Users**. 1. Select **New user**. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 2694ed5f213..cf6ee61660f 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,6 +1,6 @@ --- type: howto -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -36,7 +36,7 @@ On GitLab.com, there is a seven day delay between a user deleting their own acco As an administrator, to delete a user account: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Overview > Users**. 1. Select a user. diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 83bdf883510..c7633b2c664 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -62,6 +62,8 @@ In GitLab 14.3 and later, your account email must be confirmed to enable 2FA. To enable 2FA with a one-time password: +<!-- vale gitlab.Substitutions = NO --> + 1. **In GitLab:** 1. Access your [**User settings**](../index.md#access-your-user-settings). 1. Select **Account**. @@ -70,7 +72,7 @@ To enable 2FA with a one-time password: 1. Install a compatible application. For example: - Cloud-based (recommended because you can restore access if you lose the hardware device): - [Authy](https://authy.com/). - - [Duo](https://duo.com/). + - [Cisco Duo](https://duo.com/). - Other (proprietary): - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en). - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app). @@ -85,6 +87,8 @@ To enable 2FA with a one-time password: 1. Enter your current password. 1. Select **Submit**. +<!-- vale gitlab.Substitutions = YES --> + If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them in a safe place. @@ -152,27 +156,33 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: (Linux package installations) or [restart](../../../administration/restart_gitlab.md#self-compiled-installations) (self-compiled installations). -### Enable one-time password using Duo +<!-- vale gitlab.Substitutions = NO --> + +### Enable one-time password using Cisco Duo > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15760) in GitLab 15.10. FLAG: On self-managed GitLab, by default this feature is available. On GitLab.com this feature is not available. -You can use Duo as an OTP provider in GitLab. +You can use Cisco Duo as an OTP provider in GitLab. + +DUO® is a registered trademark of Cisco Systems, Inc., and/or its affiliates in the United States and certain other countries. #### Prerequisites -To use Duo as an OTP provider: +To use Cisco Duo as an OTP provider: + +- Your account must exist in both Cisco Duo and GitLab, with the same username in both applications. +- You must have [configured Cisco Duo](https://admin.duosecurity.com/) and have an integration key, secret key, and API hostname. -- Your account must exist in both Duo and GitLab, with the same username in both applications. -- You must have [configured Duo](https://admin.duosecurity.com/) and have an integration key, secret key, and API hostname. +For more information, see the [Cisco Duo API documentation](https://duo.com/docs/authapi). -For more information, see the [Duo API documentation](https://duo.com/docs/authapi). +GitLab 15.10 has been tested with Cisco Duo version D261.14 -GitLab 15.10 has been tested with Duo version D261.14 +#### Configure Cisco Duo in GitLab -#### Configure Duo in GitLab +<!-- vale gitlab.Substitutions = YES --> On your GitLab server: diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md index 080ab41083b..1b875e984a1 100644 --- a/doc/user/profile/achievements.md +++ b/doc/user/profile/achievements.md @@ -4,7 +4,7 @@ group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Achievements (Experiment) **(FREE ALL)** +# Achievements **(FREE ALL EXPERIMENT)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113156) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `achievements`. Disabled by default. diff --git a/doc/user/profile/img/profile-preferences-syntax-themes_v15_11.png b/doc/user/profile/img/profile-preferences-syntax-themes_v15_11.png Binary files differdeleted file mode 100644 index 39cd35f3b5b..00000000000 --- a/doc/user/profile/img/profile-preferences-syntax-themes_v15_11.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index a25260c3db9..cff18654292 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,6 +1,6 @@ --- type: index, howto -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -353,7 +353,7 @@ A list of **Most Recent Activity** contributions is displayed. To view your activity: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Select **Activity**. 1. Optional. To filter your activity by contribution type, in the **Your Activity** tab, select a tab: @@ -397,15 +397,15 @@ When you sign in, three cookies are set: - A session cookie called `_gitlab_session`. This cookie has no set expiration date. However, it expires based on its `session_expire_delay`. -- A session cookie called `about_gitlab_active_user`. - This cookie is used by the [marketing site](https://about.gitlab.com/) to determine if a user has an active GitLab session. No user information is passed to the cookie and it expires with the session. +- A session cookie called `gitlab_user`. + This cookie is used by the [marketing site](https://about.gitlab.com/) to determine if a user has an active GitLab session. No user information is passed to the cookie and it expires two weeks from login. - A persistent cookie called `remember_user_token`, which is set only if you selected **Remember me** on the sign-in page. -When you close your browser, the `_gitlab_session` and `about_gitlab_active_user` cookies are usually cleared client-side. +When you close your browser, the `_gitlab_session` and `gitlab_user` cookies are usually cleared client-side. When it expires or isn't available, GitLab: - Uses the `remember_user_token`cookie to get you a new `_gitlab_session` cookie and keep you signed in, even if you close your browser. -- Sets the `about_gitlab_active_user` to `true`. +- Sets the `gitlab_user` to `true`. When both the `remember_user_token` and `_gitlab_session` cookies are gone or expired, you must sign in again. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index f1310bbb323..706065d4693 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -107,7 +107,7 @@ To select a notification level for a group, use either of these methods: Or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select the notification dropdown list, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). @@ -138,7 +138,7 @@ To select a notification level for a project, use either of these methods: Or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select the notification dropdown list, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). @@ -275,6 +275,7 @@ epics: | Merge Request | New note | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | | Merge Request | Pushed | Participants and Custom notification level with this event selected. | | Merge Request | Reassigned | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | +| Merge Request | Review requested | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old reviewer. | | Merge Request | Reopened | Subscribers and participants. | | Merge Request | Title or description changed | Any new mentions by username. | | Pipeline | Failed | The author of the pipeline. | @@ -367,20 +368,21 @@ a merge request or an issue. The following table lists all GitLab-specific email headers: -| Header | Description | -| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `List-Id` | The path of the project in an RFC 2919 mailing list identifier. You can use it for email organization with filters. | -| `X-GitLab-(Resource)-ID` | The ID of the resource the notification is for. The resource, for example, can be `Issue`, `MergeRequest`, `Commit`, or another such resource. | -| `X-GitLab-ConfidentialIssue` | The boolean value indicating issue confidentiality for notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222908) in GitLab 16.0. | -| `X-GitLab-Discussion-ID` | The ID of the thread the comment belongs to, in notification emails for comments. | -| `X-GitLab-Group-Id` | The group's ID. Only present on notification emails for [epics](../group/epics/index.md). | -| `X-GitLab-Group-Path` | The group's path. Only present on notification emails for [epics](../group/epics/index.md) | -| `X-GitLab-NotificationReason` | The reason for the notification. [See possible values.](#x-gitlab-notificationreason). | -| `X-GitLab-Pipeline-Id` | The ID of the pipeline the notification is for, in notification emails for pipelines. | -| `X-GitLab-Project-Id` | The project's ID. | -| `X-GitLab-Project-Path` | The project's path. | -| `X-GitLab-Project` | The name of the project the notification belongs to. | -| `X-GitLab-Reply-Key` | A unique token to support reply by email. | +| Header | Description | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `List-Id` | The path of the project in an RFC 2919 mailing list identifier. You can use it for email organization with filters. | +| `X-GitLab-(Resource)-ID` | The ID of the resource the notification is for. The resource, for example, can be `Issue`, `MergeRequest`, `Commit`, or another such resource. | +| `X-GitLab-(Resource)-State` | The state of the resource the notification is for. The resource can be, for example, `Issue` or `MergeRequest`. The value can be `opened`, `closed`, `merged`, or `locked`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130967) in GitLab 16.4. | +| `X-GitLab-ConfidentialIssue` | The boolean value indicating issue confidentiality for notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222908) in GitLab 16.0. | +| `X-GitLab-Discussion-ID` | The ID of the thread the comment belongs to, in notification emails for comments. | +| `X-GitLab-Group-Id` | The group's ID. Only present on notification emails for [epics](../group/epics/index.md). | +| `X-GitLab-Group-Path` | The group's path. Only present on notification emails for [epics](../group/epics/index.md) | +| `X-GitLab-NotificationReason` | The reason for the notification. [See possible values.](#x-gitlab-notificationreason). | +| `X-GitLab-Pipeline-Id` | The ID of the pipeline the notification is for, in notification emails for pipelines. | +| `X-GitLab-Project-Id` | The project's ID. | +| `X-GitLab-Project-Path` | The project's path. | +| `X-GitLab-Project` | The name of the project the notification belongs to. | +| `X-GitLab-Reply-Key` | A unique token to support reply by email. | ### X-GitLab-NotificationReason diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 9161f5d4cf6..c3361040a00 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -1,6 +1,6 @@ --- type: concepts, howto -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -104,7 +104,8 @@ To view the last time a token was used: ## Personal access token scopes -> Personal access tokens no longer being able to access container or package registries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387721) in GitLab 16.0. +> - Personal access tokens no longer being able to access container or package registries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387721) in GitLab 16.0. +> - `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default. A personal access token can perform actions based on the assigned scopes. @@ -120,13 +121,15 @@ 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. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. | WARNING: If you enabled [external authorization](../admin_area/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. ## When personal access tokens expire -Personal access tokens expire on the date you define, at midnight UTC. +Personal access tokens expire on the date you define, at midnight, 00:00 AM UTC. - GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in the next seven days. The owners of these tokens are notified by email. - GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expire on the current date. The owners of these tokens are notified by email. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 2df2674d539..f057e62694b 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -13,7 +13,7 @@ You can update your preferences to change the look and feel of GitLab. You can change the color theme of the GitLab UI. These colors are displayed on the left sidebar. Using individual color themes might help you differentiate between your different -GitLab instances. +GitLab instances. To change the color theme: @@ -25,7 +25,7 @@ To change the color theme: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Experiment](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252). -Dark mode makes elements on the GitLab UI stand out on a dark background. +Dark mode makes elements on the GitLab UI stand out on a dark background. - To turn on Dark mode, Select **Preferences > Color theme > Dark Mode**. @@ -44,139 +44,304 @@ To change the syntax highlighting theme: 1. In the **Syntax highlighting theme** section, select a theme. 1. Select **Save changes**. -To view the updated syntax highlighting theme, refresh your project's page. +To view the updated syntax highlighting theme, refresh your project's page. To customize the syntax highlighting theme, you can also [use the Application settings API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). Use `default_syntax_highlighting_theme` to change the syntax highlighting colors on a more granular level. -If these steps do not work, your programming language might not be supported by the syntax highlighters. +If these steps do not work, your programming language might not be supported by the syntax highlighters. For more information, view [Rouge Ruby Library](https://github.com/rouge-ruby/rouge) for guidance on code files and Snippets. View [Moncaco Editor](https://microsoft.github.io/monaco-editor/) and [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) for guidance on the Web IDE. ## Change the diff colors -Diffs use two different background colors to show changes between versions of code. By default, the original file in red and the changes made in green. +Diffs use two different background colors to show changes between versions of code. By default, the original file is in red, and the changes are in green. To change the diff colors: 1. On the left sidebar, select your avatar. 1. Select **Preferences**. -1. Go to the **Diff colors** section. -1. Complete the fields. +1. Go to the **Diff colors** section. +1. Select a color or enter a color code. 1. Select **Save changes**. -1. Optional. Type a color code in the fields. + +To change back to the default colors, clear the **Color for removed lines** and **Color for added lines** text boxes and select **Save changes**. ## Behavior -The following settings allow you to customize the behavior of the GitLab layout -and default views of your dashboard and the projects' landing pages. +Use the **Behavior** section to customize the behavior and layout of your GitLab self-managed instance. You can change your layout width and choose the default content for your homepage, group and project overview pages. You have options to customize appearance and function, like whitespace rendering, file display, and text automation. -### Layout width +### Change the layout width on the UI -GitLab can be set up to use different widths depending on your liking. Choose -between the fixed (max. `1280px`) and the fluid (`100%`) application layout. +You can stretch content on the GitLab UI to fill the entire page. By default, page content is fixed at 1280 pixels wide. -NOTE: -While `1280px` is the standard max width when using fixed layout, some pages still use 100% width, depending on the content. +To change the layout width of your UI: -### Homepage +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. Under **Layout width**, choose **Fixed** or **Fluid**. +1. Select **Save changes**. -This setting changes the behavior of the tanuki icon in the upper-left corner of GitLab. +### Choose your homepage -### Group overview content +Control what page you view when you select the GitLab logo (**{tanuki}**). You can set your homepage to be Projects (default), Your Groups, Your Activity, and other content. -The **Group overview content** dropdown list allows you to choose what information is -displayed on a group's home page. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. For **Homepage**, select a default. +1. Select **Save changes**. -You can choose between 2 options: +### Customize default content on your group overview page -- Details (default) -- [Security dashboard](../application_security/security_dashboard/index.md) +You can change the main content on your group overview page. Your group overview page is the page that shows when you select **Groups** on the left sidebar. You can customize the default content for your group overview page to the: -### Project overview content +- Details Dashboard (default), which includes an overview of group activities and projects. +- Security Dashboard, which might include group security policies and other security topics. -The **Project overview content** setting allows you to choose what content you want to -see on a project's home page. +For more information, view [Groups](../../user/group/index.md). -If **Files and Readme** is selected, you can show or hide the shortcut buttons above the file list on the project overview with the **Show shortcut buttons above files on project overview** setting. +To change the default content on your group overview page: -### Tab width +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. For **Group overivew content**, select an option. +1. Select **Save changes**. -You can set the displayed width of tab characters across various parts of -GitLab, for example, blobs, diffs, and snippets. +### Customize default content on your project overview page -NOTE: -Some parts of GitLab do not respect this setting, including the WebIDE, file -editor and Markdown editor. +Your project overview page is the page you view when you select **Project overview** on the left sidebar. You can set your main project overview page to the Activity page, the Readme file, and other content. + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. For **Project overivew content**, select an option. +1. Select **Save changes**. + +### Hide shortcut buttons + +Shortcut buttons precede the list of files on a project's overview page. These buttons provide links to parts of a project, such as the README file or license agreements. + +To hide shortcut buttons on the project overview page: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. Clear the **Show shortcut buttons above files on project overview** checkbox. +1. Select **Save changes**. + +### Show whitespace characters in the Web IDE + +Whitespace characters are any blank characters in a text, such as spaces and indentations. You might use whitespace to structure content in code. If your programming language is sensitive to whitespaces, the Web IDE can detect changes to them. + +To render whitespace in the Web IDE: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. Select the **Render whitespace characters in the Web IDE** checkbox. +1. Select **Save changes**. + +You can view changes to whitespace in diffs. + +To view diffs on the Web IDE, follow these steps: + +1. On the left sidebar, select **Source Control** (**{branch}**). +1. Under the **Changes** tab, select your file. + +### Show whitespace changes in diffs + +View changes to whitespace in diff files. For more information on whitespaces, view the previous task. + +To view changes to whitespace in diffs: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. Select the **Show whitespace changes in diffs** checkbox. +1. Select **Save changes**. + +For more information on diffs, view [Change the diff colors](#change-the-diff-colors). + +### Show one file per page in a merge request + +The **Changes** tab lets you view all file changes in a merge request on one page. +Instead, you can choose to view one file at a time. + +To show one file per page on the **Changes** tab: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. Select the **Show one file at a time on merge request's Changes tab** checkbox. +1. Select **Save changes**. + +Then, to move between files on the **Changes** tab, below each file, select the **Previous** and **Next** buttons. + +### Auto-enclose characters + +Automatically add the corresponding closing character to text when you type the opening character. For example, you can automatically insert a closing bracket when you type an opening bracket. This setting works only in description and comment boxes and for the following characters: `**"`, `'`, ```, `(`, `[`, `{`, `<`, `*`, `_**`. + +To auto-enclose characters in description and comment boxes: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. Select the **Surround text selection when typing quotes or brackets** checkbox. +1. Select **Save changes**. + +In a description or comment box, you can now type a word, highlight it, then type an +opening character. Instead of replacing the text, the closing character is added to the end. + +### Automate new list items + +Create a new list item when you press <kbd>Enter</kbd> in a list in description and comment boxes. + +To add a new list item when you press the <kbd>Enter</kbd> key: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. Select the **Automatically add new list items** checkbox. +1. Select **Save changes**. + +### Change the tab width + +Change the default size of tabs in diffs, blobs, and snippets. The WebIDE, file editor, and Markdown editor do not support this feature. + +To adjust the default tab width: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Behavior** section. +1. For **Tab width**, enter a value. +1. Select **Save changes**. ## Localization -### Language +Change localization settings such as your language, calendar start day, and time preferences. -Select your preferred language from a list of supported languages. +### Change your display language on the GitLab UI -*This feature is experimental and translations are not complete yet.* +GitLab supports multiple languages on the UI. To help improve translations or request support for an unlisted language, view [Translating GitLab](../../development/i18n/translation.md). -### First day of the week +To choose a language for the GitLab UI: -The first day of the week can be customized for calendar views and date pickers. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Localization** section. +1. Under **Language**, select an option. +1. Select **Save changes**. + +You might need to refresh your page to view the updated language. -You can choose one of the following options as the first day of the week: +### Customize your contribution calendar start day -- Saturday -- Sunday -- Monday +Choose which day of the week the contribution calendar starts with. The contribution calendar shows project contributions over the past year. You can view this calendar on each user profile. To access your user profile: -If you select **System Default**, the first day of the week is set to the -[instance default](../../administration/settings/index.md#change-the-default-first-day-of-the-week). +- On the left sidebar, select your avatar > select your name or username. + +To change your contribution calendar start day: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Localization** section. +1. Under **First day of the week**, select an option. +1. Select **Save changes**. -## Time preferences +After you change your calendar start day, refresh your user profile page. -### Use relative times +### Show exact times instead of relative times > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65570) in GitLab 14.1. -You can select your preferred time format for the GitLab user interface: +Customize the format used to display times of activities on your group and project overview pages and user profiles. You can display times in a: + +- Relative format, for example `30 minutes ago`. +- Absolute format, for example `September 3, 2022, 3:57 PM`. + +To use relative times on the GitLab UI: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Time preferences** section. +1. Clear the **Use relative times** checkbox. +1. Select **Save changes**. + +## User identities in CI job JSON web tokens + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387537) in GitLab 16.0. + +CI/CD jobs generate JSON web tokens, which can include a list of your external identities. +Instead of making separate API calls to get individual accounts, you can find your user identities in a single authentication token. + +External identities are not included by default. +To enable including external identities, see [Token payload](../../ci/secrets/id_token_authentication.md#token-payload). + +## Control follower engagement + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0. + +Turn off the ability to follow or be followed by other GitLab users. By default, your user profile, including your name and profile photo, is public in the **Following** tabs of other users. When you deactivate this setting: + +- GitLab deletes all of your followers and followed connections. +- GitLab automatically removes your user profile from the pages of each connection. + +To remove the ability to be followed by and follow other users: + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Clear the **Enable follow users** checkbox. +1. Select **Save changes**. + +To access your **Followers** and **Following** tabs: -- Relative times, for example, `30 minutes ago`. -- Absolute times, for example, `May 18, 2021, 3:57 PM`. +- On the left sidebar, select your avatar > select your name or username. +- Select **Followers** or **Following**. -The times are formatted depending on your chosen language and browser locale. +## Enable Code Suggestions -To set your time preference: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../policy/experiment-beta-support.md#beta). -1. On the **Preferences** page, go to **Time preferences**. -1. Select the **Use relative times** checkbox to use relative times, - or clear the checkbox to use absolute times. +To enable [Code Suggestions](../../user/project/repository/code_suggestions/index.md): + +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Select the **Enable Code Suggestions** checkbox. 1. Select **Save changes**. NOTE: -This feature is experimental, and choosing absolute times might break certain layouts. -Open an issue if you notice that using absolute times breaks a layout. +If Code Suggestions are turned off [for the group](../../user/group/manage.md#enable-code-suggestions), then you cannot enable them for yourself. (Your setting has no effect.) -## User identities in CI job JSON web tokens +## Integrate your GitLab instance with third-party services + +Give third-party services access to your GitLab account. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387537) in GitLab 16.0. False by default. +### Integrate your GitLab instance with Gitpod -You can select to include the list of your external identities in the JSON Web Token information that is generated for a CI job. -For more information and examples, see [Token Payload](../../ci/secrets/id_token_authentication.md#token-payload). +Configure your GitLab instance with Gitpod when you want to launch and manage code directly from your GitLab browser. Gitpod automatically prepares and builds development environments for your projects. -## Integrations +To integrate with Gitpod: -Configure your preferences with third-party services which provide enhancements to your GitLab experience. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Find the **Integrations** section. +1. Select the **Enable Gitpod integration** checkbox. +1. Select **Save changes**. -### Sourcegraph +### Integrate your GitLab instance with Sourcegraph -NOTE: -This setting is only visible if Sourcegraph has been enabled by a GitLab administrator. +GitLab supports Sourcegraph integration for all public projects on GitLab. -Manage the availability of integrated code intelligence features powered by -Sourcegraph. View [the Sourcegraph feature documentation](../../integration/sourcegraph.md#enable-sourcegraph-in-user-preferences) -for more information. +To integrate with Sourcegraph: -### Gitpod +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Find the **Integrations** section. +1. Select the **Enable integrated code intelligence on code views** checkbox. +1. Select **Save changes**. -Enable and disable the [GitLab-Gitpod integration](../../integration/gitpod.md). This is only -visible after the integration is configured by a GitLab administrator. View -[the Gitpod feature documentation](../../integration/gitpod.md) for more information. +You must be the administrator of the GitLab instance to configure GitLab with Sourcegraph. <!-- ## Troubleshooting diff --git a/doc/user/profile/service_accounts.md b/doc/user/profile/service_accounts.md index e593378ce4a..8845ee55e14 100644 --- a/doc/user/profile/service_accounts.md +++ b/doc/user/profile/service_accounts.md @@ -1,6 +1,6 @@ --- type: index, howto -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -22,6 +22,11 @@ A service account: You should use service accounts in pipelines or integrations where credentials must be set up and maintained without being impacted by changes in human user membership. +You can authenticate as a service account with a [personal access token](personal_access_tokens.md). +Service account users with a personal access token have the same abilities as a standard user. +This includes interacting with [registries](../packages/index.md) and using the personal access +token for [Git operations](personal_access_tokens.md#clone-repository-using-personal-access-token). + ## Create a service account The number of service accounts you can create is restricted by the number of service @@ -50,7 +55,8 @@ Prerequisite: The response includes the personal access token value. -1. Use the returned personal access token value to authenticate with the GitLab API as the service account user. +1. Make this service account a group or project member by [manually adding the service account user to the group or project](#add-a-service-account-to-subgroup-or-project). +1. Use the returned personal access token value to authenticate as the service account user. ### Self-managed GitLab @@ -63,14 +69,16 @@ Prerequisite: This service account is associated with the entire instance, not a specific group or project in the instance. -1. [Create a personal access token](../../api/users.md#create-service-account-user) +1. [Create a personal access token](../../api/users.md#create-a-personal-access-token) for the service account user. You define the scopes for the service account by [setting the scopes for the personal access token](personal_access_tokens.md#personal-access-token-scopes). The response includes the personal access token value. -1. Use the returned personal access token value to authenticate with the GitLab API as the service account user. +1. Make this service account a group or project member by + [manually adding the service account user to the group or project](#add-a-service-account-to-subgroup-or-project). +1. Use the returned personal access token value to authenticate as the service account user. ## Add a service account to subgroup or project @@ -88,27 +96,13 @@ A service account: - Can have different roles across multiple subgroups and projects of the same top level group. - On GitLab.com, only belongs to one top-level group. -### Add to a subgroup - -You can add the service account to a subgroup [through the UI](../group/index.md#add-users-to-a-group) -or API. - -To add the service account through the API, call the following endpoint: - -```shell -curl --request POST --header "PRIVATE-TOKEN: <ACCESS TOKEN>" --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/groups/<subgroup_id>/members" -``` - -### Add to a project - -You can add the service account to a project [through the UI](../project/members/index.md#add-users-to-a-project) -or API. +### Add to a subgroup or project -To add the service account through the API, call the following endpoint: +You can add the service account to a subgroup or project through the: -```shell -curl --request POST --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>" --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/projects/<project_id>/members" -``` +- [API](../../api/members.md#add-a-member-to-a-group-or-project). +- [Group members UI](../group/index.md#add-users-to-a-group). +- [Project members UI](../project/members/index.md#add-users-to-a-project). ### Change a service account role in a subgroup or project diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index d8604bc712e..7882502a588 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index c275d2b39db..39c1d228d63 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -130,7 +130,7 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Badges**. 1. Select **Add badge**. @@ -152,7 +152,7 @@ A common project badge presents the GitLab CI pipeline status. To add this badge to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter _Pipeline Status_. @@ -181,7 +181,7 @@ If you need individual badges for each project, either: To add a new badge to a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under @@ -203,7 +203,7 @@ Badges associated with a group can be edited or deleted only at the [group level You can view the exact link for your badges. Then you can use the link to embed the badge in your HTML or Markdown pages. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. 1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. @@ -270,7 +270,7 @@ https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg To add a new badge with a custom image to a group or project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > General**. 1. Expand **Badges**. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 45d3834542b..d8b1b6fd413 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -56,7 +56,7 @@ cluster certificates: 1. Go to your: - Project's **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - - **Main menu > Admin > Kubernetes**, for an instance-level cluster. + - The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. @@ -248,7 +248,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Amazon EKS**. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 5127248baed..7e2c429c6bb 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -68,7 +68,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **Main menu > Admin > Kubernetes** page, for an instance-level cluster. + 1. The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown list. 1. On the **Connect a cluster** page, fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index a3a7cb35346..a087460d89e 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -63,7 +63,7 @@ cluster certificates: - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. + - The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Google GKE**. 1. Connect your Google account if you haven't done already by selecting the diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 16ad95bb95c..a3263109bb1 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -19,7 +19,7 @@ When you successfully connect an existing cluster using cluster certificates, th 1. Go to your: - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. + - The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. 1. Toggle **GitLab Integration** off (in gray). 1. Select **Save changes**. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 58553fbb1c3..1a69b45b651 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -24,5 +24,5 @@ to a single project. To view project-level Kubernetes clusters: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Kubernetes clusters**. diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index 74974958910..d783471f0da 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -6,17 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Code Owners **(PREMIUM ALL)** -> Moved to GitLab Premium in 13.9. - Use the Code Owners feature to define who has expertise for specific parts of your project's codebase. Define the owners of files and directories in a repository to: - **Require owners to approve changes.** Combine protected branches with Code Owners to require experts to approve merge requests before they merge into a protected branch. - **Identify owners.** Code Owner names are displayed on the files and directories they own: +  -Use Code Owners in combination with merge request +Combine Code Owners with merge request [approval rules](../merge_requests/approvals/rules.md) (either optional or required) to build a flexible approval workflow: @@ -42,13 +41,11 @@ For example: <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> </figure> -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> - ## View Code Owners of a file or directory To view the Code Owners of a file or directory: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Go to the file or directory you want to see the Code Owners for. 1. Optional. Select a branch or tag. @@ -57,14 +54,14 @@ GitLab shows the Code Owners at the top of the page. ## Set up Code Owners -1. Create a `CODEOWNERS` file in your [preferred location](#code-owners-file). +1. Create a `CODEOWNERS` file in your [preferred location](#codeowners-file). 1. Define some rules in the file following the [Code Owners syntax reference](reference.md). Some suggestions: - Configure [All eligible approvers](../merge_requests/approvals/rules.md#code-owners-as-eligible-approvers) approval rule. - [Require Code Owner approval](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) on a protected branch. 1. Commit your changes, and push them up to GitLab. -### Code Owners file +### `CODEOWNERS` file A `CODEOWNERS` file (with no extension) specifies the users or [shared groups](../members/share_project_with_groups.md) responsible for @@ -78,9 +75,17 @@ all others are ignored: 1. In the `docs` directory: `./docs/CODEOWNERS`. 1. In the `.gitlab` directory: `./.gitlab/CODEOWNERS`. -### Add a group as a Code Owner +For more information, see [Code Owners syntax and error handling](reference.md). + +#### When user or group change names + +When a user or group change their names, the `CODEOWNERS` isn't automatically updated with the new names. +To enter the new names, you must edit the file. -> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. +Organizations using SAML SSO can [set usernames](../../../integration/saml.md#set-a-username) to +prevent users from being able to change their usernames. + +### Add a group as a Code Owner To set the members of a group or subgroup as a Code Owner: @@ -99,8 +104,6 @@ file.md @group-x @group-x/subgroup-y #### Group inheritance and eligibility -> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. - ```mermaid graph TD A[Parent group X] -->|owns| B[Project A] @@ -188,9 +191,6 @@ Only one CODEOWNERS pattern per section is matched to a file path. ### Organize Code Owners by putting them into sections -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed. - You can organize Code Owners by putting them into named sections. You can use sections for shared directories, so that multiple @@ -215,9 +215,10 @@ The following image shows a **Groups** and **Documentation** section: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `codeowners_default_owners`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115888) in GitLab 15.11. Feature flag `codeowners_default_owners` removed. -If multiple file paths inside a section share the same ownership, define a default -Code Owner for the section. All paths in that section inherit this default, unless -you override the section default on a specific line. +If multiple file paths inside a section share the same ownership, define default +Code Owners for the section. +All paths in that section inherit this default, unless you override the section +default on a specific line. Default owners are applied when specific owners are not specified for file paths. Specific owners defined beside the file path override default owners: @@ -227,7 +228,7 @@ Specific owners defined beside the file path override default owners: docs/ README.md -[Database] @database-team +[Database] @database-team @agarcia model/db/ config/db/database-setup.md @docs-team ``` @@ -235,9 +236,14 @@ config/db/database-setup.md @docs-team In this example: - `@docs-team` owns all items in the `Documentation` section. -- `@database-team` owns all items in the `Database` section except +- `@database-team` and `@agarcia` own all items in the `Database` section except `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. +Compare this behavior to when you use [regular entries and sections together](#use-regular-entries-and-sections-together), +when entries in sections don't override entries without sections. + +#### Use default owners and optional sections together + To combine the syntax for default owners with [optional sections](#make-a-code-owners-section-optional) and required approvals, place default owners at the end: @@ -251,6 +257,38 @@ model/db/ config/db/database-setup.md @docs-team ``` +#### Use regular entries and sections together + +If you set a default Code Owner for a path outside a section, their approval is always required, and +the entry isn't overridden. +Entries without sections are treated as if they were another, unnamed section: + +```plaintext +# Required for all files +* @general-approvers + +[Documentation] @docs-team +docs/ +README.md +*.txt + +[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +In this example: + +- `@general-approvers` owns all items everywhere, without overrides. +- `@docs-team` owns all items in the `Documentation` section. +- `@database-team` owns all items in the `Database` section except + `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. +- A merge request that modifies `model/db/CHANGELOG.txt` would require three approvals: one from each + of the `@general-approvers`,`@docs-team`, and `@database-team` groups. + +Compare this behavior to when you use only [default owners for sections](#set-default-owner-for-a-section), +when specific entries within a section override the section default. + #### Sections with duplicate names If multiple sections have the same name, they are combined. @@ -275,8 +313,6 @@ entries under **Database**. The entries defined under the sections **Documentati #### Make a Code Owners section optional -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. - You can designate optional sections in your Code Owners file. Prepend the section name with the caret `^` character to treat the entire section as optional. Optional sections enable you to designate responsible parties for various parts @@ -314,14 +350,14 @@ section is marked as optional. You can require multiple approvals for the Code Owners sections under the Approval Rules area in merge requests. Append the section name with a number `n` in brackets. This requires `n` approvals from the Code Owners in this section. -Please note valid entries for `n` are integers `≥ 1`. `[1]` is optional as it is the default. Invalid values for `n` are treated as `1`. +Valid entries for `n` are integers `≥ 1`. `[1]` is optional because it is the default. Invalid values for `n` are treated as `1`. WARNING: [Issue #384881](https://gitlab.com/gitlab-org/gitlab/-/issues/385881) proposes changes to the behavior of this setting. Do not intentionally set invalid values. They may become valid in the future, and cause unexpected behavior. -Please confirm you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals will be optional. +Make sure you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals are optional. In this example, the `[Documentation]` section requires 2 approvals: @@ -337,7 +373,7 @@ The `Documentation` Code Owners section under the **Approval Rules** area displa  -### Allowed to Push +### Allowed to push Users who are **Allowed to push** can choose to create a merge request for their changes, or push the changes directly to a branch. If the user @@ -350,12 +386,15 @@ and release tooling. All changes from users _without_ the **Allowed to push** permission must be routed through a merge request. -## Technical Resources +## Related topics -[Code Owners development guidelines](../../../development/code_owners/index.md) +- [Syntax reference](reference.md) +- [Development guidelines](../../../development/code_owners/index.md) ## Troubleshooting +When working with Code Owners, you might encounter the following issues. + For more information about how the Code Owners feature handles errors, see the [Code Owners reference](reference.md). @@ -363,7 +402,8 @@ For more information about how the Code Owners feature handles errors, see the A Code Owner approval rule is optional if any of these conditions are true: -- The user or group are not a member of the project. Code Owners [cannot inherit from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). +- The user or group is not a member of the project. + Code Owners [cannot inherit members from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). - [Code Owner approval on a protected branch](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. - The section is [marked as optional](#make-a-code-owners-section-optional). @@ -383,7 +423,15 @@ if any of these conditions are true: member of the Code Owner group. - Current user is an external user who does not have permission to the internal Code Owner group. -### Approval rule is invalid. GitLab has approved this rule automatically to unblock the merge request +### Approval rule is invalid + +You might get an error that states: + +```plaintext +Approval rule is invalid. +GitLab has approved this rule automatically to unblock the merge request. +``` + +This issue occurs when an approval rule uses a Code Owner that is not a direct member of the project. -This message may appear if an approval rule uses a Code Owner that is not a direct member of the project. -Check that the group or user has been invited to the project. +The workaround is to check that the group or user has been invited to the project. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 395873d3107..91a3d71642d 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -21,7 +21,7 @@ type: howto, reference WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. [An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/2493) -to add this functionality to the [agent](../index.md). +to add this functionality to the [agent](../clusters/agent/index.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 `certificate_based_clusters`. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index f0d84616c24..c0a50dade31 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -64,7 +64,7 @@ Deploy keys work even if the user who created them is removed from the group or To view the deploy keys available to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. @@ -82,7 +82,7 @@ Prerequisites: - [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Add new key**. @@ -104,7 +104,7 @@ Prerequisites: To create a public deploy key: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Deploy Keys**. 1. Select **New deploy key**. @@ -122,7 +122,7 @@ Prerequisites: To grant a public deploy key access to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Publicly accessible deploy keys**. @@ -139,7 +139,7 @@ Prerequisites: To edit the project access permissions of a deploy key: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. In the key's row, select **Edit** (**{pencil}**). @@ -156,7 +156,7 @@ Prerequisites: To disable a deploy key: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Disable** (**{cancel}**). @@ -192,7 +192,7 @@ If you need to find the keys that belong to a non-member or blocked user, you can use [the Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) to identify unusable deploy keys using a script similar to the following: ```ruby -ghost_user_id = User.ghost.id +ghost_user_id = Users::Internal.ghost.id DeployKeysProject.with_write_access.find_each do |deploy_key_mapping| project = deploy_key_mapping.project diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 41fb0018be9..8b7e185508b 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deploy tokens **(FREE ALL)** -> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. - You can use a deploy token to enable authentication of deployment tasks, independent of a user account. In most cases you use a deploy token from an external host, like a build server or CI/CD server. @@ -92,7 +90,7 @@ Prerequisites: - You must have at least the Maintainer role for the project or group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. Select **Add token**. @@ -112,7 +110,7 @@ Prerequisites: To revoke a deploy token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4da49c4fb12..97b350c8692 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -16,7 +16,7 @@ You might want to use these templates: - For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - For every issue or merge request for a specific project, so the layout is consistent. -- For a [Service Desk email template](service_desk/index.md#use-a-custom-template-for-service-desk-tickets). +- For a [Service Desk email template](service_desk/configure.md#use-a-custom-template-for-service-desk-tickets). For description templates to work, they must be: @@ -32,7 +32,7 @@ directory in your repository. To create an issue description template: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -52,7 +52,7 @@ that depend on the contents of commit messages and branch names. To create a merge request description template for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -110,7 +110,7 @@ You can set a description template at the **instance level** for issues and merge requests by using an [instance template repository](../admin_area/settings/instance_template_repository.md). You can also use the instance template repository for file templates. -You might also be interested [project templates](../admin_area/custom_project_templates.md) +You might also be interested in [project templates](../admin_area/custom_project_templates.md) that you can use when creating a new project in the instance. ### Set group-level description templates **(PREMIUM ALL)** @@ -118,13 +118,18 @@ that you can use when creating a new project in the instance. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. -With **group-level** description templates, you can select a repository within the group to store -your templates. Then, you can access these templates from other projects in the group. +With **group-level** description templates, you can select a project within the group to store +your templates. Then, you can access these templates in other projects in the group. As a result, you can use the same templates in issues and merge requests in all the group's projects. +Prerequisites: + +- You must have the Owner role for the group. +- The project must be a direct child of the group. + To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Templates**. 1. From the dropdown list, select your template project as the template repository at group level. @@ -155,7 +160,7 @@ To set a default description template for merge requests, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Default description template for merge requests** section, fill in the text area. 1. Select **Save changes**. @@ -167,7 +172,7 @@ To set a default description template for issues, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Default description template for issues**. 1. Fill in the text area. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 88aa9446787..783f5f3ee7c 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -151,7 +151,7 @@ You can push files to GitLab whether they're locked or unlocked. NOTE: Although multi-branch file locks can be created and managed through the Git LFS -command line interface, file locks can be created for any file. +command-line interface, file locks can be created for any file. ### View exclusively-locked files @@ -221,7 +221,7 @@ similar functionality for locked files is discussed in To view and remove file locks: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Locked files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 0f612d5b222..bafcbbb9cbd 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -36,7 +36,7 @@ When importing: - [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. -- [Bitbucket Cloud import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your +- [Bitbucket Cloud import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. @@ -117,5 +117,5 @@ current Bitbucket public name, and reconnect if there's a mismatch: 1. Following reconnection, the user should use the API again to verify that their `extern_uid` in the GitLab database now matches their current Bitbucket public name. -The importer must then [delete the imported project](../../project/working_with_projects.md#delete-a-project) +The importer must then [delete the imported project](../../project/settings/index.md#delete-a-project) and import again. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index a80ce95c163..4afe23a29fa 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -32,7 +32,7 @@ You can import Bitbucket repositories to GitLab. > 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. -- [Bitbucket Server import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Bitbucket Server import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. @@ -87,6 +87,9 @@ original creator. The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the repository imports under the namespace of the user who started the import process. +The importer attempts to find reviewers by their email address in the GitLab user database. If they don't exist in GitLab, they cannot be added as reviewers to a +merge request. + ### User assignment by username > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default. diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index f5f924ef603..90ed6cfdb2c 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -39,10 +39,10 @@ The following list illustrates the main differences between CVS and Git: your state in version control, then you merge the other developer's changes. You can also ask the other developer to do the merge and resolve any conflicts themselves. -- **Signed commits.** Git supports signing your commits with GPG for additional +- **Signed commits.** Git supports + [signing your commits](../repository/signed_commits/index.md) for additional security and verification that the commit indeed came from its original author. - GitLab can [integrate with GPG](../repository/gpg_signed_commits/index.md) - and show whether a signed commit is correctly verified. + GitLab shows whether a signed commit is correctly verified. _Some of the items above were taken from this great [Stack Overflow post](https://stackoverflow.com/a/824241/974710). For a more diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 85c24886687..2bce6708556 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -19,7 +19,7 @@ users. > 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. -- [FogBugz import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [FogBugz import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The FogBugz import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 98457b96dde..9629ec03443 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -32,7 +32,7 @@ on the issue about the original Gitea author. > 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. - Gitea version 1.0.0 or later. -- [Gitea import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Gitea import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Gitea import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 2079c61da31..75d25e29bd9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -28,6 +28,9 @@ When importing projects: - If a user referenced in the project is not found in the GitLab database, the project creator is set as the author and assignee. The project creator is usually the user that initiated the import process. A note on the issue mentioning the original GitHub author is added. +- Reviewers assigned to GitHub pull requests that do not exist in GitLab are not imported. In this case, the import + creates comments describing that non-existent users were added as reviewers and approvers. However, the actual + reviewer status and approval are not applied to the merge request in GitLab. - You can change the target namespace and target repository name before you import. - The importer also imports branches on forks of projects related to open pull requests. These branches are imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to @@ -43,7 +46,7 @@ For an overview of the import process, see [How to migrate from GitHub to GitLab To import projects from GitHub: -- [GitHub import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [GitHub import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The GitHub import source is enabled by default on GitLab.com. - You must have at least the Maintainer role on the destination group to import to. @@ -55,12 +58,8 @@ To import projects from GitHub: When issues and pull requests are being imported, the importer attempts to find their GitHub authors and assignees in the database of the GitLab instance. Pull requests are called _merge requests_ in GitLab. For the importer to succeed, matching email addresses are required. -- GitHub accounts must have a GitHub public-facing email address is populated. This means all comments and contributions - are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you - may have to add it on existing accounts. - -Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383047), if you are using GitHub as an OmniAuth provider, ensure that the URL -perimeter is specified in the [OmniAuth configuration](../../../integration/github.md#enable-github-oauth-in-gitlab). +- GitHub accounts must have a GitHub public-facing email address so that all comments and contributions can be properly mapped to + the same user in GitLab. GitHub Enterprise does not require this field to be populated so you might have to add it on existing accounts. ### Importing from GitHub Enterprise to self-managed GitLab @@ -68,7 +67,7 @@ If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable the [GitHub integration](../../../integration/github.md). - GitHub must be enabled as an import source in the - [Admin Area](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [Admin Area](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources). - For GitLab 15.10 and earlier, you must add `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains). @@ -78,7 +77,17 @@ If you are importing from GitHub.com to a self-managed GitLab instance: - You don't need to enable the [GitHub integration](../../../integration/github.md). - GitHub must be enabled as an import source in the - [Admin Area](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [Admin Area](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources). + +### Known issues + +- GitHub pull request comments (known as diff notes in GitLab) created before 2017 are imported in separate threads. + This occurs because of a limitation of the GitHub API that doesn't include `in_reply_to_id` for comments before 2017. +- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383047), if you are using GitHub as an + OmniAuth provider, ensure that the URL perimeter is specified in the + [OmniAuth configuration](../../../integration/github.md#enable-github-oauth-in-gitlab). +- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/424400), Markdown attachments from + repositories on GitHub Enterprise Server instances aren't imported. ## Import your GitHub repository into GitLab @@ -288,10 +297,10 @@ When they are imported, supported GitHub branch protection rules are mapped to e | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | | **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | | **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | -| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | +| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM ALL)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | | **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | -| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | -| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | +| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM ALL)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) **(PREMIUM ALL)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index c1d6f5dbcbe..df831c2f3eb 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -41,7 +41,7 @@ with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate gro GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 433496ba6c9..aaf19439c24 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -19,7 +19,7 @@ repositories like the Android Open Source Project (AOSP). > 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. -- [Manifest import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Manifest import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Manifest import source is enabled by default on GitLab.com. - GitLab must use PostgreSQL for its database, because [subgroups](../../group/subgroups/index.md) are needed for the manifest import diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md deleted file mode 100644 index 7b9615b883c..00000000000 --- a/doc/user/project/import/phabricator.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -stage: Manage -group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' ---- - -# Import Phabricator tasks into a GitLab project (removed) **(FREE SELF)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106369) in GitLab 15.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117649) in 16.0. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5d23ee885bb..375cb718538 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -12,15 +12,15 @@ You can import your existing repositories by providing the Git URL. > 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. -- [Repository by URL import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Repository by URL import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Repository by URL import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. ## Import project by URL -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. On the right of the page, select **New project**. 1. Select the **Import project** tab. 1. Select **Repository by URL**. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 478e9c6bf1b..b60d87adbd3 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -134,7 +134,7 @@ Prerequisites: [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. On the left sidebar, select **Search or go to** and find your group. 1. In the upper-right corner, confirm that **New project** is visible. Contact your GitLab administrator if you require permission. diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 60b23540ac3..d8ad7f9a29c 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -24,7 +24,7 @@ Prerequisites: To view project insights: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Insights**. 1. To view a report, select the **Select report** dropdown list. @@ -52,7 +52,7 @@ To configure project insights, 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: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 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`. 1. In the large text box, update the file contents. diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 6005bc48d56..763f478eb99 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -29,7 +29,7 @@ An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.co GitLab supports enabling the Apple App Store integration at the project level. Complete these steps 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, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Apple App Store Connect**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index c73563ba162..442b8695136 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,7 +32,7 @@ In Asana, create a Personal Access Token. Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 9abbe75cc4c..242d5e6974c 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -36,7 +36,7 @@ integration in GitLab. ## Configure GitLab -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 048673cd4a2..febbee66c33 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,7 +14,7 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Bugzilla**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -39,7 +39,7 @@ project pages. This link takes you to the appropriate Bugzilla project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference Bugzilla issues in GitLab diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md index 7075aca28c2..dc93ff8ed06 100644 --- a/doc/user/project/integrations/clickup.md +++ b/doc/user/project/integrations/clickup.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use [ClickUp](https://clickup.com/) as an external issue tracker. To enable the ClickUp integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **ClickUp**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -34,7 +34,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference ClickUp issues in GitLab diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 54d092d2fa9..0a31e66fe96 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -20,7 +20,7 @@ on the left sidebar in your project. To enable a custom issue tracker in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 67f76d48744..29d92b16e32 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -28,7 +28,7 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 105061efba7..5c1130c7893 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -11,7 +11,7 @@ that is pushed to your project. To enable emails on push: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Emails on push**. 1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 7ee0306e7c0..831078e4e4b 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,7 +14,7 @@ This IBM product was [formerly named Rational Team Concert (RTC)](https://jazz.n To enable the EWM integration, in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **EWM**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 3f4b110468b..c368a9da2f6 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -29,7 +29,7 @@ Complete these steps on GitHub: Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **GitHub**. 1. Ensure the **Active** checkbox is selected. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index a082d9aa5be..d762c71242d 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -30,7 +30,7 @@ Although functionality has not changed, you should [reinstall the app](#update-t To install the GitLab for Slack app from project integration settings: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. Select **Install GitLab for Slack app**. @@ -55,7 +55,7 @@ When GitLab releases new features for the GitLab for Slack app, you might have t To update your GitLab for Slack app: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for +1. On the left sidebar, select **Search or go to** and find a project for which the GitLab for Slack app is configured. 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. @@ -105,7 +105,7 @@ The command returns an error if no matching action is found. By default, slash commands expect a project full path. To create a shorter project alias in the GitLab for Slack app: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. The current **Project Alias**, if any, is displayed. To edit this value, @@ -122,7 +122,7 @@ With Slack notifications, GitLab can send messages to Slack workspace channels f To configure Slack notifications: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for +1. On the left sidebar, select **Search or go to** and find a project for which the GitLab for Slack app is [installed](#install-the-gitlab-for-slack-app). 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. @@ -168,10 +168,19 @@ The following events are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | -| **Group mention in public** | A group is mentioned in a public context. | -| **Group mention in private** | A group is mentioned in a confidential context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in public** | A group is mentioned in a public context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | +### Trigger notifications for group mentions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417751) in GitLab 16.4. + +To trigger a [notification event](#notification-events) for a group mention, use `@<group_name>` in: + +- Issue and merge request descriptions +- Comments on issues, merge requests, and commits + ## Troubleshooting ### GitLab for Slack app does not appear in the list of integrations diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 696bb6acf99..1affa7abfb4 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -29,7 +29,7 @@ Prerequisites: To enable the Google Play integration in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Google Play**. 1. In **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 803984f82bf..9d6be5da810 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -25,7 +25,7 @@ In the Harbor instance, ensure that: GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Harbor**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 00ae1a0478c..59b5043b8f7 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -18,7 +18,7 @@ Prerequisites: To view the available integrations for your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. You can also view and manage integration settings across [all projects in an instance or group](../../admin_area/settings/project_integration_management.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index f5084392841..146123f97cd 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,7 +39,7 @@ network. For more details, read ## Complete these steps in GitLab -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 9e1de5e3aab..9588fbff922 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -41,7 +41,7 @@ Display name override is not enabled by default, you need to ask your administra After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Mattermost notifications**. 1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 4898d5bd337..715e744988c 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -31,7 +31,7 @@ you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/pla If Mattermost is installed on the same server as GitLab, you can automatically configure Mattermost slash commands: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. 1. Under **Enable integration**, ensure the **Active** checkbox is selected. @@ -67,7 +67,7 @@ To get configuration values from GitLab: 1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index b359696c72b..dea34709dff 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -35,7 +35,7 @@ After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: 1. Sign in to GitLab as an administrator. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Microsoft Teams notifications**. 1. To enable the integration, select **Active**. diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 3697e660deb..cd0a1819afd 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,7 +37,7 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md deleted file mode 100644 index c0b2591d824..00000000000 --- a/doc/user/project/integrations/prometheus.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: 'index.md' ---- - -# Prometheus (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md deleted file mode 100644 index e31f3b26e66..00000000000 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring AWS resources (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md deleted file mode 100644 index 4a0d324932b..00000000000 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring HAProxy (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md deleted file mode 100644 index 49345f41514..00000000000 --- a/doc/user/project/integrations/prometheus_library/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Prometheus Metrics library (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md deleted file mode 100644 index f5bbaffa58e..00000000000 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring Kubernetes (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md deleted file mode 100644 index e38f26710fc..00000000000 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring NGINX (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md deleted file mode 100644 index 189cf59a514..00000000000 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring NGINX Ingress Controller (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md deleted file mode 100644 index e4edd63314f..00000000000 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring NGINX Ingress Controller with VTS metrics (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index 218a036f0a2..3f1907d04cb 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -26,7 +26,7 @@ notifications: 1. To enable the integration for your group or project: 1. In your group or project, on the left sidebar, select **Settings > Integrations**. 1. To enable the integration for your instance: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index af2c7265f5d..a66aa9cd00a 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Redmine**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -38,7 +38,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index b2c85c8cb4c..aeddee29109 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -23,7 +23,7 @@ This change is a breaking change. To enable the Shimo integration for your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Shimo**. 1. Under **Enable integration**, ensure the **Active** checkbox is selected. @@ -36,7 +36,7 @@ On the left sidebar, **Shimo** now appears instead of **Wiki**. To view the Shimo Workspace from your group or project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 87d7476e42e..d48fd929d54 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -32,7 +32,7 @@ to control GitLab from Slack. Slash commands are configured separately. > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Slack notifications**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -79,10 +79,19 @@ The following triggers are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | -| **Group mention in public** | A group is mentioned in a public context. | -| **Group mention in private** | A group is mentioned in a confidential context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in public** | A group is mentioned in a public context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | +## Trigger notifications for group mentions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417751) in GitLab 16.4. + +To trigger a [notification event](#triggers-for-slack-notifications) for a group mention, use `@<group_name>` in: + +- Issue and merge request descriptions +- Comments on issues, merge requests, and commits + ## Troubleshooting If your Slack integration is not working, start troubleshooting by @@ -147,7 +156,7 @@ Commands that change data can cause damage if not run correctly or under the rig ```ruby # Grab all projects that have the Slack notifications enabled -p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations s ON p.id = s.project_id WHERE s.type_new = 'Slack' AND s.active = true") +p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations s ON p.id = s.project_id WHERE s.type_new = 'Integrations::Slack' AND s.active = true") # Disable the integration on each of the projects that were found. p.each do |project| diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 78c8180cb4c..67894e158c8 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -23,7 +23,7 @@ For a list of available slash commands, see [Slash commands](gitlab_slack_applic Slack slash commands are scoped to a project. To configure Slack slash commands: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Slack slash commands** and leave this browser tab open. 1. In a new browser tab, sign in to Slack and [add a new slash command](https://my.slack.com/services/new/slash-commands). diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md index ff633783e83..75849d61551 100644 --- a/doc/user/project/integrations/squash_tm.md +++ b/doc/user/project/integrations/squash_tm.md @@ -26,7 +26,7 @@ are synchronized as requirements in Squash TM and test progress is reported in G ## Configure GitLab -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Squash TM**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md index d68222d2f94..4e94ef76f58 100644 --- a/doc/user/project/integrations/telegram.md +++ b/doc/user/project/integrations/telegram.md @@ -40,10 +40,10 @@ After you invite the bot to a Telegram channel, you can configure GitLab to send 1. To enable the integration: - **For your group or project:** - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - **For your instance:** - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Telegram**. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index d59bfde5944..34f8cf262cd 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,7 +15,7 @@ copy its URL. In GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 370584303f8..b675ffa7a36 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -26,10 +26,10 @@ notifications: 1. To enable integration: - At the project or group level: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - At the instance level: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select the **Webex Teams** integration. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index c4dd8dcf812..269fdf304a8 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -988,7 +988,7 @@ Payload example: "draft": { "previous": true, "current": false - } + }, "updated_at": { "previous": "2017-09-15 16:50:55 UTC", "current":"2017-09-15 16:52:00 UTC" @@ -1026,7 +1026,7 @@ Payload example: "last_edited_by_id": { "previous": null, "current": 3278533 - }, + } }, "assignees": [ { @@ -1521,7 +1521,8 @@ Deployment events are triggered when a deployment: - Fails - Is cancelled -The `deployable_id` in the payload is the ID of the CI/CD job. +The `deployable_id` and `deployable_url` in the payload represent a CI/CD job that executed the deployment. +When the deployment event occurs by [API](../../../ci/environments/external_deployment_tools.md) or [`trigger` jobs](../../../ci/pipelines/downstream_pipelines.md), `deployable_url` is `null`. Request header: @@ -1879,12 +1880,13 @@ Payload example: ## Emoji events -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.3. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.4. 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 `emoji_webhooks`. -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 `emoji_webhooks`. On GitLab.com, this feature is available. NOTE: To have the `emoji_webhooks` flag enabled on GitLab.com, see [issue 417288](https://gitlab.com/gitlab-org/gitlab/-/issues/417288). diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index fe3d5e015a6..8e7f8bcd67d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -40,7 +40,7 @@ including: ## Group webhooks **(PREMIUM ALL)** You can configure a group webhook, which is triggered by events -that occur across all projects in the group. If you configure identical webhooks +that occur across all projects in the group and its subgroups. If you configure identical webhooks in a group and a project, they are both triggered by an event in the project. diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index 651c1a15b7a..c05083a1d83 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,7 +14,7 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **YouTrack**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -30,7 +30,7 @@ project pages. This link takes you to the appropriate YouTrack project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference YouTrack issues in GitLab diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 0b8f6cc33fc..60b50251555 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -32,7 +32,7 @@ When you create a confidential issue in a project, the project becomes listed in To create a confidential issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, at the top, select **Create new** (**{plus}**). 1. From the dropdown list, select **New issue**. 1. Complete the [fields](create_issues.md#fields-in-the-new-issue-form). @@ -43,7 +43,7 @@ To create a confidential issue: To change the confidentiality of an existing issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Select the title of your issue to view it. 1. On the right sidebar, next to **Confidentiality**, select **Edit**. diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 3014b088fd6..cd4ef43d333 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -28,7 +28,7 @@ Prerequisites: To create an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Either: - On the left sidebar, select **Plan > Issues**, and then, in the upper-right corner, select **New issue**. @@ -51,7 +51,7 @@ Prerequisites: To create an issue from a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Issues**. 1. In the upper-right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected @@ -98,7 +98,7 @@ Prerequisites: To create an issue from a project issue board: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issue boards**. 1. At the top of a board list, select **Create new issue** (**{plus-square}**). 1. Enter the issue's title. @@ -106,7 +106,7 @@ To create an issue from a project issue board: To create an issue from a group issue board: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Issue boards**. 1. At the top of a board list, select **Create new issue** (**{plus-square}**). 1. Enter the issue's title. @@ -130,7 +130,7 @@ Prerequisites: To email an issue to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. At the bottom of the page, select **Email a new issue to this project**. 1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index b3fe7da4280..882e4d97938 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -76,3 +76,10 @@ you can also [set an issue to close automatically](managing_issues.md#closing-is as soon as the merge request is merged.  + +## From branch names + +When you create a branch in the same project as an issue and start the branch name with the issue +number, followed by a hyphen, the issue and MR you create are linked. +For more information, see +[Prefix branch names with issue numbers](../repository/branches/index.md#prefix-branch-names-with-issue-numbers). diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 86370cab963..34a9b69038b 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,97 +1,102 @@ --- -stage: none -group: unassigned +stage: Plan +group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export issues to CSV **(FREE ALL)** -> Moved to GitLab Free in 12.10. - -You can export issues as CSV files from GitLab, which are sent to your default -notification email address as an attachment. - -**Export Issues to CSV** enables you and your team to export all the data -collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) -file, which stores tabular data in plain text. +You can export issues from GitLab to a plain-text CSV +([comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)) +file. The CSV file is attached to an email, and sent to your default +notification email address. <!-- vale gitlab.Spelling = NO --> -CSV files can be used with any plotter or spreadsheet-based program, such as -Microsoft Excel, Open Office Calc, or Google Sheets. +CSV files can be used with any plotter or spreadsheet-based program, like +Microsoft Excel, OpenOffice Calc, or Google Sheets. Use a CSV list of issues to: <!-- vale gitlab.Spelling = YES --> -Here are some of the uses of exporting issues as CSV files: - -- Make a snapshot of issues for offline analysis or to communicate with other - teams who may not be in GitLab. +- Create a snapshot of issues for offline analysis, or to share with other + teams who might not be in GitLab. - Create diagrams, graphs, and charts from the CSV data. -- Present the data in any other format for auditing or sharing reasons. -- Import the issues elsewhere to a system outside of GitLab. -- Long-term issues' data analysis with multiple snapshots created along the - time. +- Convert the data to other formats for auditing or sharing. +- Import the issues to a system outside of GitLab. +- Analyze long-term trends with multiple snapshots created over time. - Use the long-term data to gather relevant feedback given in the issues, and improve your product based on real metrics. -## Choosing which issues to include - -After selecting a project, from the issues page you can narrow down which -issues to export using the search bar, along with the All/Open/Closed tabs. All -issues returned are exported, including those not shown on the first page. +## Select issues to export - +You can export issues from individual projects, but not groups. -GitLab asks you to confirm the number of issues and email address for the -export, after which the email is prepared. +Prerequisites: - +- You must have at least the Reporter role. -## Sorting +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**. +1. Above the list of issues, select **Search or filter results...**. +1. In the dropdown list that appears, select the attributes to filter by. + For more information about filter options, see + [Filter the list of issues](managing_issues.md#filter-the-list-of-issues). +1. In the upper right, select **Actions** (**{ellipsis_v}**) **> Export as CSV**. +1. In the dialog, verify that the email address is correct, then select **Export issues**. -Exported issues are always sorted by `Title`. +All matching issues are exported, including those not shown on the first page. +The exported CSV does not contain attachments from issues. ## Format -Data is encoded with a comma as the column delimiter, with `"` used to quote -fields if needed, and newlines to separate rows. The first row contains the -headers, which are listed in the following table along with a description of -the values: - -| Column | Description | -|------------------------------------------|-----------------------------------------------------------| -| Title | Issue `title` | -| Description | Issue `description` | -| Issue ID | Issue `iid` | -| URL | A link to the issue on GitLab | -| State | `Open` or `Closed` | -| Author | Full name of the issue author | -| Author Username | Username of the author, with the `@` symbol omitted | -| Assignee | Full name of the issue assignee | -| Assignee Username | Username of the author, with the `@` symbol omitted | -| Confidential | `Yes` or `No` | -| Locked | `Yes` or `No` | -| Due Date | Formatted as `YYYY-MM-DD` | -| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Milestone | Title of the issue milestone | -| Weight | Issue weight | -| Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| [Epic](../../group/epics/index.md) ID | ID of the parent epic, introduced in 12.7 | -| [Epic](../../group/epics/index.md) Title | Title of the parent epic, introduced in 12.7 | - -In GitLab 14.7 and earlier, the first two columns were `Issue ID` and `URL`, -which [caused an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/34769) -when importing back into GitLab. - -## Limitations - -- Export Issues to CSV is not available at the Group's Issues List. -- Issues are sent as an email attachment, with a 15 MB export limit to ensure - successful delivery across a range of email providers. If you reach the limit, - we suggest narrowing the search before export, perhaps by exporting open and - closed issues separately. -- CSV files are plain text files. This means that the exported CSV file doesn't - contain any issue attachments. +The CSV file has this format: + +- Sort is by title. +- Columns are delimited with commas. +- Fields are quoted with double quotes (`"`) if needed. +- Newline characters separate rows. + +## Columns + +The following columns are included in the CSV file. + +| Column | Description | +|-------------------|-------------| +| Title | Issue `title` | +| Description | Issue `description` | +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| State | `Open` or `Closed` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | +| Assignee Username | Username of the author, with the `@` symbol omitted | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formatted as `YYYY-MM-DD` | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Labels, separated by commas | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| Epic ID | ID of the parent epic | +| Epic Title | Title of the parent epic | + +## Troubleshooting + +When working with exported issues, you might encounter the following issues. + +### Column order + +In GitLab 14.7 and earlier, the first two columns in exported files were `Issue ID` and `URL`, +which caused problems importing data back into GitLab. For more information, see +[issue 34769](https://gitlab.com/gitlab-org/gitlab/-/issues/34769). + +### Size of export + +Issues are sent as an email attachment, with a 15 MB export limit to ensure +successful delivery across a range of email providers. If you reach the limit, +narrow your search before export. For example, consider exporting open and +closed issues separately. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 4068083cd1e..0ea49ff387f 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -6,12 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Design management **(FREE ALL)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab 12.2. -> - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. -> - Design Management section in issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2, with a feature flag named `design_management_moved`. In earlier versions, designs were displayed in a separate tab. -> - Design Management section in issues [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) for new displays in GitLab 13.4. - With Design Management you can upload design assets (including wireframes and mockups) to GitLab issues and keep them stored in a single place. Product designers, product managers, and engineers can collaborate on designs with a single source of truth. @@ -29,7 +23,7 @@ For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube. - On self-managed instances, a GitLab administrator must [enable LFS globally](../../../administration/lfs/index.md). - On both GitLab.com and self-managed instances, LFS must be - [enabled for the project itself](../settings/index.md#configure-project-visibility-features-and-permissions). + [enabled for the project itself](../settings/index.md#configure-project-features-and-permissions). If enabled globally, LFS is enabled by default for all projects. If you have disabled it for your project, you must enable it again. @@ -58,7 +52,6 @@ You can upload files of the following types as designs: - JPEG - JPG - PNG -- SVG - TIFF - WEBP @@ -69,7 +62,7 @@ Support for PDF files is tracked in [issue 32811](https://gitlab.com/gitlab-org/ - Design Management data isn't deleted when: - [A project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429). - [An issue is deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427). -- In GitLab 12.7 and later, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) +- Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) and in GitLab 16.1 and later it can be [verified by Geo as well](https://gitlab.com/gitlab-org/gitlab/-/issues/355660). ## View a design @@ -106,9 +99,6 @@ a blue icon (**{file-modified-solid}**) is displayed. ### Zoom in on a design -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. -> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. - You can explore a design in more detail by zooming in and out of the image: - To control the amount of zoom, select plus (`+`) and minus (`-`) @@ -124,7 +114,7 @@ To move around the image while zoomed in, drag the image. Prerequisites: - You must have at least the Developer role for the project. -- In GitLab 13.1 and later, the names of the uploaded files must be no longer than 255 characters. +- The names of the uploaded files must be no longer than 255 characters. To add a design to an issue: @@ -163,6 +153,7 @@ Prerequisites: To do so, [add a design](#add-a-design-to-an-issue) with the same filename. To browse all the design versions, use the dropdown list at the top of the **Designs** section. +It's shown as either **Showing latest version** or **Showing version #N**. ### Skipped designs @@ -172,14 +163,19 @@ When designs are skipped, a warning message is displayed. ## Archive a design -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab 12.4. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/220964) the button from "Delete" to "Archive" in GitLab 13.3. - You can archive individual designs or select a few of them to archive at once. +Archived designs are not permanently lost. +You can browse [previous versions](#add-a-new-version-of-a-design). + +When you archive a design, its URL changes. +If the design isn't available in the latest version, you can link to it only with the version in the +URL. + Prerequisites: - You must have at least the Developer role for the project. +- You can archive only the latest version of a design. To archive a single design: @@ -192,15 +188,10 @@ To archive multiple designs at once: 1. Select the checkboxes on the designs you want to archive. 1. Select **Archive selected**. -NOTE: -Only the latest version of the designs can be archived. -Archived designs are not permanently lost. You can browse -[previous versions](#add-a-new-version-of-a-design). +## Markdown and rich text editors for descriptions <!-- When content_editor_on_issues flag is removed, move version notes - to "Add a design to an issue", update that topic, and delete the one below. --> - -## Markdown and rich text editors for descriptions + to "Add a design to an issue", update that topic, and delete this one. --> > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2. @@ -214,30 +205,28 @@ It's the same editor you use for comments across GitLab. ## Reorder designs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. - You can change the order of designs by dragging them to a new position. ## Add a comment to a design -> Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.8. - You can start [discussions](../../discussions/index.md) on uploaded designs. To do so: -<!-- vale gitlab.SubstitutionWarning = NO --> 1. Go to an issue. 1. Select the design. +<!-- vale gitlab.SubstitutionWarning = NO --> +<!-- Disable Vale so it doesn't catch "click" --> 1. Click or tap the image. A pin is created in that spot, identifying the discussion's location. +<!-- vale gitlab.SubstitutionWarning = YES --> 1. Enter your message. 1. Select **Comment**. -<!-- vale gitlab.SubstitutionWarning = YES --> -You can adjust a pin's position by dragging it around the image. You can use this when your design's -layout has changed, or when you want to move a pin to add a new one in its place. +You can adjust a pin's position by dragging it around the image. +Use this when your design's layout has changed, or to move a pin so you can add a new one in +its place. New discussion threads get different pin numbers, which you can use to refer to them. -In GitLab 12.5 and later, new discussions are output to the issue activity, +New discussions are output to the issue activity, so that everyone involved can participate in the discussion. ## Delete a comment from a design @@ -255,8 +244,6 @@ To delete a comment from a design: ## Resolve a discussion thread on a design -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. - When you're done discussing part of a design, you can resolve the discussion thread. To mark a thread as resolved or unresolved, either: @@ -272,16 +259,10 @@ To revisit a resolved discussion, expand **Resolved Comments** below the visible ## Add a to-do item for a design -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. - To add a [to-do item](../../todos.md) for a design, select **Add a to do** on the design sidebar. ## Refer to a design in Markdown -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in GitLab 13.1. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in GitLab 13.5. - To refer to a design in a [Markdown](../../markdown.md) text box in GitLab, for example, in a comment or description, paste its URL. It's then displayed as a short reference. @@ -297,9 +278,6 @@ It's rendered as: ## Design activity records -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33051) in GitLab 13.1. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/225205) in GitLab 13.2. - User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#access-your-user-profile), [group](../../group/manage.md#view-group-activity), @@ -307,8 +285,6 @@ and [project](../working_with_projects.md#view-project-activity) activity pages. ## GitLab-Figma plugin -> [Introduced](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/issues/2) in GitLab 13.2. - You can use the GitLab-Figma plugin to upload your designs from Figma directly to your issues in GitLab. @@ -316,3 +292,26 @@ To use the plugin in Figma, install it from the [Figma Directory](https://www.fi and connect to GitLab through a personal access token. For more information, see the [plugin documentation](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/wikis/home). + +## Troubleshooting + +When working with Design Management, you might encounter the following issues. + +### Could not find design + +You might get an error that states `Could not find design`. + +This issue occurs when a design has been [archived](#archive-a-design), +so it's not available in the latest version, and the link you've followed doesn't specify a version. + +When you archive a design, its URL changes. +If the design isn't available in the latest version, it can be linked to only with the version in the URL. + +For example, `https://gitlab.example.com/mygroup/myproject/-/issues/123456/designs/menu.png?version=503554`. +You can no longer access `menu.png` with `https://gitlab.example.com/mygroup/myproject/-/issues/123456/designs/menu.png`. + +The workaround is to select one of the previous versions from the dropdown list at the top of the +**Designs** section. +It's shown as either **Showing latest version** or **Showing version #N**. + +Issue [392540](https://gitlab.com/gitlab-org/gitlab/-/issues/392540) tracks improving this behavior. diff --git a/doc/user/project/issues/img/csv_export_button_v12_9.png b/doc/user/project/issues/img/csv_export_button_v12_9.png Binary files differdeleted file mode 100644 index 702b6439d7c..00000000000 --- a/doc/user/project/issues/img/csv_export_button_v12_9.png +++ /dev/null diff --git a/doc/user/project/issues/img/csv_export_modal.png b/doc/user/project/issues/img/csv_export_modal.png Binary files differdeleted file mode 100644 index f988deec966..00000000000 --- a/doc/user/project/issues/img/csv_export_modal.png +++ /dev/null diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 02cefaa47ef..cb3cbf5fc36 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -18,7 +18,7 @@ Prerequisites: To edit an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select the title of your issue to view it. 1. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the available fields. @@ -54,7 +54,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -88,7 +88,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -117,7 +117,7 @@ Prerequisites: To move an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 right sidebar, select **Move issue**. 1. Search for a project to move the issue to. @@ -138,7 +138,7 @@ Prerequisite: To move multiple issues at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to move. @@ -212,7 +212,7 @@ To close an issue, you can either: - In an [issue board](../issue_board.md), drag an issue card from its list into the **Closed** list. - From any other page in the GitLab UI: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 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. At the top of the issue, select **Close issue**. @@ -309,7 +309,7 @@ Prerequisites: To disable automatic issue closing: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Branch defaults**. 1. Clear the **Auto-close referenced issues on default branch** checkbox. @@ -357,7 +357,7 @@ Prerequisites: To change issue type: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the issue and select an issue type from the **Issue type** dropdown list: @@ -377,14 +377,14 @@ Prerequisites: To delete an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. Select **Delete issue**. Alternatively: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select the title of your issue to view it. 1. Select **Edit title and description** (**{pencil}**). 1. Select **Delete issue**. @@ -399,7 +399,7 @@ You can promote an issue to an [epic](../../group/epics/index.md) in the immedia To promote an issue to an epic: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. Select **Promote to epic**. @@ -422,7 +422,7 @@ You can use the `/promote_to_incident` [quick action](../quick_actions.md) to pr To add an issue to an [iteration](../../group/iterations/index.md): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 right sidebar, in the **Iteration** section, select **Edit**. 1. From the dropdown list, select the iteration to associate this issue with. @@ -434,7 +434,7 @@ Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#i To view all issues assigned to you: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). +1. On the left sidebar, select **Search or go to**. 1. From the dropdown list, select **Issues assigned to me**. Or: @@ -453,7 +453,7 @@ Or: To filter the list of issues: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Above the list of issues, select **Search or filter results...**. 1. In the dropdown list that appears, select the attribute you want to filter by. @@ -491,7 +491,7 @@ when you [filter the list of issues](#filter-the-list-of-issues) by: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. @@ -504,7 +504,7 @@ To refer to an issue elsewhere in GitLab, you can use its full URL or a short re To copy the issue reference to your clipboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 right sidebar, next to **Reference**, select **Copy Reference** (**{copy-to-clipboard}**). @@ -528,7 +528,7 @@ For more information about creating comments by sending an email and the necessa To copy the issue's email address: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**). @@ -545,7 +545,7 @@ themselves or another project member assigns them. To change the assignee on an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 right sidebar, in the **Assignee** section, select **Edit**. 1. From the dropdown list, select the user to add as an assignee. @@ -586,7 +586,7 @@ Prerequisites: To edit health status of an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 right sidebar, in the **Health status** section, select **Edit**. 1. From the dropdown list, select the status to add to this issue: diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 4daaaf72683..86d21d07950 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -69,7 +69,7 @@ You can also assign and unassign labels with [quick actions](quick_actions.md): To view the **project's labels**: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. Or: @@ -86,7 +86,7 @@ project or group path where it was created. To view the **group's labels**: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. Or: @@ -108,7 +108,7 @@ Prerequisites: To create a project label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -142,7 +142,7 @@ To do so: To create a group label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -182,7 +182,7 @@ Prerequisites: To edit a **project** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -190,7 +190,7 @@ To edit a **project** label: To edit a **group** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -208,7 +208,7 @@ Prerequisites: To delete a **project** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Either: @@ -221,7 +221,7 @@ To delete a **project** label: To delete a **group** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. 1. Either: @@ -251,7 +251,7 @@ Prerequisites: To promote a project label to a group label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. @@ -302,7 +302,7 @@ Prerequisites: To add the default labels to the project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Select **Generate a default set of labels**. @@ -441,7 +441,7 @@ Prerequisites: To prioritize a label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Next to a label you want to prioritize, select the star (**{star-o}**). diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 1e9bd307333..901a8fe9850 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -119,7 +119,7 @@ Prerequisite: To add a user to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Invite members**. 1. If the user: @@ -180,7 +180,7 @@ Prerequisites: To add a group to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Invite a group**. 1. Select a group. @@ -211,7 +211,7 @@ If the importing member's role in the target project is: To import users: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. @@ -236,7 +236,7 @@ Prerequisites: To remove a member from a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Next to the project member you want to remove, select **Remove member**. 1. Optional. On the confirmation dialog, select the @@ -273,7 +273,7 @@ You can filter and sort members in a project. ### Display inherited members -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. @@ -282,7 +282,7 @@ You can filter and sort members in a project. ### Display direct members -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press <kbd>Enter</kbd>. @@ -305,7 +305,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project you want to be a member of. +1. On the left sidebar, select **Search or go to** and find the project you want to be a member of. 1. By the project's name, select **Request Access**.  @@ -329,7 +329,7 @@ Prerequisite: - You must be the project owner. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. Under **Project visibility**, select **Users can request access**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 3780018bf11..deefe9040fa 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w When you want a group to have access to your project, you can invite [a group](../../group/index.md) to the project. -The group's members get access to the project, which becomes a *shared project*. +The group's direct and inherited members get access to the project, which becomes a *shared project*. ## Example @@ -53,11 +53,12 @@ must be at least as restrictive as that of the project. For example, you can inv > - [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. -You can share a project with a group by inviting that group to the project. +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. To invite a group to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Invite a group**. 1. **Select a group** you want to add to the project. @@ -99,7 +100,7 @@ For example, if a group member has the role of Developer, and the group is invit To view the maximum role assigned to a member: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. In the **Max role** column, view the user's maximum assigned role. @@ -109,7 +110,7 @@ In a group, a shared project is a project to which the group members gained acce To view a group's shared projects: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the group page, select the **Shared projects** tab. A list of shared projects is displayed. diff --git a/doc/user/project/merge_requests/ai_in_merge_requests.md b/doc/user/project/merge_requests/ai_in_merge_requests.md index c1aa729d8c5..304717cf9fc 100644 --- a/doc/user/project/merge_requests/ai_in_merge_requests.md +++ b/doc/user/project/merge_requests/ai_in_merge_requests.md @@ -34,8 +34,7 @@ Provide feedback on this experimental feature in [issue 416537](https://gitlab.c - Title of the merge request - Contents of the description -- Source branch name -- Target branch name +- Diff of changes between the source branch's head and the target branch ## Summarize merge request changes **(ULTIMATE SAAS)** diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index cbbeac17355..87ff6376ebd 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -89,17 +89,15 @@ To edit a merge request approval rule: ## Add multiple approval rules -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 11.10. - In GitLab Premium and Ultimate tiers, you can enforce multiple approval rules on a merge request, and multiple default approval rules for a project. If your tier supports multiple default rules: - When [adding](#add-an-approval-rule) or [editing](#edit-an-approval-rule) an approval rule - for a project, GitLab displays the **Add approval rule** button even after a rule is defined. + for a project, GitLab displays **Add approval rule**, even after a rule is defined. - When editing or overriding multiple approval rules [on a merge request](#edit-or-override-merge-request-approval-rules), GitLab - displays the **Add approval rule** button even after a rule is defined. + displays **Add approval rule**, even after a rule is defined. When an [eligible approver](#eligible-approvers) approves a merge request, it reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: @@ -111,8 +109,6 @@ For an overview, see [Multiple Approvers](https://www.youtube.com/watch?v=8JQJ58 ## Eligible approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. - To be eligible as an approver for a project, a user must be a member of one or more of these: @@ -140,15 +136,20 @@ users were not explicitly listed in the approval rules. ### Group approvers -You can add a group of users as approvers, but those users count as approvers only if -they have **direct membership** to the group. Inherited members do not count. Group approvers are -restricted to only groups [with share access to the project](../../members/share_project_with_groups.md). +You can add a group of users as approvers. All **direct members** of this group +can approve the rule. **Inherited members** cannot approve the rule. + +Typically the group is a subgroup in your top-level namespace, unless you are +collaborating with an external group. If you are collaborating with another group, +you must [share access to the project](../../members/share_project_with_groups.md) +before assigning the group as a group approver. A user's membership in an approvers group affects their individual ability to approve in these ways: -- A user already part of a group approver who is later added as an individual approver - counts as one approver, and not two. +- Inherited members are not considered approvers. Only direct members can approve merge requests. +- A user from a group approver group who is later _also_ added as an individual approver + counts as one approver, not two. - Merge request authors do not count as eligible approvers on their own merge requests by default. To change this behavior, disable the [**Prevent author approval**](settings.md#prevent-approval-by-author) @@ -157,6 +158,12 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-approvals-by-users-who-add-commits) project setting. +NOTE: +Creating multiple top-level groups to manage groups of users is not necessary, and is +discouraged because GitLab Free [is limited to 5 group members](https://about.gitlab.com/pricing/faq-efficient-free-tier/). +Managing groups of users using subgroups in your top-level namespace enables you +to use a single license. + ### Code owners as eligible approvers > Moved to GitLab Premium in 13.9. @@ -261,12 +268,9 @@ For more information, see [Coverage check approval rule](../../../../ci/testing/ ## Security Approvals **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. +> - Security approvals moved to merge request approvals settings [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. > - Bot comment for approvals [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411656) in GitLab 16.2 [with a flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. Enabled by default. - -FLAG: -On self-managed GitLab, by default the bot comment for approvals is available. To hide the feature, an administrator can [disable the feature flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. -On GitLab.com, the bot comment for approvals is available. +> - Bot comment for approvals [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130827) in GitLab 16.3. Feature flag `security_policy_approval_notification` removed. You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index b520ee41493..ae16eb2a790 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -65,6 +65,7 @@ this setting, unless you configure one of these options: > - Moved to GitLab Premium in 13.9. > - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127744) added in GitLab 16.3 to also include merge commits in this check. +> - [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](../../../admin_area/merge_requests_approvals.md), diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index ab882af7eda..18f19197f4c 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -158,7 +158,7 @@ rebases and file changes. To add a comment to a merge request file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. Select **Changes**. 1. In the header for the file you want to comment on, select **Comment** (**{comment}**). diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index d9b2ecf0806..ef1554f3b86 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -52,7 +52,7 @@ Commit `G` is added after the cherry-pick. After a merge request is merged, you can cherry-pick all changes introduced by the merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. 1. In the upper-right corner, select **Cherry-pick**: @@ -70,7 +70,7 @@ You can cherry-pick a single commit from multiple locations in your GitLab proje To cherry-pick a commit from the list of all commits for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Commits**. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. @@ -84,7 +84,7 @@ You can cherry-pick commits from any merge request in your project, regardless o whether the merge request is open or closed. To cherry-pick a commit from the list of commits included in a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. @@ -98,7 +98,7 @@ list of commits included in a merge request: You can cherry-pick from the list of previous commits affecting an individual file when you view that file in your project's Git repository: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository** and go to the file changed by the commit. 1. Select **History**, then select the [title](https://git-scm.com/docs/git-commit#_discussion) diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 1fc7188ffea..5ca097da29f 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -8,7 +8,7 @@ type: reference, howto # Commit message templates **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6. +> - Squash commit templates [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6. GitLab uses commit templates to create default messages for specific types of commits. These templates encourage commit messages to follow a particular format, @@ -29,7 +29,7 @@ Prerequisite: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Depending on the type of template you want to create, scroll to either [**Merge commit message template**](#default-template-for-merge-commits) or @@ -66,13 +66,13 @@ GitLab creates a squash commit message with this template: ## Supported variables in commit templates > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) `url`, `approved_by`, and `merged_by` variables in GitLab 14.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) `reviewed_by` variable in GitLab 15.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) `local_reference` variable in GitLab 16.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128553) `source_project_id` variables in GitLab 16.3. +> - `first_commit` and `first_multiline_commit` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) in GitLab 14.6. +> - `url`, `approved_by`, and `merged_by` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) in GitLab 14.7. +> - `co_authored_by` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) in GitLab 14.7. +> - `all_commits` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) in GitLab 14.9. +> - `reviewed_by` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) in GitLab 15.7. +> - `local_reference` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) in GitLab 16.1. +> - `source_project_id` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128553) in GitLab 16.3. Commit message templates support these variables: diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index ddd2a0ddcb5..502dfd7acab 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -18,7 +18,7 @@ From this tab, you can review commit messages and copy a commit's SHA when you n To see the commits included in a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, then select your merge request. 1. To show a list of the commits in the merge request, newest first, select **Commits** . To read more about the commit, select **Toggle commit description** (**{ellipsis_h}**) @@ -48,7 +48,7 @@ if another merge request: To add previously merged commits to a merge request for more context: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, then select your merge request. 1. Select **Commits**. 1. Scroll to the end of the list of commits, and select **Add previously merged commits**. @@ -63,7 +63,7 @@ force push. To add discussion to a specific commit: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Commits**. 1. Below the commits, in the **Comment** field, enter a comment. 1. Save your comment as either a standalone comment, or a thread: @@ -74,7 +74,7 @@ To add discussion to a specific commit: To view the changes between previously merged commits: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, then select your merge request. 1. Select **Changes**. 1. By **Compare** (**{file-tree}**), select the commits to compare: diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index fefc6aabddf..e132ddfb729 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -59,7 +59,7 @@ in the user interface, and you can also resolve conflicts locally through the co To resolve less-complex conflicts from the GitLab user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. @@ -84,7 +84,7 @@ Some merge conflicts are more complex, requiring you to manually modify lines to resolve their conflicts. Use the merge conflict resolution editor to resolve complex conflicts in the GitLab interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index e31460c1997..ec269bec84d 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -19,7 +19,7 @@ to streamline merge request creation. You can create a merge request from the list of merge requests. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. @@ -95,7 +95,7 @@ You can create a merge request when you add, edit, or upload a file to a reposit You can create a merge request when you create a branch. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Type a branch name and select **New branch**. 1. Above the file list, on the right side, select **Create merge request**. @@ -142,7 +142,7 @@ to reduce the need for editing merge requests manually through the UI. You can create a merge request from your fork to contribute back to the main project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your 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. @@ -171,7 +171,7 @@ Prerequisites: To create a merge request by sending an email: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -216,7 +216,7 @@ scenarios when you create a new merge request: 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, at the top, select **Search GitLab** (**{search}**) to find your project. +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. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 15b2e53d7d9..cc7fa050766 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -12,7 +12,7 @@ Export all the data collected from a project's merge requests into a comma-separ To export merge requests to a CSV file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index b80698f99c3..e208785fd63 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -57,7 +57,7 @@ information about the dependency: To view dependency information on a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area. Dependent merge requests display information about the total number of dependencies set, such as @@ -105,7 +105,7 @@ Prerequisite: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. In **Merge request dependencies**, paste either the reference or the full URL @@ -120,7 +120,7 @@ Prerequisite: - You must have a role in the project that allows you to edit merge requests. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. Scroll to **Merge request dependencies** and select **Remove** next to the reference diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 3ad07d0377e..ed762979ff1 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -46,7 +46,7 @@ You can view merge requests for your project, group, or yourself. To view all merge requests for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. @@ -55,7 +55,7 @@ Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd> To view merge requests for all projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Code > Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. @@ -64,7 +64,7 @@ If your group contains subgroups, this view also displays merge requests from th To view all merge requests assigned to you: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). +1. On the left sidebar, select **Search or go to**. 1. From the dropdown list, select **Merge requests assigned to me**. or: @@ -85,16 +85,16 @@ or: To filter the list of merge requests: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Above the list of merge requests, select **Search or filter results...**. 1. From the dropdown list, select the attribute you wish to filter by. Some examples: - [**By environment or deployment date**](#by-environment-or-deployment-date). - **ID**: Enter filter `#30` to return only merge request 30. - User filters: Type (or select from the dropdown list) any of these filters to display a list of users: - - **Approved-By**, for merge requests already approved by a user. **(PREMIUM)**. + - **Approved-By**, for merge requests already approved by a user. **(PREMIUM ALL)**. - **Approver**, for merge requests that this user is eligible to approve. - (For more information, read about [Code owners](../codeowners/index.md)). **(PREMIUM)** + (For more information, read about [Code owners](../codeowners/index.md)). **(PREMIUM ALL)** - **Reviewer**, for merge requests reviewed by this user. 1. Select or type the operator to use for filtering the attribute. The following operators are available: @@ -156,7 +156,7 @@ To assign the merge request to a user, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area in a merge request, or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit**. @@ -176,7 +176,7 @@ accountable for it: To assign multiple assignees to a merge request, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit** and, from the dropdown list, select all users you want @@ -312,7 +312,7 @@ On GitLab.com, this feature is enabled for GitLab team members only. To understand the history of a merge request, filter its activity feed to show you only the items that are relevant to you. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select a merge request. 1. Scroll to **Activity**. @@ -341,22 +341,7 @@ sort order by clicking the sort button on the right. > Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. -In a merge request, you can resolve a thread when you want to finish a conversation. - -Prerequisites: - -- You must have at least the Developer role - or be the author of the change being reviewed. -- Resolvable threads can be added only to merge requests. It doesn't work - for comments in issues, commits, or snippets. - -To resolve a thread: - -1. Go to the thread. -1. Do one of the following: - - In the upper-right corner of the original comment, select **Resolve thread** (**{check-circle}**). - - Below the last reply, in the **Reply** field, select **Resolve thread**. - - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. +In a merge request, you can [resolve a thread](../../discussions/index.md#resolve-a-thread) when you want to finish a conversation. At the top of the page, the number of unresolved threads is updated: @@ -390,7 +375,7 @@ You can prevent merge requests from being merged until all threads are resolved. When this setting is enabled, the **Unresolved threads** counter in a merge request is shown in orange when at least one thread remains unresolved. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Merge checks** section, select the **All threads must be resolved** checkbox. 1. Select **Save changes**. @@ -400,7 +385,7 @@ is shown in orange when at least one thread remains unresolved. You can set merge requests to automatically resolve threads when lines are modified with a new push. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Merge options** section, select **Automatically resolve merge request diff threads when they become outdated**. 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 16482d92d7e..77dcb269071 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -39,7 +39,7 @@ To do this when pushing from the command line, use the `merge_request.merge_when To do this from the GitLab user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select the merge request to edit. 1. Scroll to the merge request reports section. @@ -63,7 +63,7 @@ Prerequisites: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select the merge request to edit. 1. Scroll to the merge request reports section. @@ -79,7 +79,7 @@ merge. This configuration works for both: - GitLab CI/CD pipelines. - Pipelines run from an [external CI integration](../integrations/index.md#available-integrations). -As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md) +As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md#disable-cicd-in-a-project) does not disable this feature, but you can use pipelines from external CI providers with it. @@ -90,7 +90,7 @@ Prerequisites: To enable this setting: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Scroll to **Merge checks**, and select **Pipelines must succeed**. This setting also prevents merge requests from being merged if there is no pipeline, @@ -111,7 +111,7 @@ Prerequisite: To change this behavior: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Under **Merge checks**: - Select **Pipelines must succeed**. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 7eac0e8839a..959ada4928e 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -26,7 +26,7 @@ gitGraph ## Configure a project's merge method -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Select your desired **Merge method** from these options: - Merge commit diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 14e2ff84eae..7e6bf606f10 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -30,7 +30,7 @@ Prerequisites: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area, and find the report showing when the merge request was merged. @@ -55,7 +55,7 @@ Prerequisites: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. If you know the merge request that contains the commit: 1. Select **Code > Merge requests**, then identify and select your merge request. 1. Select **Commits**, then select the title of the commit you want to revert. This displays the commit in the **Changes** tab of your merge request. diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png Binary files differdeleted file mode 100644 index 70db0d79eaf..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v16_3.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v16_3.png Binary files differnew file mode 100644 index 00000000000..9c3ecebd395 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v16_3.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e4882134654..c09071e856c 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -10,7 +10,7 @@ type: index, reference [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) to propose changes. Your team leaves [comments](../../../discussions/index.md) on -your merge request, and makes [code suggestions](suggestions.md) you can accept +your merge request, and makes [Code Suggestions](suggestions.md) you can accept from the user interface. When your work is reviewed, your team members can choose to accept or reject it. @@ -21,17 +21,24 @@ 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). -## Suggested reviewers **(ULTIMATE SAAS)** +## GitLab Duo Suggested Reviewers **(ULTIMATE SAAS)** > - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/experiment-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/368356) in GitLab 15.6. > - Beta designation [removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113058) in GitLab 15.10. -GitLab can suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right sidebar. +GitLab uses machine learning to suggest reviewers for your merge request. - +To suggest reviewers, GitLab uses: -For more information, see [Data usage in Suggested Reviewers](data_usage.md). +- The changes in the merge request +- The project's contribution graph + +GitLab Duo Suggested Reviewers also integrates with Code Owners, profile status, and merge request rules, helping you make a more informed decision when choosing reviewers that can meet your review criteria. + + + +For more information, see [Data usage in GitLab Duo Suggested Reviewers](data_usage.md). ### Enable suggested reviewers @@ -73,11 +80,40 @@ If you [approve a merge request](../approvals/index.md#approve-a-merge-request) are shown in the reviewer list, a green check mark **{check-circle-filled}** displays next to your name. +### Request a review + +To assign a reviewer to a merge request, in a text area in +the merge request, use the `/assign_reviewer @user` +[quick action](../../quick_actions.md#issues-merge-requests-and-epics). Alternatively: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. On the right sidebar, in the **Reviewers** section, select **Edit**. +1. Search for the user you want to assign, and select the user. + +The merge request is added to the user's review requests. + +#### From multiple users **(PREMIUM ALL)** + +> Moved to GitLab Premium in 13.9. + +To assign multiple reviewers to a merge request, in a text area in +the merge request, use the `/assign_reviewer @user` +[quick action](../../quick_actions.md#issues-merge-requests-and-epics). Alternatively: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. On the right sidebar, in the **Reviewers** section, select **Edit**. +1. From the dropdown list, select all the users you want + to assign to the merge request. + +To remove a reviewer, clear the user from the same dropdown list. + ### Download merge request changes as a diff To download the changes included in a merge request as a diff: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Plain diff**. @@ -100,7 +136,7 @@ curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff" | git a To download the changes included in a merge request as a patch file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Patches**. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 4857d58933a..2b046399c4e 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -14,7 +14,7 @@ merge request, authored by the user who suggested the changes. ## Create suggestions -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. On the secondary menu, select **Changes**. 1. Find the lines of code you want to change. @@ -92,7 +92,7 @@ Prerequisites: To apply suggested changes directly from the merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. Find the comment containing the suggestion you want to apply. - To apply suggestions individually, select **Apply suggestion**. @@ -140,7 +140,7 @@ Merge requests created from forks use the template defined in the target project To meet your project's needs, you can customize these messages and include other placeholder variables: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Scroll to **Merge suggestions**, and alter the text to meet your needs. See [Supported variables](#supported-variables) for a list of placeholders @@ -172,7 +172,7 @@ For example, to customize the commit message to output To reduce the number of commits added to your branch, you can apply multiple suggestions in a single commit. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. For each suggestion you want to apply, and select **Add suggestion to batch**. 1. Optional. To remove a suggestion, select **Remove from batch**. diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index ea999fe039a..a6d55ee44e2 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -71,7 +71,7 @@ Prerequisites: To configure the default squashing behavior for all merge requests in your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Squash commits when merging** section, select your desired behavior: - **Do not allow**: Squashing is never performed, and the option is not displayed. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index e0e65c99433..f87d379b974 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -36,7 +36,7 @@ see [epic 3869](https://gitlab.com/groups/gitlab-org/-/epics/3869). By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Select the **Status checks must succeed** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 7c9a5a37292..65cc9477c49 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -13,7 +13,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Burndown charts -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to GitLab 11.2 for group milestones. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in GitLab 13.6. > - Moved to GitLab Premium in 13.9. @@ -32,13 +31,13 @@ For an overview, check the video demonstration on [Mapping work versus time with To view a project's burndown chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. To view a group's burndown chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. @@ -112,13 +111,13 @@ Burnup charts show the assigned and completed work for a milestone. To view a project's burnup chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. To view a group's burnup chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 4bb751aedc5..328e56e2bd8 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -37,7 +37,7 @@ For information about project and group milestones API, see: To view the milestone list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. In a project, GitLab displays milestones that belong to the project. @@ -46,7 +46,7 @@ In a group, GitLab displays milestones that belong to the group and all projects ### View milestones in a project with issues turned off If a project has issue tracking -[turned off](../settings/index.md#configure-project-visibility-features-and-permissions), +[turned off](../settings/index.md#configure-project-features-and-permissions), to get to the milestones page, enter its URL. To do so: @@ -66,7 +66,7 @@ You might not see some milestones because they're in projects or groups you're n To do so: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. On the left sidebar, select **Milestones**. @@ -121,7 +121,7 @@ Prerequisites: To create a milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. 1. Select **New milestone**. 1. Enter the title. @@ -140,7 +140,7 @@ Prerequisites: To edit a milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +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**. @@ -157,7 +157,7 @@ Prerequisites: To edit a milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +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**. @@ -183,7 +183,7 @@ Prerequisites: To promote a project milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Milestones**. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**) next to the milestone you want to promote. diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index d4516746afc..0aad9a69743 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -70,7 +70,7 @@ on how to use GitLab as a backend for the MLflow Client. To list the current active experiments, either go to `https/-/ml/experiments` or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Model experiments**. 1. To display all candidates that have been logged, along with their metrics, parameters, and metadata, select an experiment. 1. To display details for a candidate, select **Details**. diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md index 3e78cc5b7f2..9cedb5780ed 100644 --- a/doc/user/project/ml/experiment_tracking/mlflow_client.md +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -24,7 +24,7 @@ Prerequisites: - A [personal](../../../../user/profile/personal_access_tokens.md), [project](../../../../user/project/settings/project_access_tokens.md), or [group](../../../../user/group/settings/group_access_tokens.md) access token with at least the Developer role and the `api` permission. - The project ID. To find the project ID: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. To use MLflow client compatibility from a local environment: @@ -83,6 +83,7 @@ tested. More information can be found in the [MLflow Documentation](https://www. | `set_experiment` | Yes | 15.11 | | | `get_run` | Yes | 15.11 | | | `start_run` | Yes | 15.11 | (16.3) If a name is not provided, the candidate receives a random nickname. | +| `search_runs` | Yes | 15.11 | (16.4) `experiment_ids` supports only a single experiment ID with order by column or metric. | | `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty. Does not support directories. | | `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty. Does not support directories. | | `log_batch` | Yes | 15.11 | | 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 8bf4875ba1e..d8e4fce41ef 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 @@ -43,7 +43,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, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. In the upper-right corner, select **New Domain**. 1. In **Domain**, enter the domain name. @@ -113,7 +113,7 @@ Subdomains (`subdomain.example.com`) require: Whether it's a user or a project website, the DNS record should point to your Pages domain (`namespace.gitlab.io`), -without any `/project-name`. +without any path.  @@ -154,7 +154,7 @@ If you're using Cloudflare, check After you have added all the DNS records: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). @@ -246,7 +246,7 @@ meet these requirements. - To add the certificate at the time you add a new domain: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. In the upper-right corner, select **New Domain**. 1. In **Domain**, enter the domain name. @@ -255,7 +255,7 @@ meet these requirements. - To add the certificate to a domain previously added: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. 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). @@ -283,7 +283,7 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Select the **Force HTTPS (requires valid certificates)** checkbox. 1. Select **Save changes**. @@ -303,7 +303,7 @@ You can edit a custom domain to: To edit a custom domain: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. @@ -313,7 +313,7 @@ After a custom domain is deleted, the domain is no longer verified in GitLab and To delete and remove a custom domain: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Deploy > Pages**. 1. Next to the domain name, select **Remove**. 1. When prompted, select **Remove domain**. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 5c1fc41d947..3d9fe4b04e9 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,7 +42,7 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. Turn on the **Automatic certificate management using Let's Encrypt** toggle. @@ -69,7 +69,7 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). @@ -84,7 +84,7 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Remove**. 1. [Add the domain again, and verify it](index.md#1-add-a-custom-domain). diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index f8ee3f10d1e..90fc1a72eb3 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -16,7 +16,7 @@ Use a `.gitlab-ci.yml` template when you have an existing project that you want Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may have to do additional configuration for the Pages site to generate properly. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the **Add** (**{plus}**) dropdown list, select **New file**. 1. From the **Select a template type** dropdown list, select `.gitlab-ci.yml`. 1. From the **Apply a template** dropdown list, in the **Pages** section, select the name of your SSG. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index ab3c12427b3..8fa927bd61c 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -33,7 +33,7 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. A **Get Started with Pages** form appears. If this form is not available, diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index e44a7bf347f..ec511ee0a5f 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -25,13 +25,13 @@ For GitLab self-managed instances, replace `example.io` with your instance's Pages domain. For GitLab.com, Pages domains are `*.gitlab.io`. -| Type of GitLab Pages | The name of the project created in GitLab | Website URL | +| Type of GitLab Pages | Example path of a project in GitLab | Website URL | | -------------------- | ------------ | ----------- | -| User pages | `username.example.io` | `http(s)://username.example.io` | -| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` | -| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` | -| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| -| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| +| User pages | `username/username.example.io` | `http(s)://username.example.io` | +| Group pages | `acmecorp/acmecorp.example.io` | `http(s)://acmecorp.example.io` | +| Project pages owned by a user | `username/my-website` | `http(s)://username.example.io/my-website` | +| Project pages owned by a group | `acmecorp/webshop` | `http(s)://acmecorp.example.io/webshop`| +| Project pages owned by a subgroup | `acmecorp/documentation/product-manual` | `http(s)://acmecorp.example.io/documentation/product-manual`| WARNING: There are some known [limitations](introduction.md#subdomains-of-subdomains) @@ -72,7 +72,7 @@ To understand Pages domains clearly, read the examples below. **General example:** - On GitLab.com, a project site is always available under - `https://namespace.gitlab.io/project-name` + `https://namespace.gitlab.io/project-slug` - On GitLab.com, a user or group website is available under `https://namespace.gitlab.io/` - On your GitLab instance, replace `gitlab.io` above with your @@ -86,7 +86,7 @@ The `baseurl` option might be named differently in some static site generators. Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, -whenever you publish a project website (`namespace.gitlab.io/project-name`), +whenever you publish a project website (for example, `namespace.gitlab.io/project-slug`), you must look for this configuration (base URL) on your static site generator's documentation and set it up to reflect this pattern. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 4585ee2cecd..664c80e0351 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -47,9 +47,9 @@ depending on your static generator configuration. If the case of `404.html`, there are different scenarios. For example: -- If you use project Pages (served under `/projectname/`) and try to access - `/projectname/non/existing_file`, GitLab Pages tries to serve first - `/projectname/404.html`, and then `/404.html`. +- If you use project Pages (served under `/project-slug/`) and try to access + `/project-slug/non/existing_file`, GitLab Pages tries to serve first + `/project-slug/404.html`, and then `/404.html`. - If you use user or group Pages (served under `/`) and try to access `/non/existing_file` GitLab Pages tries to serve `/404.html`. - If you use a custom domain and try to access `/non/existing_file`, GitLab @@ -64,7 +64,7 @@ You can configure redirects for your site using a `_redirects` file. For more in To remove your pages: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Select **Remove pages**. @@ -87,7 +87,7 @@ For [group websites](../../project/pages/getting_started_part_one.md#user-and-gr the group must be at the top level and not a subgroup. For [project websites](../../project/pages/getting_started_part_one.md#project-website-examples), -you can create your project first and access it under `http(s)://namespace.example.io/projectname`. +you can create your project first and access it under `http(s)://namespace.example.io/project-path`. ## Enable unique domains @@ -99,7 +99,7 @@ By default, every project in a group shares the same domain, for example, `group To ensure your project uses a unique Pages domain, enable the unique domains feature for the project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Select the **Use unique domain** checkbox. 1. Select **Save changes**. @@ -308,7 +308,7 @@ For a list of known issues, see the GitLab [public issue tracker](https://gitlab This problem most likely results from a missing `index.html` file in the public directory. If after deploying a Pages site a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name -such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`. +such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-slug/test.html`. The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts) from the latest pipeline. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 5f1f5bc59ae..ff1f138e5b7 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -47,14 +47,14 @@ To create redirects, create a configuration file named `_redirects` in the configured at the instance level. Only the first matching rules within the configured maximum are processed. The default file size limit is 64 KB, and the default maximum number of rules is 1,000. - If your GitLab Pages site uses the default domain name (such as - `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: + `namespace.gitlab.io/project-slug`) you must prefix every rule with the path: ```plaintext - /projectname/wardrobe.html /projectname/narnia.html 302 + /project-slug/wardrobe.html /project-slug/narnia.html 302 ``` - If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), - no project name prefix is needed. For example, if your custom domain is `example.com`, + no project path prefix is needed. For example, if your custom domain is `example.com`, your `_redirects` file would look like: ```plaintext @@ -69,7 +69,7 @@ the file instead of your redirect. For example, if the files `hello.html` and is ignored because `hello.html` exists: ```plaintext -/projectname/hello.html /projectname/world.html 302 +/project-slug/hello.html /project-slug/world.html 302 ``` GitLab does not support Netlify @@ -210,8 +210,7 @@ would **not** match a request URL like `/old/file`: ## Debug redirect rules If a redirect isn't working as expected, or you want to check your redirect syntax, visit -`https://[namespace.gitlab.io]/projectname/_redirects`, replacing `[namespace.gitlab.io]` with -your domain name. The `_redirects` file isn't served directly, but your browser +`[your pages url]/_redirects`. The `_redirects` file isn't served directly, but your browser displays a numbered list of your redirect rules, and whether the rule is valid or invalid: ```plaintext diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 505f1a530cd..fac07a1313a 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -95,7 +95,7 @@ Prerequisites: To protect a branch: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -133,7 +133,7 @@ Prerequisite: To protect a branch for all the projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -157,7 +157,7 @@ Prerequisite: To protect multiple branches at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -193,7 +193,7 @@ from the command line or from a Git client application. To create a new branch through the user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Select **New branch**. 1. Fill in the branch name and select an existing branch, tag, or commit to @@ -205,7 +205,7 @@ To create a new branch through the user interface: You can force everyone to submit a merge request, rather than allowing them to check in directly to a protected branch: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -218,7 +218,7 @@ check in directly to a protected branch: You can allow everyone with write access to push to the protected branch. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -247,7 +247,7 @@ Prerequisites: To allow a deploy key to push to a protected branch: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -267,7 +267,7 @@ protected branches. To protect a new branch and enable force push: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -280,7 +280,7 @@ To protect a new branch and enable force push: To enable force pushes on branches that are already protected: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -322,7 +322,7 @@ the applicable rules have **Required approval from code owners** enabled. To protect a new branch and enable Code Owner's approval: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -333,7 +333,7 @@ To protect a new branch and enable Code Owner's approval: To enable Code Owner's approval on branches that are already protected: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -366,7 +366,7 @@ for details about the pipelines security model. Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, enter the branch name and select **Yes, delete protected branch**. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 8686d02271c..b312acd49f4 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -31,7 +31,7 @@ Prerequisites: - You must have at least the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected tags**. 1. Select **Add new**. @@ -77,7 +77,9 @@ all matching tags: A tag and a branch with identical names can contain different commits. If your tags and branches use the same names, users running `git checkout` commands might check out the _tag_ `qa` when they instead meant to check out -the _branch_ `qa`. +the _branch_ `qa`. As an added security measure, avoid creating tags with the +same name as branches. Confusing the two could lead to potential +security or operational issues. To prevent this problem: @@ -111,7 +113,7 @@ Prerequisites: To allow a deploy key to create a protected tag: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected tags**. 1. From the **Tag** dropdown list, select the tag you want to protect. @@ -129,7 +131,7 @@ Prerequisite: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Tags**. 1. Next to the tag you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, enter the tag name and select **Yes, delete protected tag**. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index d0a938e054d..e8451e3049d 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -6,119 +6,97 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Push options **(FREE ALL)** -GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) -to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. +When you push changes to a branch, you can use client-side +[Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt). +In Git 2.10 and later, use Git push options to: -Currently, there are push options available for: +- [Skip CI jobs](#push-options-for-gitlab-cicd) +- [Push to merge requests](#push-options-for-merge-requests) -- [Skipping CI jobs](#push-options-for-gitlab-cicd) -- [Merge requests](#push-options-for-merge-requests) - -NOTE: -Git push options are only available with Git 2.10 or newer. - -For Git versions 2.10 to 2.17 use `--push-option`: +In Git 2.18 and later, you can use either the long format (`--push-option`) or the shorter `-o`: ```shell -git push --push-option=<push_option> +git push -o <push_option> ``` -For version 2.18 and later, you can use the above format, or the shorter `-o`: +In Git 2.10 to 2.17, you must use the long format: ```shell -git push -o <push_option> +git push --push-option=<push_option> ``` +For server-side controls and enforcement of best practices, see +[push rules](repository/push_rules.md) and [server hooks](../../administration/server_hooks.md). + ## Push options for GitLab CI/CD You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. -| Push option | Description | Introduced in version | -| ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | -| `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI integrations, such as Jenkins. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | -| `integrations.skip_ci` | Skip push events for CI integrations, such as Atlassian Bamboo, Buildkite, Drone, Jenkins, and JetBrains TeamCity. | [16.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123837) | +| Push option | Description | Example | +|--------------------------------|-------------|---------| +| `ci.skip` | Do not create a CI/CD pipeline for the latest push. Skips only branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI/CD integrations, such as Jenkins. | `git push -o ci.skip` | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to the CI/CD pipeline, if one is created due to the push. Passes variables only to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | `git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600"` | +| `integrations.skip_ci` | Skip push events for CI/CD integrations, such as Atlassian Bamboo, Buildkite, Drone, Jenkins, and JetBrains TeamCity. Introduced in [GitLab 16.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123837). | `git push -o integrations.skip_ci` | -An example of using `ci.skip`: - -```shell -git push -o ci.skip -``` - -An example of passing some CI/CD variables for a pipeline: - -```shell -git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600" -``` +## Push options for merge requests -An example of using `integrations.skip_ci`: +Git push options can perform actions for merge requests while pushing changes: -```shell -git push -o integrations.skip_ci -``` +| Push option | Description | +|----------------------------------------------|-------------| +| `merge_request.create` | Create a new merge request for the pushed branch. | +| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch or upstream project, such as: `git push -o merge_request.target=project_path/branch`. | +| `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | +| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | +| `merge_request.title="<title>"` | Set the title of the merge request. For example: `git push -o merge_request.title="The title I want"`. | +| `merge_request.description="<description>"` | Set the description of the merge request. For example: `git push -o merge_request.description="The description I want"`. | +| `merge_request.draft` | Mark the merge request as a draft. For example: `git push -o merge_request.draft`. Introduced in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/296673). | +| `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. For example: `git push -o merge_request.milestone="3.0"`. Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960). | +| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | +| `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | +| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. Support for usernames added in [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276). | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. Support for usernames added in [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276). | -## Push options for merge requests +## Formats for push options -You can use Git push options to perform certain actions for merge requests at the same -time as pushing changes: - -| Push option | Description | Introduced in version | -| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------- | -| `merge_request.create` | Create a new merge request for the pushed branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch or upstream project, such as: `git push -o merge_request.target=project_path/branch` | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.title="<title>"` | Set the title of the merge request. For example: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.description="<description>"` | Set the description of the merge request. For example: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.draft` | Mark the merge request as a draft. For example: `git push -o merge_request.draft`. | [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/296673) | -| `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. For example: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | -| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904), support for usernames added in [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276) | -| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID.For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904), support for usernames added in [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276) | - -If you use a push option that requires text with spaces in it, you need to enclose it -in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: +If your push option requires text containing spaces, enclose the text in +double quotes (`"`). You can omit the quotes if there are no spaces. Some examples: ```shell git push -o merge_request.label="Label with spaces" git push -o merge_request.label=Label-with-no-spaces ``` -You can combine push options to accomplish multiple tasks at once, by using -multiple `-o` (or `--push-option`) flags. For example, if you want to create a new -merge request, and target a branch named `my-target-branch`: +To combine push options to accomplish multiple tasks at once, use +multiple `-o` (or `--push-option`) flags. This command creates a +new merge request, targets a branch (`my-target-branch`), and sets auto-merge: ```shell -git push -o merge_request.create -o merge_request.target=my-target-branch +git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds ``` -Additionally if you want the merge request to merge as soon as the pipeline succeeds you can do: +## Create Git aliases for common commands -```shell -git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds -``` +Adding push options to Git commands can create very long commands. If +you use the same push options frequently, create Git aliases for them. +Git aliases are command-line shortcuts for longer Git commands. -## Useful Git aliases +To create and use a Git alias for the +[merge when pipeline succeeds Git push option](#push-options-for-merge-requests): -As shown above, Git push options can cause Git commands to grow very long. If -you use the same push options frequently, it's useful to create -[Git aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases). Git aliases -are command line shortcuts for Git which can significantly simplify the use of -long Git commands. +1. In your terminal window, run this command: -### Merge when pipeline succeeds alias + ```shell + git config --global alias.mwps "push -o merge_request.create -o merge_request.target=main -o merge_request.merge_when_pipeline_succeeds" + ``` -To set up a Git alias for the -[merge when pipeline succeeds Git push option](#push-options-for-merge-requests): +1. To use the alias to push a local branch that targets the default branch (`main`) + and auto-merges, run this command: -```shell -git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds" -``` + ```shell + git mwps origin <local-branch-name> + ``` -Then to quickly push a local branch that targets the default branch and merges when the -pipeline succeeds: +## Related topics -```shell -git mwps origin <local-branch-name> -``` +- [Git aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases) in the Git documentation diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index aee052631fc..097c726d163 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -146,10 +146,13 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do |:--------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| | `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign one or more users. | | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign yourself. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412275) in GitLab 16.5 | | `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. | +| `/checkin_reminder` | **{dotted-circle}** No| **{check-circle}** Yes | **{dotted-circle}** No | Set checkin reminder cadence. Options are `weekly`, `twice-monthly`, `monthly`, `never`. This action is behind a feature flag. | | `/clear_health_status` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | | `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | | `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/confidential` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark work item as confidential. [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412276) in GitLab 16.4. | | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. | | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/health_status <value>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, or `at_risk`. | @@ -160,6 +163,7 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Remove due date. | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 | | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. | @@ -168,6 +172,7 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | Remove all assignees. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | | `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 | | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 8e65514cd1d..17ea0e3f694 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -74,7 +74,7 @@ Prerequisites: To create a release in the Releases page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown list, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release @@ -215,7 +215,7 @@ To delete a release, use either the In the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Releases**. 1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). @@ -287,22 +287,40 @@ are defined as [crontab](https://crontab.guru/) entries. If the job that's executing is in a freeze period, GitLab CI/CD creates an environment variable named `$CI_DEPLOY_FREEZE`. -To prevent the deployment job from executing, create a `rules` entry in your -`.gitlab-ci.yml`, for example: +To prevent the deployment job from executing in multiple projects in a group, +define the `.freezedeployment` job in a file shared across the group. +Use the [`includes`](../../../ci/yaml/includes.md) keyword to incorporate the +template in your project's `.gitlab-ci.yml` file: ```yaml -deploy_to_production: +.freezedeployment: stage: deploy - script: deploy_to_prod.sh + before_script: + - '[[ ! -z "$CI_DEPLOY_FREEZE" ]] && echo "INFRASTRUCTURE OUTAGE WINDOW" && exit 1; ' rules: - - if: $CI_DEPLOY_FREEZE == null + - if: '$CI_DEPLOY_FREEZE' + when: manual + allow_failure: true + - when: on_success +``` + +To prevent the deployment job from executing, use the [`extends`](../../../ci/yaml/index.md#extends) keyword in the `deploy_to_production` job of your `.gitlab-ci.yml` file to inherit the configuration from the `.freezedeployment` template job: + +```yaml +deploy_to_production: + extends: .freezedeployment + script: deploy_to_prod.sh environment: production ``` +This configuration blocks deployment jobs conditionally and maintains pipeline continuity. When a freeze period is defined, the job fails and the pipeline can proceed without deployment. Manual deployment is possible after the freeze period. + +This approach offers deployment control during critical maintenance, and ensures the uninterrupted flow of the CI/CD pipeline. + To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with the Maintainer role. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Select **Expand** to see the deploy freeze table. @@ -342,7 +360,7 @@ Releases can be made accessible to non-project members while keeping repository- projects that use releases as a way to give access to new versions of software but do not want the source code to be public. -To make releases available publicly, set the following [project settings](../settings/index.md#project-feature-settings): +To make releases available publicly, set the following [project settings](../settings/index.md#configure-project-features-and-permissions): - Repository is enabled and set to **Only Project Members** - Releases is enabled and set to **Everyone With Access** diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index e1de9cbdc1c..9daa6705ad8 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Release CLI tool -The [GitLab Release CLI (`release-cli`)](https://gitlab.com/gitlab-org/release-cli) tool +The [GitLab Release CLI (`release-cli`)](https://gitlab.com/gitlab-org/release-cli) is a command-line tool for managing releases from the command line or from a CI/CD pipeline. You can use the release CLI to create, update, modify, and delete releases. diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index ec3d63462f3..6bbc0b8123a 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://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Connect a remote machine to the Web IDE (Beta) **(FREE ALL)** +# Tutorial: Connect a remote machine to the Web IDE **(FREE ALL BETA)** > - [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. diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 16110af984a..8ca505be500 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://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Remote development (Beta) **(FREE ALL)** +# Remote development **(FREE ALL BETA)** > - [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. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index e123debb724..fdc822ca49f 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -42,7 +42,7 @@ Prerequisites: To update the default branch for an individual [project](../../index.md): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Branch defaults**. For **Default branch**, select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close @@ -68,7 +68,7 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. @@ -85,7 +85,7 @@ overrides it. Users with the Owner role of groups and subgroups can configure the default branch name for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. @@ -128,7 +128,7 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. @@ -146,7 +146,7 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand the **Default branch** section. @@ -167,7 +167,7 @@ can be overridden on a per-group basis by the group's owner. In [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index f7445ffe950..f33d443cd7f 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -11,7 +11,7 @@ Branches are versions of a project's working tree. When you create a new cannot be deleted) for your repository. Default branch settings can be configured at the project, subgroup, group, or instance level. -As your project grows, your team [creates](../web_editor.md#create-a-branch) more +As your project grows, your team creates more branches, preferably by following [branch naming patterns](#prefix-branch-names-with-issue-numbers). Each branch represents a set of changes, which allows development work to be done in parallel. Development work in one branch does not affect another branch. @@ -27,9 +27,13 @@ Branches are the foundation of development in a project: ## Create branch +Prerequisites: + +- You must have at least the Developer role for the project. + To create a new branch from the GitLab UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. Enter a **Branch name**. @@ -44,15 +48,15 @@ you can add one. Prerequisites: -- You must have at least the Developer role in the project. -- Unless you have the Maintainer or Owner roles, the +- You must have at least the Developer role for the project. +- If you don't have the Maintainer or Owner role, the [default branch protection](../../../group/manage.md#change-the-default-branch-protection-of-a-group) must be set to `Partially protected` or `Not protected` for you to push a commit to the default branch. To add a [default branch](default.md) to an empty project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Scroll to **The repository for this project is empty** and select the type of file you want to add. 1. In the Web IDE, make any desired changes to this file, then select **Create commit**. @@ -64,7 +68,7 @@ GitLab creates a default branch and adds your file to it. Prerequisites: -- You must have at least the Developer role in the project. +- You must have at least the Developer role for the project. When viewing an issue, you can create an associated branch directly from that page. Branches created this way use the @@ -73,11 +77,11 @@ including variables. Prerequisites: -- You must have at least the Developer role in the project. +- You must have at least the Developer role for the project. To create a branch from an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues** and find your issue. 1. Below the issue description, find the **Create merge request** dropdown list, and select **{chevron-down}** to display the dropdown list. @@ -89,7 +93,7 @@ To create a branch from an issue: ## Manage and protect branches -GitLab provides you multiple methods to protect individual branches. These methods +GitLab provides multiple methods to protect individual branches. These methods ensure your branches receive oversight and quality checks from their creation to their deletion: - The [default branch](default.md) in your project receives extra protection. @@ -104,19 +108,19 @@ ensure your branches receive oversight and quality checks from their creation to You can manage your branches: - With the GitLab user interface. -- With the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +- With Git on the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). - With the [Branches API](../../../../api/branches.md). ### View all branches To view and manage your branches in the GitLab user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. On this page, you can: -- See all branches, active branches, or stale branches. +- See all branches, or filter to see only active or stale branches. - Create new branches. - [Compare branches](#compare-branches). - Delete merged branches. @@ -145,19 +149,19 @@ and their protection methods: Prerequisites: -- You must have at least the Maintainer role in the project. +- You must have at least the Maintainer role for the project. To view the **Branch rules overview** list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. -1. Expand **Branch Rules** to view all branches with protections. +1. Expand **Branch rules** to view all branches with protections. - To add protections to a new branch: 1. Select **Add branch rule**. 1. Select **Create protected branch**. - To view more information about protections on an existing branch: 1. Identify the branch you want more information about. - 1. Select **Details** to see information about its: + 1. Select **View details** to see information about its: - [Branch protections](../../protected_branches.md). - [Approval rules](../../merge_requests/approvals/rules.md). - [Status checks](../../merge_requests/status_checks.md). @@ -173,12 +177,17 @@ GitLab enforces these additional rules on all branches: - No spaces are allowed in branch names. - Branch names with 40 hexadecimal characters are prohibited, because they are similar to Git commit hashes. -Common software packages, like Docker, may enforce +Common software packages, like Docker, can enforce [additional branch naming restrictions](../../../../administration/packages/container_registry.md#docker-connection-error). -For best compatibility with other software packages, use only numbers, hyphens (`-`), -underscores (`_`), and lower-case letters from the ASCII standard table. You -can use forward slashes (`/`) and emoji in branch names, but compatibility with other +For the best compatibility with other software packages, use only: + +- Numbers +- Hyphens (`-`) +- Underscores (`_`) +- Lowercase letters from the ASCII standard table + +You can use forward slashes (`/`) and emoji in branch names, but compatibility with other software packages cannot be guaranteed. Branch names with specific formatting offer extra benefits: @@ -200,7 +209,7 @@ Prerequisites: To change the default pattern for branches created from issues: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Branch defaults**. 1. Scroll to **Branch name template** and enter a value. The field supports these variables: @@ -210,8 +219,13 @@ To change the default pattern for branches created from issues: ### Prefix branch names with issue numbers -To streamline the creation of merge requests, start your branch name with an -issue number. GitLab uses the issue number to import data into the merge request: +To streamline the creation of merge requests, start your Git branch name with the +issue number, followed by a hyphen. +For example, to link a branch to issue `#123`, start the branch name with `123-`. + +The issue and the branch must be in the same project. + +GitLab uses the issue number to import data into the merge request: - The issue is marked as related to the merge request. The issue and merge request display links to each other. @@ -224,21 +238,9 @@ issue number. GitLab uses the issue number to import data into the merge request ## Compare branches -> - Repository filter search box [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. -> - Revision swapping [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. - -The default compare mode uses the `git diff from...to` method, instead of the -`git diff from to` method, to compare branches. The `git diff from...to` method -provides a more human-readable diff, because it does not include unrelated changes -made to the target branch after the source branch was created. - -NOTE: -The `git diff from...to` method shows all changes from a cherry-picked commit as -new changes. It uses the merge base, not the actual commit content, to compare branches. - To compare branches in a repository: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Compare revisions**. 1. Select the **Source** branch to search for your desired branch. Exact matches are shown first. You can refine your search with operators: @@ -247,8 +249,23 @@ To compare branches in a repository: - `*` matches using a wildcard: `branch*cache*` matches `fix/branch-search-cache-expiration`. - You can combine operators: `^chore/*migration$` matches `chore/user-data-migration`. 1. Select the **Target** repository and branch. Exact matches are shown first. -1. Select **Compare** to show the list of commits, and changed files. To reverse - the **Source** and **Target**, select **Swap revisions**. +1. Below **Show changes**, select the method to compare branches: + <!-- vale gitlab.SubstitutionWarning = NO --> + <!-- Disable Vale so it doesn't flag "since" --> + - **Only incoming changes from source** (default) shows differences from the source branch since + the latest common commit on both branches. + It doesn't include unrelated changes made to the target branch after the source branch was created. + This method uses the `git diff <from>...<to>` + [Git command](https://git-scm.com/docs/git-diff#Documentation/git-diff.txt-emgitdiffemltoptionsgtltcommitgtltcommitgt--ltpathgt82308203-1). + To compare branches, this method uses the merge base instead of the actual commit, so + changes from cherry-picked commits are shown as new changes. + - **Include changes to target since source was created** shows all the differences between the two + branches. + This method uses the `git diff <from> <to>` + [Git command](https://git-scm.com/docs/git-diff#Documentation/git-diff.txt-emgitdiffemltoptionsgt--merge-baseltcommitgtltcommitgt--ltpathgt82308203). + <!-- vale gitlab.SubstitutionWarning = YES --> +1. Select **Compare** to show the list of commits, and changed files. +1. Optional. To reverse the **Source** and **Target**, select **Swap revisions** (**{substitute}**). ## Delete merged branches @@ -259,15 +276,15 @@ Merged branches can be deleted in bulk if they meet all of these criteria: Prerequisites: -- You must have at least the Developer role in the project. +- You must have at least the Developer role for the project. To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. Select **Delete merged branches**. -1. In the modal window, enter the word `delete` to confirm, then select **Delete merged branches**. +1. In the dialog, enter the word `delete` to confirm, then select **Delete merged branches**. ## Related topics @@ -323,7 +340,7 @@ Error: Could not set the default branch. Do you have a branch named 'HEAD' in yo To fix this problem: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Search for a branch named `HEAD`. 1. Make sure the branch has no uncommitted changes. diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md deleted file mode 100644 index 6f18aabaa46..00000000000 --- a/doc/user/project/repository/code_suggestions.md +++ /dev/null @@ -1,375 +0,0 @@ ---- -stage: AI-powered -group: AI Model Validation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference ---- - -# Code Suggestions (Beta) **(FREE ALL)** - -> - [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. -> - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. -> - [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. -> - Code suggestions in the GitLab WebIDE enabled for all GitLab-hosted customers. -> - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2. - -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). - -Write code more efficiently by using generative AI to suggest code while you're developing. - -Code Suggestions are available: - -- To users of GitLab SaaS (by default) and self-managed GitLab Enterprise Edition (when requested). Code Suggestions are not available for GitLab Community Edition. -- In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. -- In the GitLab WebIDE. - -<div class="video-fallback"> - <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">View an end-to-end demo of Code Suggestions in VS Code</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> -</figure> - -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). - -## Supported languages - -The best results from Code Suggestions are expected [for languages the Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_coding_languages) directly support: - -- C++ -- C# -- Go -- Google SQL -- Java -- JavaScript -- Kotlin -- PHP -- Python -- Ruby -- Rust -- Scala -- Swift -- TypeScript - -### Supported code infrastructure interfaces - -Code Suggestions includes [Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) support for the following infrastructure as code interfaces: - -- Google Cloud CLI -- Kubernetes Resource Model (KRM) -- Terraform - -Suggestion quality for other languages and using natural language code comments to request completions may not yet result in high-quality suggestions. - -### Supported languages in IDEs - -Editor support for languages is documented in the following table. - -| Language | VS Code | JetBrains IDEs | Visual Studio | Neovim | -|---------------------------------|--------------------------------------------------------------|------------------------------|---------------|--------| -| C++ | ✓ | | ✓ | | -| C# | ✓ | ✓ | ✓ | | -| Go | ✓ | ✓ (IDEA Ultimate / GoLand) | | | -| Google SQL | | | | | -| Java | ✓ | ✓ | | | -| JavaScript | ✓ | ✓ | | | -| Kotlin | ✓ | ✓ | | | -| PHP | ✓ | ✓ (IDEA Ultimate) | | | -| Python | ✓ | ✓ | | ✓ | -| Ruby | ✓ | ✓ (IDEA Ultimate / RubyMine) | | ✓ | -| Rust | ✓ | ✓ | | | -| Scala | ✓ | ✓ | | | -| Swift | ✓ | ✓ | | | -| TypeScript | ✓ | ✓ | | | -| Google Cloud CLI | | | | | -| Kubernetes Resource Model (KRM) | | | | | -| Terraform | ✓ (Requires 3rd party extension providing Terraform support) | | | | - -## Supported editor extensions - -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). -- [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. - -## Enable Code Suggestions on GitLab SaaS **(FREE SAAS)** - -Code Suggestions can be enabled [for all members of a group](../../group/manage.md#enable-code-suggestions). - -Each individual user must also choose to enable Code Suggestions. - -### Enable Code Suggestions for an individual user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta). - -Each user can enable Code Suggestions for themselves: - -1. On the left sidebar, select your avatar. -1. Select **Preferences**. -1. In the **Code Suggestions** section, select the **Enable Code Suggestions** checkbox. -1. Select **Save changes**. - -If Code Suggestions is enabled for the group, the group setting overrides the user setting. - -NOTE: -This setting controls Code Suggestions for all IDEs. Support for [more granular control per IDE](https://gitlab.com/groups/gitlab-org/-/epics/10624) is proposed. - -## Enable Code Suggestions on self-managed GitLab **(FREE SELF)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta). - -To enable Code Suggestions on a self-managed GitLab EE instance, you must: - -- Be an administrator. -- Have a [GitLab SaaS account](https://gitlab.com/users/sign_up). -You do not need to have a GitLab SaaS subscription. - -Then, you will: - -1. Enable Code Suggestions for your SaaS account. -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 - -To enable Code Suggestions for your GitLab SaaS account: - -1. Create a [personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) - with the `api` scope. -1. On the left sidebar, select your avatar. -1. Select **Preferences**. -1. In the **Code Suggestions** section, select **Enable Code Suggestions**. -1. Select **Save changes**. - -### Enable Code Suggestions for the instance - -You must enable Code Suggestions for the instance. When you do this, 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. - -To enable Code Suggestions for your self-managed GitLab instance: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. -1. Expand **Code Suggestions** and: - - Select **Turn on Code Suggestions for this instance**. - - In **Personal access token**, enter your GitLab SaaS personal access token. -1. Select **Save changes**. - -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 - -GitLab provisions access on a customer-by-customer basis for Code Suggestions -on self-managed instances. To request access: - -1. Sign into your GitLab SaaS account. -1. Comment on [issue 415393](https://gitlab.com/gitlab-org/gitlab/-/issues/415393) - and tag your customer success manager. - -After GitLab has provisioned access to Code Suggestions for your instance, -the users in your instance can now enable Code Suggestions. - -## Use Code Suggestions - -Prerequisites: - -- For self-managed GitLab, Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). -- For GitLab SaaS, Code Suggestions must be enabled [for the top-level group](../../group/manage.md#enable-code-suggestions) and [for your user account](#enable-code-suggestions-for-an-individual-user). -- Install and configure a [supported IDE editor extension](#supported-editor-extensions). -To use Code Suggestions: - -1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: - - - Provides entire code snippets, like generating functions. - - Completes the current line. - -1. To accept a suggestion, press <kbd>Tab</kbd>. - -Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. - -GitLab is making improvements to the Code Suggestions to improve the quality. AI is non-deterministic, so you may not get the same suggestion every time with the same input. - -This feature is currently in [Beta](../../../policy/experiment-beta-support.md#beta). -Code Suggestions depends on both Google Vertex AI Codey APIs and the GitLab Code Suggestions service. We have built this feature to gracefully degrade and have controls in place to allow us to -mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. - -## Code Suggestions data usage - -Code Suggestions is a generative artificial intelligence (AI) model. - -Your personal access token enables a secure API connection to GitLab.com. -This API connection securely transmits a context window from your IDE/editor to the Code Suggestions GitLab hosted service which calls Google Vertex AI Codey APIs, -and the generated suggestion is transmitted back to your IDE/editor. - -GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview). - -### Data privacy - -No new additional data is collected to enable this feature. Private non-public GitLab customer data is -not used as training data. - -Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) - -### Inference window context - -Code Suggestions currently inferences against the currently opened file and has a context window of 2,048 tokens and 8,192 character limits. This limit includes content before and after the cursor, the file name, and the extension type. -Learn more about Google Vertex AI [code-gecko](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). - -The maximum number of tokens that is generated in the response is default 64. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. -Learn more about Google Vertex AI [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion). - -### Self-managed instance data privacy - -A self-managed GitLab instance does not generate the code suggestion. After successful -authentication to the self-managed instance, a token is generated. - -The IDE/editor then uses this token to securely transmit data directly to -GitLab.com's Code Suggestions service for processing. - -The Code Suggestion service then securely returns an AI-generated code suggestion. - -Neither GitLab nor Google Vertex AI Codey APIs have any visibility into a self-managed customer's code other than -what is sent to generate the code suggestion. - -### Training data - -Code suggestions are routed through Google Vertex AI Codey APIs. Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) and [Responsible AI](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/responsible-ai). - -Google Vertex AI Codey APIs are not trained on private non-public GitLab customer or user data. - -Google has [shared the following](https://ai.google/discover/foundation-models/) about the data Codey models are trained on: - -> Codey is our family of foundational coding models built on PaLM 2. Codey was fine-tuned on a large dataset of high quality, permissively licensed code from external sources - -## Progressive enhancement - -This feature is designed as a progressive enhancement to developer's IDEs. -Code Suggestions offer a completion if the machine learning engine can generate a recommendation. -In the event of a connection issue or model inference failure, the feature gracefully degrades. -Code Suggestions do not prevent you from writing code in your IDE. - -### Internet connectivity - -Code Suggestions does not work with offline environments. - -To use Code Suggestions: - -- On GitLab.com, you must have an internet connection and be able to access GitLab. -- In GitLab 16.1 and later, on self-managed GitLab, you must have an internet connection. - -### Model accuracy and quality - -Code Suggestions can generate low-quality, incomplete, and possibly insecure code. -We strongly encourage all beta users to leverage GitLab native -[Code Quality Scanning](../../../ci/testing/code_quality.md) and -[Security Scanning](../../application_security/index.md) capabilities. - -GitLab currently does not retrain Google Vertex AI Codey APIs. GitLab makes no claims -to the accuracy or quality of code suggestions generated by Google Vertex AI Codey API. -Read more about [Google Vertex AI foundation model capabilities](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). - -## Known limitations - -While in Beta, we are working on improving 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 - -We are also aware of specific situations that can produce unexpected or incoherent results including: - -- Suggestions written in the middle of existing functions, or "fill in the middle." -- Suggestions based on natural language code comments. -- Suggestions that mixed programming languages in unexpected ways. - -## Feedback - -Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). - -## Troubleshooting - -### Code Suggestions aren't displayed - -If Code Suggestions are not displayed, try the following troubleshooting steps. - -In GitLab, ensure Code Suggestions is enabled: - -- [For your user account](#enable-code-suggestions-for-an-individual-user). -- [For *all* top-level groups your account belongs to](../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. - -To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. - -#### 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. - -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)** - 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. Verify that the debug log contains similar output: - -```shell -2023-07-14T17:29:00:763 [debug]: Disabling code completion -2023-07-14T17:29:01:802 [debug]: Enabling code completion -2023-07-14T17:29:01:802 [debug]: AI Assist: Using server: https://codesuggestions.gitlab.com/v2/completions -``` - -#### Code Suggestions not displayed in Microsoft Visual Studio - -Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-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**. -1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Extension** as the log filter. -1. Verify that the debug log contains similar output: - -```shell -14:48:21:344 GitlabProposalSource.GetCodeSuggestionAsync -14:48:21:344 LsClient.SendTextDocumentCompletionAsync("GitLab.Extension.Test\TestData.cs", 34, 0) -14:48:21:346 LS(55096): time="2023-07-17T14:48:21-05:00" level=info msg="update context" -``` - -### Authentication troubleshooting - -If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, -specifically the token system. To resolve the issue: - -1. Remove the existing personal access token from your GitLab account settings. -1. Reauthorize your GitLab account in VS Code using OAuth. -1. Test the code suggestions feature with different file extensions to verify if the issue is resolved. diff --git a/doc/user/project/repository/code_suggestions/index.md b/doc/user/project/repository/code_suggestions/index.md new file mode 100644 index 00000000000..4f0c0b2c9a6 --- /dev/null +++ b/doc/user/project/repository/code_suggestions/index.md @@ -0,0 +1,192 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions **(FREE ALL BETA)** + +> - [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. + +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). + +Write code more efficiently by using generative AI to suggest code while you're developing. + +GitLab Duo Code Suggestions are available: + +- On [self-managed](self_managed.md) and [SaaS](saas.md). +- In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. +- In the GitLab WebIDE. + +<div class="video-fallback"> + <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">View an end-to-end demo of Code Suggestions in VS Code</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> +</figure> + +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). + +## Supported languages + +The best results from Code Suggestions are expected [for languages the Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_coding_languages) directly support: + +- C++ +- C# +- Go +- Google SQL +- Java +- JavaScript +- Kotlin +- PHP +- Python +- Ruby +- Rust +- Scala +- Swift +- TypeScript + +### Supported code infrastructure interfaces + +Code Suggestions includes [Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) support for the following infrastructure as code interfaces: + +- Google Cloud CLI +- Kubernetes Resource Model (KRM) +- Terraform + +Suggestion quality for other languages and using natural language code comments to request completions may not yet result in high-quality suggestions. + +### Supported languages in IDEs + +Editor support for languages is documented in the following table. + +| Language | VS Code | JetBrains IDEs | Visual Studio | Neovim | +|------------------|------------------------|------------------------|------------------------|--------| +| C++ | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | +| C# | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Go | **{check-circle}** Yes | **{check-circle}** Yes (IDEA Ultimate / GoLand) | **{check-circle}** Yes | **{check-circle}** Yes | +| Google SQL | **{dotted-circle}** No | **{dotted-circle}** No | **{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 | +| PHP | **{check-circle}** Yes | **{check-circle}** Yes (IDEA Ultimate) | **{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 (IDEA Ultimate / RubyMine) | **{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 | +| 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) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes (Requires third-party extension providing the `terraform` file type) | + +## Supported editor extensions + +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). +- [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. + +## Code Suggestions data usage + +Code Suggestions is a generative artificial intelligence (AI) model. + +Your personal access token enables a secure API connection to GitLab.com. +This API connection securely transmits a context window from your IDE/editor to the Code Suggestions GitLab hosted service which calls Google Vertex AI Codey APIs, +and the generated suggestion is transmitted back to your IDE/editor. + +GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview). Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance). + +### Telemetry + +For self-managed instances that have enabled Code Suggestions and SaaS accounts, we collect aggregated or de-identified first-party usage data through our [Snowplow collector](https://about.gitlab.com/handbook/business-technology/data-team/platform/snowplow/). This usage data includes the following metrics: + +- Language the code suggestion was in (for example, Python) +- Editor being used (for example, VS Code) +- Number of suggestions shown, accepted, rejected, or that had errors +- Duration of time that a suggestion was shown +- Prompt and suffix lengths +- Model used +- Number of unique users +- Number of unique instances + +### Inference window context + +Code Suggestions currently inferences against the currently opened file and has a context window of 2,048 tokens and 8,192 character limits. This limit includes content before and after the cursor, the file name, and the extension type. +Learn more about Google Vertex AI [code-gecko](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). + +The maximum number of tokens that is generated in the response is default 64. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. +Learn more about Google Vertex AI [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion). + +### Training data + +Code Suggestions are routed through Google Vertex AI Codey APIs. Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) and [Responsible AI](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/responsible-ai). + +Google Vertex AI Codey APIs are not trained on private non-public GitLab customer or user data. + +Google has [shared the following](https://ai.google/discover/foundation-models/) about the data Codey models are trained on: + +> Codey is our family of foundational coding models built on PaLM 2. Codey was fine-tuned on a large dataset of high quality, permissively licensed code from external sources + +## Progressive enhancement + +This feature is designed as a progressive enhancement to developer's IDEs. +Code Suggestions offer a completion if the machine learning engine can generate a recommendation. +In the event of a connection issue or model inference failure, the feature gracefully degrades. +Code Suggestions do not prevent you from writing code in your IDE. + +### Internet connectivity + +Code Suggestions does not work with offline environments. + +To use Code Suggestions: + +- On GitLab.com, you must have an internet connection and be able to access GitLab. +- In GitLab 16.1 and later, on self-managed GitLab, you must have an internet connection. + +### Model accuracy and quality + +Code Suggestions can generate low-quality, incomplete, and possibly insecure code. +We strongly encourage all beta users to leverage GitLab native +[Code Quality Scanning](../../../../ci/testing/code_quality.md) and +[Security Scanning](../../../application_security/index.md) capabilities. + +GitLab currently does not retrain Google Vertex AI Codey APIs. GitLab makes no claims +to the accuracy or quality of Code Suggestions generated by Google Vertex AI Codey API. +Read more about [Google Vertex AI foundation model capabilities](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). + +## Known limitations + +While in Beta, we are working on improving 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 + +We are also aware of specific situations that can produce unexpected or incoherent results including: + +- Suggestions written in the middle of existing functions, or "fill in the middle." +- Suggestions based on natural language code comments. +- Suggestions that mixed programming languages in unexpected ways. + +## Feedback + +Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). diff --git a/doc/user/project/repository/code_suggestions/saas.md b/doc/user/project/repository/code_suggestions/saas.md new file mode 100644 index 00000000000..174c227b6fe --- /dev/null +++ b/doc/user/project/repository/code_suggestions/saas.md @@ -0,0 +1,54 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions on GitLab SaaS **(FREE SAAS BETA)** + +> - [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. + +Write code more efficiently by using generative AI to suggest code while you're developing. + +Usage of GitLab Duo 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](index.md#code-suggestions-data-usage). + +## 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). + +You can enable Code Suggestions for an individual or group: + +- [Enable Code Suggestions for all group members](../../../group/manage.md#enable-code-suggestions). (You must be a group owner). +- [Enable Code Suggestions for your own account](../../../profile/preferences.md#enable-code-suggestions). + +The group setting takes precedence over the user setting. + +## Use Code Suggestions + +Prerequisites: + +- Ensure Code Suggestions is enabled for your user and group. +- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). + +To use Code Suggestions: + +1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: + + - Provides entire code snippets, like generating functions. + - Completes the current line. + +1. To accept a suggestion, press <kbd>Tab</kbd>. + +Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. + +GitLab is making improvements to the Code Suggestions to improve the quality. AI is non-deterministic, so you may not get the same suggestion every time with the same input. + +This feature is currently in [Beta](../../../../policy/experiment-beta-support.md#beta). +Code Suggestions depends on both Google Vertex AI Codey APIs and the GitLab Code Suggestions service. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. diff --git a/doc/user/project/repository/code_suggestions/self_managed.md b/doc/user/project/repository/code_suggestions/self_managed.md new file mode 100644 index 00000000000..3c149604086 --- /dev/null +++ b/doc/user/project/repository/code_suggestions/self_managed.md @@ -0,0 +1,187 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions on self-managed GitLab **(PREMIUM SELF BETA)** + +> - [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. + +Write code more efficiently by using generative AI to suggest code while you're developing. + +GitLab Duo Code Suggestions are available on GitLab Enterprise Edition. +Cloud licensing is required for Premium and Ultimate subscription tiers. + +Code Suggestions are not available for GitLab Community Edition. + +WARNING: +In GitLab 16.3 and later, only Premium and Ultimate customers can participate in the free trial of Code Suggestions on self-managed GitLab. + +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](index.md#code-suggestions-data-usage). + +## Enable Code Suggestions on self-managed GitLab **(FREE SELF)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). + +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 differs depending on your version of GitLab. + +### GitLab 16.3 and later + +Prerequisites: + +- You are a new Code Suggestions customer as of GitLab 16.3. +- All of the users in your instance have the latest version of their IDE extension. +- You are an administrator. + +To enable Code Suggestions for your self-managed GitLab instance: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Code Suggestions** and select **Turn on Code Suggestions for this 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). + +The users in your instance can now use Code Suggestions. + +### GitLab 16.2 and earlier + +Prerequisites: + +- You are an administrator. +- You have a [customer success manager](https://about.gitlab.com/handbook/customer-success/csm/]). +- 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). + +Then, you will: + +1. Enable Code Suggestions for your SaaS account. +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 + +To enable Code Suggestions for your GitLab SaaS account: + +1. Create a [personal access token](../../../profile/personal_access_tokens.md#create-a-personal-access-token) + with the `api` scope. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Code Suggestions** section, select **Enable Code Suggestions**. +1. Select **Save changes**. + +#### Enable Code Suggestions for the instance + +To enable Code Suggestions for your self-managed GitLab instance: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Code Suggestions** and: + - Select **Turn on Code Suggestions for this instance**. + - In **Personal access token**, enter your GitLab SaaS personal access token. +1. Select **Save changes**. + +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 + +GitLab provisions access on a customer-by-customer basis for Code Suggestions +on self-managed instances. To request access, contact your customer success manager. + +Your customer success manager then provisions access by commenting on [issue 415393](https://gitlab.com/gitlab-org/gitlab/-/issues/415393) (internal access only). + +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 any firewalls to allow outbound connections to `https://codesuggestions.gitlab.com/`. + +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). + +### Update GitLab + +In GitLab 16.3 and later, GitLab is enforcing the cloud licensing requirement for Code Suggestions: + +- The Premium and Ultimate subscription tiers support cloud Licensing. +- GitLab Free does not have cloud licensing support. + +If you have a GitLab Free subscription and update 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. 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 + +You must [manually synchronize your subscription](../../../../subscriptions/self_managed/index.md#manually-synchronize-your-subscription-details) if either: + +- You have already updated to GitLab 16.3 and have just bought a Premium or Ultimate tier subscription. +- You already have a Premium or Ultimate tier subscription and have just updated to GitLab 16.3. + +Without the manual synchronization, it might take up to 24 hours to active Code Suggestions on your instance. + +## Use Code Suggestions + +Prerequisites: + +- Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). +- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). + +To use Code Suggestions: + +1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: + + - Provides entire code snippets, like generating functions. + - Completes the current line. + +1. To accept a suggestion, press <kbd>Tab</kbd>. + +Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. + +GitLab is making improvements to the Code Suggestions to improve the quality. AI is non-deterministic, so you may not get the same suggestion every time with the same input. + +This feature is currently in [Beta](../../../../policy/experiment-beta-support.md#beta). +Code Suggestions depends on both Google Vertex AI Codey APIs and the GitLab Code Suggestions service. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. + +### Data privacy + +A self-managed GitLab instance does not generate the code suggestion. After successful +authentication to the self-managed instance, a token is generated. + +The IDE/editor then uses this token to securely transmit data directly to +GitLab.com's Code Suggestions service for processing. + +The Code Suggestions service then securely returns an AI-generated code suggestion. + +Neither GitLab nor Google Vertex AI Codey APIs have any visibility into a self-managed customer's code other than +what is sent to generate the code suggestion. diff --git a/doc/user/project/repository/code_suggestions/troubleshooting.md b/doc/user/project/repository/code_suggestions/troubleshooting.md new file mode 100644 index 00000000000..c0cdb3cc32d --- /dev/null +++ b/doc/user/project/repository/code_suggestions/troubleshooting.md @@ -0,0 +1,69 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Troubleshooting Code Suggestions **(FREE ALL BETA)** + +When working with GitLab Duo Code Suggestions, you might encounter the following issues. + +## Code Suggestions aren't displayed + +If Code Suggestions are not displayed, 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). If you don't have a role that lets you view the top-level group's settings, contact a group owner. + +To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. + +### 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. + +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)** + 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. Verify that the debug log contains similar output: + +```shell +2023-07-14T17:29:00:763 [debug]: Disabling code completion +2023-07-14T17:29:01:802 [debug]: Enabling code completion +2023-07-14T17:29:01:802 [debug]: AI Assist: Using server: https://codesuggestions.gitlab.com/v2/completions +``` + +### Code Suggestions not displayed in Microsoft Visual Studio + +Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-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**. +1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Extension** as the log filter. +1. Verify that the debug log contains similar output: + +```shell +14:48:21:344 GitlabProposalSource.GetCodeSuggestionAsync +14:48:21:344 LsClient.SendTextDocumentCompletionAsync("GitLab.Extension.Test\TestData.cs", 34, 0) +14:48:21:346 LS(55096): time="2023-07-17T14:48:21-05:00" level=info msg="update context" +``` + +## Authentication troubleshooting + +If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, +specifically the token system. To resolve the issue: + +1. Remove the existing personal access token from your GitLab account settings. +1. Reauthorize your GitLab account in VS Code using OAuth. +1. Test the Code Suggestions feature with different file extensions to verify if the issue is resolved. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index ee2be6dee7c..5dd8ad39889 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -14,7 +14,7 @@ File finder is powered by the [`fuzzaldrin-plus`](https://github.com/jeancroy/fu To search for a file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. In the upper right, select **Find file**. 1. In the search box, start typing the filename. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 4c37b92b388..a304a8d108d 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -59,8 +59,8 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates To update your fork from the GitLab UI: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. Select the fork you want to update. 1. Below the dropdown list for branch name, find the **Forked from** (**{fork}**) information box to determine if your fork is ahead, behind, or both. In this example, @@ -181,13 +181,13 @@ To restore the fork relationship, [use the API](../../../api/projects.md#create- To remove a fork relationship: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Remove fork relationship** section, select **Remove fork relationship**. 1. To confirm, enter the project path and select **Confirm**. -When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_types.md#hashed-object-pools) +When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_paths.md#hashed-object-pools) to share objects with another repository: - All objects are copied from the pool into your fork. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 8bb6d868270..592041ef4e2 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,330 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../signed_commits/gpg.md' +remove_date: '2023-12-01' --- -# Sign commits with GPG **(FREE ALL)** +This document was moved to [another location](../signed_commits/gpg.md). -You can sign the commits you make in a GitLab repository with a -GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic -signature to your commit, you provide extra assurance that a commit -originated from you, rather than an impersonator. If GitLab can verify a commit -author's identity with a public GPG key, the commit is marked **Verified** in the -GitLab UI. You can then configure [push rules](../push_rules.md) -for your project to reject individual commits not signed with GPG, or reject all -commits from unverified users. - -NOTE: -GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and -implementations. - -For GitLab to consider a commit verified: - -- The committer must have a GPG public/private key pair. -- The committer's public key must be uploaded to their GitLab account. -- One of the email addresses in the GPG public key must match a **verified** email address - used by the committer in GitLab. To keep this address private, use the automatically generated - [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) - GitLab provides in your profile. -- The committer's email address must match the verified email address from the - GPG key. - -GitLab uses its own keyring to verify the GPG signature. It does not access any -public key server. - -GPG verified tags are not supported. - -For more details about GPG, refer to the [related topics list](#related-topics). - -## View a user's public GPG key - -To view a user's public GPG key, you can either: - -- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, - if the user has configured one, or a blank page for users without a configured GPG key. -- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner - of the user's profile, select **View public GPG keys** (**{key}**). - -## Configure commit signing - -To sign commits, you must configure both your local machine and your GitLab account: - -1. [Create a GPG key](#create-a-gpg-key). -1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account). -1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git). -1. [Sign your Git commits](#sign-your-git-commits). - -### Create a GPG key - -If you don't already have a GPG key, create one: - -1. [Install GPG](https://www.gnupg.org/download/) for your operating system. - If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in - the commands on this page. -1. To generate your key pair, run the command appropriate for your version of `gpg`: - - ```shell - # Use this command for the default version of GPG, including - # Gpg4win on Windows, and most macOS versions: - gpg --gen-key - - # Use this command for versions of GPG later than 2.1.17: - gpg --full-gen-key - ``` - -1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select - the default option, `RSA and RSA`. -1. Select the key length, in bits. GitLab recommends 4096-bit keys. -1. Specify the validity period of your key. This value is subjective, and the - default value is no expiration. -1. To confirm your answers, enter `y`. -1. Enter your name. -1. Enter your email address. It must match a - [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits) - in your GitLab account. -1. Optional. Enter a comment to display in parentheses after your name. -1. GPG displays the information you've entered so far. Edit the information or press - <kbd>O</kbd> (for `Okay`) to continue. -1. Enter a strong password, then enter it again to confirm it. -1. To list your private GPG key, run this command, replacing - `<EMAIL>` with the email address you used when you generated the key: - - ```shell - gpg --list-secret-keys --keyid-format LONG <EMAIL> - ``` - -1. In the output, identify the `sec` line, and copy the GPG key ID. It begins after - the `/` character. In this example, the key ID is `30F2B65B9246B6CA`: - - ```plaintext - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` - -1. To show the associated public key, run this command, replacing `<ID>` with the - GPG key ID from the previous step: - - ```shell - gpg --armor --export <ID> - ``` - -1. Copy the public key, including the `BEGIN PGP PUBLIC KEY BLOCK` and - `END PGP PUBLIC KEY BLOCK` lines. You need this key in the next step. - -### Add a GPG key to your account - -To add a GPG key to your user settings: - -1. Sign in to GitLab. -1. On the left sidebar, select your avatar. -1. Select **Edit profile**. -1. Select **GPG Keys** (**{key}**). -1. Select **Add new key**. -1. In **Key**, paste your _public_ key. -1. To add the key to your account, select **Add key**. GitLab shows the key's - fingerprint, email address, and creation date: - -  - -After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. - -### Associate your GPG key with Git - -After you [create your GPG key](#create-a-gpg-key) and -[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git -to use this key: - -1. Run this command to list the private GPG key you just created, - replacing `<EMAIL>` with the email address for your key: - - ```shell - gpg --list-secret-keys --keyid-format LONG <EMAIL> - ``` - -1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is - `30F2B65B9246B6CA`: - - ```plaintext - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` - -1. Run this command to configure Git to sign your commits with your key, - replacing `<KEY ID>` with your GPG key ID: - - ```shell - git config --global user.signingkey <KEY ID> - ``` - -### Sign your Git commits - -After you [add your public key to your account](#add-a-gpg-key-to-your-account), -you can sign individual commits manually, or configure Git to default to signed commits: - -- Sign individual Git commits manually: - 1. Add `-S` flag to any commit you want to sign: - - ```shell - git commit -S -m "My commit message" - ``` - - 1. Enter the passphrase of your GPG key when asked. - 1. Push to GitLab and check that your commits [are verified](#verify-commits). -- Sign all Git commits by default by running this command: - - ```shell - git config --global commit.gpgsign true - ``` - -#### Set signing key conditionally - -If you maintain signing keys for separate purposes, such as work and personal -use, use an `IncludeIf` statement in your `.gitconfig` file to set which key -you sign commits with. - -Prerequisites: - -- Requires Git version 2.13 or later. - -1. In the same directory as your main `~/.gitconfig` file, create a second file, - such as `.gitconfig-gitlab`. -1. In your main `~/.gitconfig` file, add your Git settings for work in non-GitLab projects. -1. Append this information to the end of your main `~/.gitconfig` file: - - ```ini - # The contents of this file are included only for GitLab.com URLs - [includeIf "hasconfig:remote.*.url:https://gitlab.com/**"] - - # Edit this line to point to your alternate configuration file - path = ~/.gitconfig-gitlab - ``` - -1. In your alternate `.gitconfig-gitlab` file, add the configuration overrides to - use when you're committing to a GitLab repository. All settings from your - main `~/.gitconfig` file are retained unless you explicitly override them. - In this example, - - ```ini - # Alternate ~/.gitconfig-gitlab file - # These values are used for repositories matching the string 'gitlab.com', - # and override their corresponding values in ~/.gitconfig - - [user] - email = you@example.com - signingkey = <KEY ID> - - [commit] - gpgsign = true - ``` - -## Verify commits - -You can review commits for a merge request, or for an entire project: - -1. To review commits for a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Commits**. -1. To review commits for a merge request: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Merge requests**, then select your merge request. - 1. Select **Commits**. -1. Identify the commit you want to review. Signed commits show either a **Verified** - or **Unverified** badge, depending on the verification status of the GPG - signature. Unsigned commits do not display a badge: - -  - -1. To display the signature details for a commit, select the GPG badge: - -  - -  - -## Revoke a GPG key - -If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits: - -- Past commits signed by this key are marked as unverified. -- Future commits signed by this key are marked as unverified. - -To revoke a GPG key: - -1. On the left sidebar, select your avatar. -1. Select **Edit profile**. -1. Select **GPG Keys** (**{key}**). -1. Select **Revoke** next to the GPG key you want to delete. - -## Remove a GPG key - -When you remove a GPG key from your GitLab account: - -- Previous commits signed with this key remain verified. -- Future commits (including any commits created but not yet pushed) that attempt - to use this key are unverified. - -To remove a GPG key from your account: - -1. On the left sidebar, select your avatar. -1. Select **Edit profile**. -1. Select **GPG Keys** (**{key}**). -1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. - -If you must unverify both future and past commits, -[revoke the associated GPG key](#revoke-a-gpg-key) instead. - -## Related topics - -- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) -- [Sign commits with SSH keys](../ssh_signed_commits/index.md) -- [Commits API](../../../../api/commits.md) -- GPG resources: - - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) - - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) - - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) - - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) - - [Review existing GPG keys in your instance](../../../../administration/credentials_inventory.md#review-existing-gpg-keys) - -## Troubleshooting - -### Fix verification problems with signed commits - -Commits can be signed with [X.509 certificates](../x509_signed_commits/index.md) -or a GPG key. The verification process for both methods can fail for multiple reasons: - -| Value | Description | Possible Fixes | -|-----------------------------|-------------|----------------| -| `UNVERIFIED` | The commit signature is not valid. | Sign the commit with a valid signature. | -| `SAME_USER_DIFFERENT_EMAIL` | The GPG key used to sign the commit does not contain the committer email, but does contain a different valid email for the committer. | Amend the commit to use an email address that matches the GPG key, or update the GPG key [to include the email address](https://security.stackexchange.com/a/261468). | -| `OTHER_USER` | The signature and GPG key are valid, but the key belongs to a different user than the committer. | Amend the commit to use the correct email address, or amend the commit to use a GPG key associated with your user. | -| `UNVERIFIED_KEY` | The key associated with the GPG signature has no verified email address associated with the committer. | Add and verify the email to your GitLab profile, [update the GPG key to include the email address](https://security.stackexchange.com/a/261468), or amend the commit to use a different committer email address. | -| `UNKNOWN_KEY` | The GPG key associated with the GPG signature for this commit is unknown to GitLab. | [Add the GPG key](#add-a-gpg-key-to-your-account) to your GitLab profile. | -| `MULTIPLE_SIGNATURES` | Multiple GPG or X.509 signatures have been found for the commit. | Amend the commit to use only one GPG or X.509 signature. | - -### Secret key not available - -If you receive the errors `secret key not available` -or `gpg: signing failed: secret key not available`, try using `gpg2` instead of `gpg`: - -```shell -git config --global gpg.program gpg2 -``` - -If your GPG key is password protected and the password entry prompt does not appear, -add `export GPG_TTY=$(tty)` to your shell's `rc` file (commonly `~/.bashrc` or `~/.zshrc`) - -### GPG failed to sign the data - -If your GPG key is password protected and you receive the error: - -```shell -error: gpg failed to sign the data -fatal: failed to write commit object -``` - -If the password entry prompt does not appear, add `export GPG_TTY=$(tty)` to your shell's `rc` file -(commonly `~/.bashrc` or `~/.zshrc`) and restart your terminal. +<!-- 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 3d00ceafc05..e97892458b4 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -55,7 +55,7 @@ to a branch in the repository. When you use the command line, you can commit mul [Revert a commit](../merge_requests/revert_changes.md#revert-a-commit) from the UI to a selected branch. - **Sign a commit:** - Use GPG to [sign your commits](gpg_signed_commits/index.md). + Add extra security by [signing your commits](signed_commits/index.md). ## Clone a repository @@ -73,7 +73,7 @@ into Xcode on macOS. 1. Select **Xcode**. The project is cloned onto your computer and you are -prompted to open XCode. +prompted to open Xcode. ### Clone and open in Visual Studio Code @@ -216,6 +216,11 @@ To render an OpenAPI file: 1. Go to the OpenAPI file in your repository. 1. Between the **Display source** and **Edit** buttons, select **Display OpenAPI**. When an OpenAPI file is found, it replaces the **Display rendered file** button. +1. To display the `operationId` in the operations list, add `displayOperationId=true` to the query string. + +NOTE: +When `displayOperationId` is present in the query string and has _any_ value, it +evaluates to `true`. This behavior matches the default behavior of Swagger. ## Repository size diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 70ee841a991..2a1fc0cddf8 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -37,7 +37,7 @@ When commits include changes to Jupyter Notebook files, GitLab: - Enables switching between raw and rendered diffs on the Commit and Compare pages. (Not available on merge request pages.) - Renders images on the diffs. -Code suggestions are not available on diffs and merge requests for `.ipynb` files. +Code Suggestions are not available on diffs and merge requests for `.ipynb` files. Cleaner notebook diffs are not generated when the notebook is too large. diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index e5c1e4a6614..1d5127b5e08 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.md @@ -1,53 +1,411 @@ --- stage: Systems -group: Distribution +group: Gitaly info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -description: "Documentation on large repositories." --- -# Managing large repositories **(FREE SELF)** +# Managing monorepos -GitLab, like any Git based system, is subject to similar performance restraints when it comes to large -repositories that size into the gigabytes. +Monorepos have become a regular part of development team workflows. While they have many advantages, monorepos can present performance challenges +when using them in GitLab. Therefore, you should know: -In the following sections, we detail several best practices for improving performance with these large repositories on GitLab. +- What repository characteristics can impact performance. +- Some tools and steps to optimize monorepos. -## Large File System (LFS) +## Impact on performance -It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, or graphics) are stored as Large File Storage (LFS) objects. With LFS, the objects are stored externally, such as in Object Storage, which reduces the number and size of objects in the repository. Storing objects in external Object Storage can improve performance. +Because GitLab is a Git-based system, it is subject to similar performance +constraints as Git when it comes to large repositories that are gigabytes in +size. -To analyze if a repository has large objects, you can use a tool like [`git-sizer`](https://github.com/github/git-sizer) for detailed analysis. This tool shows details about what makes up the repository, and highlights any areas of concern. If any large objects are found, you can then remove them with a tool such as [`git filter-repo`](reducing_the_repo_size_using_git.md). +Monorepos can be large for [many reasons](https://about.gitlab.com/blog/2022/09/06/speed-up-your-monorepo-workflow-in-git/#characteristics-of-monorepos). + +Large repositories pose a performance risk performance when used in GitLab, especially if a large monorepo receives many clones or pushes a day, which is common for them. + +Git itself has performance limitations when it comes to handling +monorepos. + +[Gitaly](https://gitlab.com/gitlab-org/gitaly) is our Git storage service built +on top of [Git](https://git-scm.com/). This means that any limitations of +Git are experienced in Gitaly, and in turn by end users of GitLab. + +## Profiling repositories + +Large repositories generally experience performance issues in Git. Knowing why +your repository is large can help you develop mitigation strategies to avoid +performance problems. + +You can use [`git-sizer`](https://github.com/github/git-sizer) to get a snapshot +of repository characteristics and discover problem aspects of your monorepo. + +For example: + +```shell +Processing blobs: 1652370 +Processing trees: 3396199 +Processing commits: 722647 +Matching commits to trees: 722647 +Processing annotated tags: 534 +Processing references: 539 +| Name | Value | Level of concern | +| ---------------------------- | --------- | ------------------------------ | +| Overall repository size | | | +| * Commits | | | +| * Count | 723 k | * | +| * Total size | 525 MiB | ** | +| * Trees | | | +| * Count | 3.40 M | ** | +| * Total size | 9.00 GiB | **** | +| * Total tree entries | 264 M | ***** | +| * Blobs | | | +| * Count | 1.65 M | * | +| * Total size | 55.8 GiB | ***** | +| * Annotated tags | | | +| * Count | 534 | | +| * References | | | +| * Count | 539 | | +| | | | +| Biggest objects | | | +| * Commits | | | +| * Maximum size [1] | 72.7 KiB | * | +| * Maximum parents [2] | 66 | ****** | +| * Trees | | | +| * Maximum entries [3] | 1.68 k | * | +| * Blobs | | | +| * Maximum size [4] | 13.5 MiB | * | +| | | | +| History structure | | | +| * Maximum history depth | 136 k | | +| * Maximum tag depth [5] | 1 | | +| | | | +| Biggest checkouts | | | +| * Number of directories [6] | 4.38 k | ** | +| * Maximum path depth [7] | 13 | * | +| * Maximum path length [8] | 134 B | * | +| * Number of files [9] | 62.3 k | * | +| * Total size of files [9] | 747 MiB | | +| * Number of symlinks [10] | 40 | | +| * Number of submodules | 0 | | +``` + +In this example, a few items are raised with a high level of concern. See the +following sections for information on solving: + +- A high number of references. +- Large blobs. + +### Large number of references + +A reference in Git (a branch or tag) is used to refer to a commit. Each +reference is stored as an individual file. If you are curious, you can go +to any `.git` directory and look under the `refs` directory. + +A large number of references can cause performance problems because, with more references, +object walks that Git does are larger for various operations such as clones, pushes, and +housekeeping tasks. + +#### Mitigation strategies + +To mitigate the effects of a large number of references in a monorepo: + +- Create an automated process for cleaning up old branches. +- If certain references don't need to be visible to the client, hide them using the + [`transfer.hideRefs`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-transferhideRefs) + configuration setting. Because Gitaly ignores any on-server Git configuration, you must change the Gitaly configuration + itself in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitaly['configuration'] = { + # ... + git: { + # ... + config: [ + # ... + { key: "transfer.hideRefs", value: "refs/namespace_to_hide" }, + ], + }, + } + ``` + +In Git 2.42.0 and later, different Git operations can skip over hidden references +when doing an object graph walk. + +### Using LFS for large blobs + +Because Git is built to handle text data, it doesn't handle large +binary files efficiently. + +Therefore, you should store binary or blob files (for example, packages, audio, video, or graphics) +as Large File Storage (LFS) objects. With LFS, the objects are stored externally, such as in Object +Storage, which reduces the number and size of objects in the repository. Storing +objects in external Object Storage can improve performance. + +To analyze if a repository has large objects, you can use a tool like +[`git-sizer`](https://github.com/github/git-sizer) for detailed analysis. This +tool shows details about what makes up the repository, and highlights any areas +of concern. If any large objects are found, you can then remove them with a tool +such as [`git filter-repo`](reducing_the_repo_size_using_git.md). For more information, refer to the [Git LFS documentation](../../../topics/git/lfs/index.md). -## Gitaly Pack Objects Cache +## Optimizing large repositories for GitLab + +Other than modifying your workflow and the actual repository, you can take other +steps to maximize performance of monorepos with GitLab. + +### Gitaly pack-objects cache + +For very active repositories with a large number of references and files, consider using the +[Gitaly pack-objects cache](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). +The pack-objects cache: + +- Benefits all repositories on your GitLab server. +- Automatically works for forks. + +You should always: + +- Fetch incrementally. Do not clone in a way that recreates all of the worktree. +- Use shallow clones to reduce data transfer. Be aware that this puts more burden on GitLab instance because of higher CPU impact. + +Control the clone directory if you heavily use a fork-based workflow. Optimize +`git clean` flags to ensure that you remove or keep data that might affect or +speed-up your build. + +For more information, see [Pack-objects cache](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). + +### Reduce concurrent clones in CI/CD + +Large repositories tend to be monorepos. This usually means that these +repositories get a lot of traffic not only from users, but from CI/CD. + +CI/CD loads tend to be concurrent because pipelines are scheduled during set times. +As a result, the Git requests against the repositories can spike notably during +these times and lead to reduced performance for both CI/CD and users alike. + +You should reduce CI/CD pipeline concurrency by staggering them to run at different times. For example, a set running at one time and another set running several +minutes later. + +#### Shallow cloning + +GitLab and GitLab Runner perform a [shallow clone](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone) +by default. + +Ideally, you should always use `GIT_DEPTH` with a small number +like 10. This instructs GitLab Runner to perform shallow clones. +Shallow clones make Git request only the latest set of changes for a given branch, +up to desired number of commits as defined by the `GIT_DEPTH` variable. + +This significantly speeds up fetching of changes from Git repositories, +especially if the repository has a very long backlog consisting of a number +of big files because we effectively reduce amount of data transfer. +The following pipeline configuration example makes the runner shallow clone to fetch only a given branch. +The runner does not fetch any other branches nor tags. + +```yaml +variables: + GIT_DEPTH: 10 + +test: + script: + - ls -al +``` + +#### Git strategy + +By default, GitLab is configured to use the [`fetch` Git strategy](../../../ci/runners/configure_runners.md#git-strategy), +which is recommended for large repositories. +This strategy reduces the amount of data to transfer and +does not really impact the operations that you might do on a repository from CI/CD. + +#### Git clone path + +[`GIT_CLONE_PATH`](../../../ci/runners/configure_runners.md#custom-build-directories) allows you to +control where you clone your repositories. This can have implications if you +heavily use big repositories with a fork-based workflow. + +A fork, from the perspective of GitLab Runner, is stored as a separate repository +with a separate worktree. That means that GitLab Runner cannot optimize the usage +of worktrees and you might have to instruct GitLab Runner to use that. + +In such cases, ideally you want to make the GitLab Runner executor be used only +for the given project and not shared across different projects to make this +process more efficient. + +The [`GIT_CLONE_PATH`](../../../ci/runners/configure_runners.md#custom-build-directories) must be +in the directory set in `$CI_BUILDS_DIR`. You can't pick any path from disk. + +#### Git clean flags + +[`GIT_CLEAN_FLAGS`](../../../ci/runners/configure_runners.md#git-clean-flags) allows you to control +whether or not you require the `git clean` command to be executed for each CI/CD +job. By default, GitLab ensures that: + +- You have your worktree on the given SHA. +- Your repository is clean. + +[`GIT_CLEAN_FLAGS`](../../../ci/runners/configure_runners.md#git-clean-flags) is disabled when set +to `none`. On very big repositories, this might be desired because `git +clean` is disk I/O intensive. Controlling that with `GIT_CLEAN_FLAGS: -ffdx +-e .build/` (for example) allows you to control and disable removal of some +directories in the worktree between subsequent runs, which can speed-up +the incremental builds. This has the biggest effect if you re-use existing +machines and have an existing worktree that you can re-use for builds. + +For exact parameters accepted by +[`GIT_CLEAN_FLAGS`](../../../ci/runners/configure_runners.md#git-clean-flags), see the documentation +for [`git clean`](https://git-scm.com/docs/git-clean). The available parameters +are dependent on the Git version. + +#### Git fetch extra flags + +[`GIT_FETCH_EXTRA_FLAGS`](../../../ci/runners/configure_runners.md#git-fetch-extra-flags) allows you +to modify `git fetch` behavior by passing extra flags. + +For example, if your project contains a large number of tags that your CI/CD jobs don't rely on, +you could add [`--no-tags`](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---no-tags) +to the extra flags to make your fetches faster and more compact. + +Also in the case where you repository does _not_ contain a lot of +tags, `--no-tags` can [make a big difference in some cases](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/746). +If your CI/CD builds do not depend on Git tags, setting `--no-tags` is worth trying. + +For more information, see the [`GIT_FETCH_EXTRA_FLAGS` documentation](../../../ci/runners/configure_runners.md#git-fetch-extra-flags). + +#### Fork-based workflow + +Following the guidelines above, let's imagine that we want to: + +- Optimize for a big project (more than 50k files in directory). +- Use forks-based workflow for contributing. +- Reuse existing worktrees. Have preconfigured runners that are pre-cloned with repositories. +- Runner assigned only to project and all forks. + +Let's consider the following two examples, one using `shell` executor and +other using `docker` executor. + +##### `shell` executor example + +Let's assume that you have the following [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +```toml +concurrent = 4 + +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "shell" + builds_dir = "/builds" + cache_dir = "/cache" + + [runners.custom_build_dir] + enabled = true +``` + +This `config.toml`: + +- Uses the `shell` executor, +- Specifies a custom `/builds` directory where all clones are stored. +- Enables the ability to specify `GIT_CLONE_PATH`, +- Runs at most 4 jobs at once. + +##### `docker` executor example + +Let's assume that you have the following [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +```toml +concurrent = 4 + +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "docker" + builds_dir = "/builds" + cache_dir = "/cache" + + [runners.docker] + volumes = ["/builds:/builds", "/cache:/cache"] +``` + +This `config.toml`: + +- Uses the `docker` executor, +- Specifies a custom `/builds` directory on disk where all clones are stored. + We host mount the `/builds` directory to make it reusable between subsequent runs + and be allowed to override the cloning strategy. +- Doesn't enable the ability to specify `GIT_CLONE_PATH` as it is enabled by default. +- Runs at most 4 jobs at once. + +##### Our `.gitlab-ci.yml` + +Once we have the executor configured, we need to fine tune our `.gitlab-ci.yml`. + +Our pipeline is most performant if we use the following `.gitlab-ci.yml`: + +```yaml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_NAME + +build: + script: ls -al +``` + +This YAML setting configures a custom clone path. This path makes it possible to re-use worktrees +between the parent project and forks because we use the same clone path for all forks. + +Why use `$CI_CONCURRENT_ID`? The main reason is to ensure that worktrees used are not conflicting +between projects. The `$CI_CONCURRENT_ID` represents a unique identifier within the given executor. +When we use it to construct the path, this directory does not conflict +with other concurrent jobs running. + +### Store custom clone options in `config.toml` + +Ideally, all job-related configuration should be stored in `.gitlab-ci.yml`. +However, sometimes it is desirable to make these schemes part of the runner's configuration. -Gitaly, the service that provides storage for Git repositories, can be configured to cache a short rolling window of Git fetch responses. This is recommended for large repositories as it can notably reduce server load when your server receives lots of fetch traffic. +In the above example of forks, making this configuration discoverable for users may be preferred, +but this brings administrative overhead as the `.gitlab-ci.yml` needs to be updated for each branch. +In such cases, it might be desirable to keep the `.gitlab-ci.yml` clone path agnostic, but make it +a configuration of the runner. -Refer to the [Gitaly Pack Objects Cache for more information](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). +We can extend our [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) +with the following specification that is used by the runner if `.gitlab-ci.yml` does not override it: -## Reference Architectures +```toml +concurrent = 4 -Large repositories tend to be found in larger organisations with many users. The GitLab Quality and Support teams provide several [Reference Architectures](../../../administration/reference_architectures/index.md) that are the recommended way to deploy GitLab at scale. +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "docker" + builds_dir = "/builds" + cache_dir = "/cache" -In these types of setups it's recommended that the GitLab environment used matches a Reference Architecture to improve performance. + environment = [ + "GIT_CLONE_PATH=$CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_NAME" + ] -## Gitaly Cluster + [runners.docker] + volumes = ["/builds:/builds", "/cache:/cache"] +``` -Gitaly Cluster can notably improve large repository performance as it holds multiple replicas of the repository across several nodes. As a result, Gitaly Cluster can load balance read requests against those repositories and is also fault-tolerant. +This makes the cloning configuration to be part of the given runner +and does not require us to update each `.gitlab-ci.yml`. -It's recommended for large repositories, however, Gitaly Cluster is a large solution with additional complexity of setup, and management. Refer to the [Gitaly Cluster documentation for more information](../../../administration/gitaly/index.md), specifically the [Before deploying Gitaly Cluster](../../../administration/gitaly/index.md#before-deploying-gitaly-cluster) section. +### Reference architectures -## Keep GitLab up to date +Large repositories tend to be found in larger organisations with many users. The GitLab Quality and Support teams provide several [reference architectures](../../../administration/reference_architectures/index.md) that are the recommended way to deploy GitLab at scale. -Performance improvements and fixes are added continuously in GitLab. As such, it's recommended you keep GitLab updated to the latest version where possible to benefit from these. +In these types of setups, the GitLab environment used should match a reference architecture to improve performance. -## Reduce concurrent clones in CI/CD +### Gitaly Cluster -Large repositories tend to be monorepos. This in turn typically means that these repositories get a lot of traffic not only from users, but from CI/CD. +Gitaly Cluster can notably improve large repository performance because it holds multiple replicas of the repository across several nodes. +As a result, Gitaly Cluster can load balance read requests against those replicas and is fault-tolerant. -CI/CD loads tend to be concurrent as pipelines are scheduled during set times. As a result, the Git requests against the repositories can spike notably during these times and lead to reduced performance for both CI and users alike. +Though Gitaly Cluster is recommended for large repositories, it is a large solution with additional complexity of setup and management. Refer to the +[Gitaly Cluster documentation for more information](../../../administration/gitaly/index.md), specifically the +[Before deploying Gitaly Cluster](../../../administration/gitaly/index.md#before-deploying-gitaly-cluster) section. -When designing CI/CD pipelines, it's advisable to reduce their concurrency by staggering them to run at different times, for example, a set running at one time, and another set running several minutes later. +### Keep GitLab up to date -There's several other actions that can be explored to improve CI/CD performance with large repositories. Refer to the [Runner documentation for more information](../../../ci/large_repositories/index.md). +You should keep GitLab updated to the latest version where possible to benefit from performance improvements and fixes are added continuously to GitLab. diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index fade9e1b63c..9d97f53cb43 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -44,7 +44,7 @@ and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab To create the webhook in the downstream instance: 1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 7ade27e556d..b16197e45b2 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -40,7 +40,7 @@ Prerequisites: - If your mirror connects with `ssh://`, the host key must be detectable on the server, or you must have a local copy of the key. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Select **Add new**. @@ -111,7 +111,7 @@ Prerequisite: - You must have at least the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories** and identify the mirror to update. @@ -124,9 +124,8 @@ When you create a mirror, you must configure the authentication method for it. GitLab supports these authentication methods: - [SSH authentication](#ssh-authentication). -- Password. +- Username and password. -When using password authentication, ensure you specify the username. For a [project access token](../../settings/project_access_tokens.md) or [group access token](../../../group/settings/group_access_tokens.md), use the username (not token name) and the token as the password. @@ -154,7 +153,7 @@ When you mirror a repository and select the **SSH public key** as your authentication method, GitLab generates a public key for you. The non-GitLab server needs this key to establish trust with your GitLab repository. To copy your SSH public key: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories**. diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index ba54c18f8ee..5b3c76d982a 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -64,14 +64,13 @@ Prerequisites: token serves as your GitHub password. - [GitLab Silent Mode](../../../../administration/silent_mode/index.md) is not enabled. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. -1. Enter the **Git repository URL**. Include the username - in the URL, if required: `https://MYUSERNAME@gitlab.com/GROUPNAME/PROJECTNAME.git` +1. Enter the **Git repository URL**. NOTE: - To mirror the `gitlab` repository, use `git@gitlab.com:gitlab-org/gitlab.git` + To mirror the `gitlab` repository, use `gitlab.com:gitlab-org/gitlab.git` or `https://gitlab.com/gitlab-org/gitlab.git`. 1. In **Mirror direction**, select **Pull**. diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index cd4fe68b01b..e18e3631d7f 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -37,7 +37,7 @@ and pulling from, remote mirrors. To set up push mirroring for an existing project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a repository URL. @@ -89,12 +89,12 @@ To configure a mirror from GitLab to GitHub: 1. Enter a **Git repository URL** with this format, changing the variables as needed: ```plaintext - https://USERNAME@github.com/GROUP/PROJECT.git + https://github.com/GROUP/PROJECT.git ``` - - `USERNAME`: The username of the owner of the personal access token. - `GROUP`: The group on GitHub. - `PROJECT`: The project on GitHub. +1. For **Username**, enter the username of the owner of the personal access token. 1. For **Password**, enter your GitHub personal access token. 1. Select **Mirror repository**. @@ -164,19 +164,17 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Open your new repository, and then select **Clone URL > 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: +1. Fill in the **Git repository URL** field using this format, replacing + `<aws-region>` with your AWS region, and + `<your_codecommit_repo>` with the name of your repository in CodeCommit: ```plaintext - https://<your_aws_git_userid>@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + https://git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> ``` - Replace `<your_aws_git_userid>` with the AWS **special HTTPS Git user ID** - from the IAM Git credentials created earlier. Replace `<your_codecommit_repo>` - with the name of your repository in CodeCommit. - -1. For **Mirror direction**, select **Push**. -1. For **Authentication method**, select **Password**. Fill in the **Password** box - with the special IAM Git clone user ID **password** created earlier in AWS. +1. For **Authentication method**, select **Username and Password**. +1. For **Username**, enter the AWS **special HTTPS Git user ID**. +1. For **Password**, enter the special IAM Git clone user ID password created earlier in AWS. 1. Leave the option **Only mirror protected branches** for CodeCommit. It pushes more frequently (from every five minutes to every minute). @@ -202,7 +200,8 @@ If it isn't working correctly, a red `error` tag appears, and shows the error me [personal access token](../../../profile/personal_access_tokens.md) with `write_repository` scope. 1. On the source GitLab instance: 1. Enter the **Git repository URL** using this format: - `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + `https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + 1. Enter the **Username** `oauth2`. 1. Enter the **Password**. Use the GitLab personal access token created on the destination GitLab instance. 1. Select **Mirror repository**. diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md index 5817aab5fc7..a83231ceb63 100644 --- a/doc/user/project/repository/mirror/troubleshooting.md +++ b/doc/user/project/repository/mirror/troubleshooting.md @@ -67,7 +67,7 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. If no repository owner is specified, delete and add the URL again in this format, @@ -168,7 +168,7 @@ Prerequisites: To resolve the issue: 1. [Verify the host key](index.md#verify-a-host-key). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. To refresh the keys, either: diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 2756149b5bd..d61d09301a5 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -39,7 +39,7 @@ Prerequisite: To create global push rules: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Push Rules**. 1. Expand **Push rules**. @@ -52,7 +52,7 @@ The push rule of an individual project overrides the global push rule. To override global push rules for a specific project, or to update the rules for an existing project to match new global push rules: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Push rules**. 1. Set the rule you want. @@ -126,7 +126,7 @@ Some validation examples: Use these rules to prevent unintended consequences. -- **Reject unsigned commits**: Commit must be signed through [GPG](gpg_signed_commits/index.md). This rule +- **Reject unsigned commits**: Commit must be signed through [GPG](signed_commits/gpg.md). This rule can block some legitimate commits [created in the Web IDE](#reject-unsigned-commits-push-rule-disables-web-ide), and allow [unsigned commits created in the GitLab UI](#unsigned-commits-created-in-the-gitlab-ui). - **Do not allow users to remove Git tags with `git push`**: Users cannot use `git push` to remove Git tags. @@ -274,7 +274,7 @@ to use them as standard characters in a match condition. ## Related topics - [Git server hooks](../../../administration/server_hooks.md) (previously called server hooks), to create complex custom push rules -- [Signing commits with GPG](gpg_signed_commits/index.md) +- [Signing commits with GPG](signed_commits/gpg.md) - [Protected branches](../protected_branches.md) ## Troubleshooting 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 590323bfadd..bfe8964a876 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 @@ -26,7 +26,7 @@ you begin. The best way to back up a repository is to The size of a repository is determined by computing the accumulated size of all files in the repository. It is similar to executing `du --summarize --bytes` on your repository's -[hashed storage path](../../../administration/repository_storage_types.md). +[hashed storage path](../../../administration/repository_storage_paths.md). ## Purge files from repository history @@ -53,7 +53,7 @@ visible even after they have been removed from the repository. To purge files from a GitLab repository: -1. Install either [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) or +1. Install [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) and optionally [`git-sizer`](https://github.com/github/git-sizer#getting-started) using a supported package manager or from source. diff --git a/doc/user/project/repository/signed_commits/gpg.md b/doc/user/project/repository/signed_commits/gpg.md new file mode 100644 index 00000000000..88f6917d4b6 --- /dev/null +++ b/doc/user/project/repository/signed_commits/gpg.md @@ -0,0 +1,284 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Sign commits with GPG **(FREE ALL)** + +You can sign the commits you make in a GitLab repository with a +GPG ([GNU Privacy Guard](https://gnupg.org/)) key. + +NOTE: +GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and +implementations. + +For GitLab to consider a commit verified: + +- The committer must have a GPG public/private key pair. +- The committer's public key must be uploaded to their GitLab account. +- One of the email addresses in the GPG public key must match a **verified** email address + used by the committer in GitLab. To keep this address private, use the automatically generated + [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) + GitLab provides in your profile. +- The committer's email address must match the verified email address from the + GPG key. + +GitLab uses its own keyring to verify the GPG signature. It does not access any +public key server. + +GPG verified tags are not supported. + +For more details about GPG, refer to the [related topics list](#related-topics). + +## View a user's public GPG key + +To view a user's public GPG key, you can either: + +- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, + if the user has configured one, or a blank page for users without a configured GPG key. +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner + of the user's profile, select **View public GPG keys** (**{key}**). + +## Configure commit signing + +To sign commits, you must configure both your local machine and your GitLab account: + +1. [Create a GPG key](#create-a-gpg-key). +1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account). +1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git). +1. [Sign your Git commits](#sign-your-git-commits). + +### Create a GPG key + +If you don't already have a GPG key, create one: + +1. [Install GPG](https://www.gnupg.org/download/) for your operating system. + If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in + the commands on this page. +1. To generate your key pair, run the command appropriate for your version of `gpg`: + + ```shell + # Use this command for the default version of GPG, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key + + # Use this command for versions of GPG later than 2.1.17: + gpg --full-gen-key + ``` + +1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select + the default option, `RSA and RSA`. +1. Select the key length, in bits. GitLab recommends 4096-bit keys. +1. Specify the validity period of your key. This value is subjective, and the + default value is no expiration. +1. To confirm your answers, enter `y`. +1. Enter your name. +1. Enter your email address. It must match a + [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits) + in your GitLab account. +1. Optional. Enter a comment to display in parentheses after your name. +1. GPG displays the information you've entered so far. Edit the information or press + <kbd>O</kbd> (for `Okay`) to continue. +1. Enter a strong password, then enter it again to confirm it. +1. To list your private GPG key, run this command, replacing + `<EMAIL>` with the email address you used when you generated the key: + + ```shell + gpg --list-secret-keys --keyid-format LONG <EMAIL> + ``` + +1. In the output, identify the `sec` line, and copy the GPG key ID. It begins after + the `/` character. In this example, the key ID is `30F2B65B9246B6CA`: + + ```plaintext + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` + +1. To show the associated public key, run this command, replacing `<ID>` with the + GPG key ID from the previous step: + + ```shell + gpg --armor --export <ID> + ``` + +1. Copy the public key, including the `BEGIN PGP PUBLIC KEY BLOCK` and + `END PGP PUBLIC KEY BLOCK` lines. You need this key in the next step. + +### Add a GPG key to your account + +To add a GPG key to your user settings: + +1. Sign in to GitLab. +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **GPG Keys** (**{key}**). +1. Select **Add new key**. +1. In **Key**, paste your _public_ key. +1. To add the key to your account, select **Add key**. GitLab shows the key's + fingerprint, email address, and creation date: + +  + +After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. + +### Associate your GPG key with Git + +After you [create your GPG key](#create-a-gpg-key) and +[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git +to use this key: + +1. Run this command to list the private GPG key you just created, + replacing `<EMAIL>` with the email address for your key: + + ```shell + gpg --list-secret-keys --keyid-format LONG <EMAIL> + ``` + +1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is + `30F2B65B9246B6CA`: + + ```plaintext + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` + +1. Run this command to configure Git to sign your commits with your key, + replacing `<KEY ID>` with your GPG key ID: + + ```shell + git config --global user.signingkey <KEY ID> + ``` + +### Sign your Git commits + +After you [add your public key to your account](#add-a-gpg-key-to-your-account), +you can sign individual commits manually, or configure Git to default to signed commits: + +- Sign individual Git commits manually: + 1. Add `-S` flag to any commit you want to sign: + + ```shell + git commit -S -m "My commit message" + ``` + + 1. Enter the passphrase of your GPG key when asked. + 1. Push to GitLab and check that your commits [are verified](../signed_commits/index.md#verify-commits). +- Sign all Git commits by default by running this command: + + ```shell + git config --global commit.gpgsign true + ``` + +#### Set signing key conditionally + +If you maintain signing keys for separate purposes, such as work and personal +use, use an `IncludeIf` statement in your `.gitconfig` file to set which key +you sign commits with. + +Prerequisites: + +- Requires Git version 2.13 or later. + +1. In the same directory as your main `~/.gitconfig` file, create a second file, + such as `.gitconfig-gitlab`. +1. In your main `~/.gitconfig` file, add your Git settings for work in non-GitLab projects. +1. Append this information to the end of your main `~/.gitconfig` file: + + ```ini + # The contents of this file are included only for GitLab.com URLs + [includeIf "hasconfig:remote.*.url:https://gitlab.com/**"] + + # Edit this line to point to your alternate configuration file + path = ~/.gitconfig-gitlab + ``` + +1. In your alternate `.gitconfig-gitlab` file, add the configuration overrides to + use when you're committing to a GitLab repository. All settings from your + main `~/.gitconfig` file are retained unless you explicitly override them. + In this example, + + ```ini + # Alternate ~/.gitconfig-gitlab file + # These values are used for repositories matching the string 'gitlab.com', + # and override their corresponding values in ~/.gitconfig + + [user] + email = you@example.com + signingkey = <KEY ID> + + [commit] + gpgsign = true + ``` + +## Revoke a GPG key + +If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. + +To revoke a GPG key: + +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **GPG Keys** (**{key}**). +1. Select **Revoke** next to the GPG key you want to delete. + +## Remove a GPG key + +When you remove a GPG key from your GitLab account: + +- Previous commits signed with this key remain verified. +- Future commits (including any commits created but not yet pushed) that attempt + to use this key are unverified. + +To remove a GPG key from your account: + +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **GPG Keys** (**{key}**). +1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. + +If you must unverify both future and past commits, +[revoke the associated GPG key](#revoke-a-gpg-key) instead. + +## Related topics + +- GPG resources: + - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) + - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) + - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) + - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) + - [Review existing GPG keys in your instance](../../../../administration/credentials_inventory.md#review-existing-gpg-keys) + +## Troubleshooting + +### Secret key not available + +If you receive the errors `secret key not available` +or `gpg: signing failed: secret key not available`, try using `gpg2` instead of `gpg`: + +```shell +git config --global gpg.program gpg2 +``` + +If your GPG key is password protected and the password entry prompt does not appear, +add `export GPG_TTY=$(tty)` to your shell's `rc` file (commonly `~/.bashrc` or `~/.zshrc`) + +### GPG failed to sign the data + +If your GPG key is password protected and you receive the error: + +```shell +error: gpg failed to sign the data +fatal: failed to write commit object +``` + +If the password entry prompt does not appear, add `export GPG_TTY=$(tty)` to your shell's `rc` file +(commonly `~/.bashrc` or `~/.zshrc`) and restart your terminal. diff --git a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png b/doc/user/project/repository/signed_commits/img/profile_settings_gpg_keys_single_key.png Binary files differindex ae0a8696c6c..ae0a8696c6c 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png +++ b/doc/user/project/repository/signed_commits/img/profile_settings_gpg_keys_single_key.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_and_unsigned_commits.png b/doc/user/project/repository/signed_commits/img/project_signed_and_unsigned_commits.png Binary files differindex e1d44f15f3f..e1d44f15f3f 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/project_signed_and_unsigned_commits.png +++ b/doc/user/project/repository/signed_commits/img/project_signed_and_unsigned_commits.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_unverified_signature.png b/doc/user/project/repository/signed_commits/img/project_signed_commit_unverified_signature.png Binary files differindex 763a677f94a..763a677f94a 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_unverified_signature.png +++ b/doc/user/project/repository/signed_commits/img/project_signed_commit_unverified_signature.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_verified_signature.png b/doc/user/project/repository/signed_commits/img/project_signed_commit_verified_signature.png Binary files differindex 1b6fa3fc2e2..1b6fa3fc2e2 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_verified_signature.png +++ b/doc/user/project/repository/signed_commits/img/project_signed_commit_verified_signature.png diff --git a/doc/user/project/repository/signed_commits/index.md b/doc/user/project/repository/signed_commits/index.md new file mode 100644 index 00000000000..e6632ecb81a --- /dev/null +++ b/doc/user/project/repository/signed_commits/index.md @@ -0,0 +1,64 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Signed commits **(FREE ALL)** + +When you add a cryptographic signature to your commit, you provide extra assurance that a commit +originated from you, rather than an impersonator. If GitLab can verify a commit +author's identity with a public GPG key, the commit is marked **Verified** in the +GitLab UI. You can then configure [push rules](../push_rules.md) +for your project to reject individual commits not signed with GPG, or reject all +commits from unverified users. + +Sign commits with your: + +- [SSH key](ssh.md). +- [GPG key](gpg.md). +- [Personal x.509 certificate](x509.md). + +## Verify commits + +You can review commits for a merge request, or for an entire project, to confirm +they are signed: + +1. To review commits for a project: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Code > Commits**. +1. To review commits for a merge request: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Merge requests**, then select your merge request. + 1. Select **Commits**. +1. Identify the commit you want to review. Signed commits show either a **Verified** + or **Unverified** badge, depending on the verification status of the signature. + Unsigned commits do not display a badge: + +  + +1. To display the signature details for a commit, select **Verified** to see + the fingerprint or key ID: + +  + +  + +You can also [use the Commits API](../../../../api/commits.md#get-gpg-signature-of-a-commit) +to check a commit's signature. + +## Troubleshooting + +### Fix verification problems with signed commits + +The verification process for commits signed with GPG keys or X.509 certificates +can fail for multiple reasons: + +| Value | Description | Possible Fixes | +|-----------------------------|-------------|----------------| +| `UNVERIFIED` | The commit signature is not valid. | Sign the commit with a valid signature. | +| `SAME_USER_DIFFERENT_EMAIL` | The GPG key used to sign the commit does not contain the committer email, but does contain a different valid email for the committer. | Amend the commit to use an email address that matches the GPG key, or update the GPG key [to include the email address](https://security.stackexchange.com/a/261468). | +| `OTHER_USER` | The signature and GPG key are valid, but the key belongs to a different user than the committer. | Amend the commit to use the correct email address, or amend the commit to use a GPG key associated with your user. | +| `UNVERIFIED_KEY` | The key associated with the GPG signature has no verified email address associated with the committer. | Add and verify the email to your GitLab profile, [update the GPG key to include the email address](https://security.stackexchange.com/a/261468), or amend the commit to use a different committer email address. | +| `UNKNOWN_KEY` | The GPG key associated with the GPG signature for this commit is unknown to GitLab. | [Add the GPG key](gpg.md#add-a-gpg-key-to-your-account) to your GitLab profile. | +| `MULTIPLE_SIGNATURES` | Multiple GPG or X.509 signatures have been found for the commit. | Amend the commit to use only one GPG or X.509 signature. | diff --git a/doc/user/project/repository/signed_commits/ssh.md b/doc/user/project/repository/signed_commits/ssh.md new file mode 100644 index 00000000000..3572e56da84 --- /dev/null +++ b/doc/user/project/repository/signed_commits/ssh.md @@ -0,0 +1,167 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Sign commits with SSH keys **(FREE ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed. + +When you sign commits with SSH keys, GitLab uses the SSH public keys associated +with your GitLab account to cryptographically verify the commit signature. +If successful, GitLab displays a **Verified** label on the commit. + +You may use the same SSH keys for `git+ssh` authentication to GitLab +and signing commit signatures as long as their usage type is **Authentication & Signing**. +It can be verified on the page for [adding an SSH key to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account). + +For more information about managing the SSH keys associated with your GitLab account, see +[Use SSH keys to communicate with GitLab](../../../ssh.md). + +## Configure Git to sign commits with your SSH key + +After you [create an SSH key](../../../ssh.md#generate-an-ssh-key-pair) and +[add it to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) +or [generate it using a password manager](../../../ssh.md#generate-an-ssh-key-pair-with-a-password-manager), +configure Git to begin using the key. + +Prerequisites: + +- Git 2.34.0 or newer. +- OpenSSH 8.0 or newer. + + NOTE: + OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8. + +- A SSH key with the usage type of either **Authentication & Signing** or **Signing**. + The SSH key must be one of these types: + - [ED25519](../../../ssh.md#ed25519-ssh-keys) (recommended) + - [RSA](../../../ssh.md#rsa-ssh-keys) + +To configure Git to use your key: + +1. Configure Git to use SSH for commit signing: + + ```shell + git config --global gpg.format ssh + ``` + +1. Specify which SSH key should be used as the signing key, changing the filename + (here, `~/.ssh/examplekey`) to the location of your key. The filename may + differ, depending on how you generated your key: + + ```shell + git config --global user.signingkey ~/.ssh/examplekey + ``` + +## Sign commits with your SSH key + +Prerequisites: + +- You've [created an SSH key](../../../ssh.md#generate-an-ssh-key-pair). +- You've [added the key](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) to your GitLab account. +- You've [configured Git to sign commits](#configure-git-to-sign-commits-with-your-ssh-key) with your SSH key. + +To sign a commit: + +1. Use the `-S` flag when signing your commits: + + ```shell + git commit -S -m "My commit msg" + ``` + +1. Optional. If you don't want to type the `-S` flag every time you commit, tell + Git to sign your commits automatically: + + ```shell + git config --global commit.gpgsign true + ``` + +1. If your SSH key is protected, Git prompts you to enter your passphrase. +1. Push to GitLab. +1. Check that your commits [are verified](#verify-commits). + Signature verification uses the `allowed_signers` file to associate emails and SSH keys. + For help configuring this file, read [Verify commits locally](#verify-commits-locally). + +## Verify commits + +You can verify all types of signed commits +[in the GitLab UI](../signed_commits/index.md#verify-commits). Commits signed +with an SSH key can also be verified locally. + +### Verify commits locally + +To verify commits locally, create an +[allowed signers file](https://man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) +for Git to associate SSH public keys with users: + +1. Create an allowed signers file: + + ```shell + touch allowed_signers + ``` + +1. Configure the `allowed_signers` file in Git: + + ```shell + git config gpg.ssh.allowedSignersFile "$(pwd)/allowed_signers" + ``` + +1. Add your entry to the allowed signers file. Use this command to add your + email address and public SSH key to the `allowed_signers` file. Replace `<MY_KEY>` + with the name of your key, and `~/.ssh/allowed_signers` + with the location of your project's `allowed_signers` file: + + ```shell + # Modify this line to meet your needs. + # Declaring the `git` namespace helps prevent cross-protocol attacks. + echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/<MY_KEY>.pub)" >> ~/.ssh/allowed_signers + ``` + + The resulting entry in the `allowed_signers` file contains your email address, key type, + and key contents, like this: + + ```plaintext + example@gitlab.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmaTS47vRmsKyLyK1jlIFJn/i8wdGQ3J49LYyIYJ2hv + ``` + +1. Repeat the previous step for each user who you want to verify signatures for. + Consider checking this file in to your Git repository if you want to locally + verify signatures for many different contributors. + +1. Use `git log --show-signature` to view the signature status for the commits: + + ```shell + $ git log --show-signature + + commit e2406b6cd8ebe146835ceab67ff4a5a116e09154 (HEAD -> main, origin/main, origin/HEAD) + Good "git" signature for johndoe@example.com with ED25519 key SHA256:Ar44iySGgxic+U6Dph4Z9Rp+KDaix5SFGFawovZLAcc + Author: John Doe <johndoe@example.com> + Date: Tue Nov 29 06:54:15 2022 -0600 + + SSH signed commit + ``` + +## Revoke an SSH key for signing commits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9. + +If an SSH key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. + +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. Select **Revoke** next to the SSH key you want to delete. + +## Related topics + +- [Sign commits and tags with X.509 certificates](../signed_commits/x509.md) +- [Sign commits with GPG](gpg.md) +- [Commits API](../../../../api/commits.md) diff --git a/doc/user/project/repository/signed_commits/x509.md b/doc/user/project/repository/signed_commits/x509.md new file mode 100644 index 00000000000..17767cbd8f4 --- /dev/null +++ b/doc/user/project/repository/signed_commits/x509.md @@ -0,0 +1,362 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Sign commits and tags with X.509 certificates **(FREE ALL)** + +[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key +certificates issued by a public or private Public Key Infrastructure (PKI). +Personal X.509 certificates are used for authentication or signing purposes +such as S/MIME (Secure/Multipurpose Internet Mail Extensions). +However, Git also supports signing of commits and tags with X.509 certificates in a +similar way as with [GPG (GnuPG, or GNU Privacy Guard)](gpg.md). +The main difference is the way GitLab determines whether or not the developer's signature is trusted: + +- For X.509, a root certificate authority is added to the GitLab trust store. + (A trust store is a repository of trusted security certificates.) Combined with + any required intermediate certificates in the signature, the developer's certificate + can be chained back to a trusted root certificate. +- For GPG, developers [add their GPG key](gpg.md#add-a-gpg-key-to-your-account) + to their account. + +GitLab uses its own certificate store and therefore defines the +[trust chain](https://www.ssl.com/faqs/what-is-a-certificate-authority/). +For a commit or tag to be *verified* by GitLab: + +- The signing certificate email must match a verified email address in GitLab. +- The GitLab instance must be able to establish a full trust chain + from the certificate in the signature to a trusted certificate in the GitLab certificate store. + This chain may include intermediate certificates supplied in the signature. You may + need to add certificates, such as Certificate Authority root certificates, + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). +- The signing time must be in the time range of the + [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), + which is usually up to three years. +- The signing time is equal to, or later than, the commit time. + +If a commit's status has already been determined and stored in the database, +use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md). +Refer to the [Troubleshooting section](#troubleshooting). +GitLab checks certificate revocation lists on a daily basis with a background worker. + +## Limitations + +- Certificates without `authorityKeyIdentifier`, + `subjectKeyIdentifier`, and `crlDistributionPoints` display as **Unverified**. We + recommend using certificates from a PKI that are in line with + [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280). +- If you have more than one email in the Subject Alternative Name list in + your signing certificate, + [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). +- The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the + signing certificate + [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). + If your SKI is shorter, commits don't show as verified in GitLab, and + short subject key identifiers may also + [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), + such as 'An error occurred while loading commit signatures' and + `HTTP 422 Unprocessable Entity` errors. + +## Configure for signed commits + +To sign your commits, tags, or both, you must: + +1. [Obtain an X.509 key pair](#obtain-an-x509-key-pair). +1. [Associate your X.509 certificate with Git](#associate-your-x509-certificate-with-git). +1. [Sign and verify commits](#sign-and-verify-commits). +1. [Sign and verify tags](#sign-and-verify-tags). + +### Obtain an X.509 key pair + +If your organization has Public Key Infrastructure (PKI), that PKI provides +an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either +create your own self-signed pair, or purchase a pair. + +### Associate your X.509 certificate with Git + +To take advantage of X.509 signing, you need Git 2.19.0 or later. You can +check your Git version with the command `git --version`. + +If you have the correct version, you can proceed to configure Git. + +### Linux + +Configure Git to use your key for signing: + +```shell +signingkey=$( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' ) +git config --global user.signingkey $signingkey +git config --global gpg.format x509 +``` + +#### Windows and macOS + +To configure Windows or macOS: + +1. Install [S/MIME Sign](https://github.com/github/smimesign) by either: + - Downloading the installer. + - Running `brew install smimesign` on macOS. +1. Get the ID of your certificate by running `smimesign --list-keys`. +1. Set your signing key by running `git config --global user.signingkey <ID>`, replacing `<ID>` with the certificate ID. +1. Configure X.509 with this command: + + ```shell + git config --global gpg.x509.program smimesign + git config --global gpg.format x509 + ``` + +### Sign and verify commits + +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you +can sign your commits: + +1. When you create a Git commit, add the `-S` flag: + + ```shell + git commit -S -m "feat: x509 signed commits" + ``` + +1. Push to GitLab, and check that your commits are verified with the `--show-signature` flag: + + ```shell + git log --show-signature + ``` + +1. *If you don't want to type the `-S` flag every time you commit,* run this command + for Git to sign your commits every time: + + ```shell + git config --global commit.gpgsign true + ``` + +### Sign and verify tags + +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you +can start signing your tags: + +1. When you create a Git tag, add the `-s` flag: + + ```shell + git tag -s v1.1.1 -m "My signed tag" + ``` + +1. Push to GitLab and verify your tags are signed with this command: + + ```shell + git tag --verify v1.1.1 + ``` + +1. *If you don't want to type the `-s` flag every time you tag,* run this command + for Git to sign your tags each time: + + ```shell + git config --global tag.gpgsign true + ``` + +## Related topics + +- [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) + +## Troubleshooting + +For committers without administrator access, review the list of +[verification problems with signed commits](../signed_commits/index.md#fix-verification-problems-with-signed-commits) +for possible fixes. The other troubleshooting suggestions on this page require +administrator access. + +### Re-verify commits + +GitLab stores the status of any checked commits in the database. You can use a +Rake task to [check the status of any previously checked commits](../../../../raketasks/x509_signatures.md). + +After you make any changes, run this command: + +```shell +sudo gitlab-rake gitlab:x509:update_signatures +``` + +### Main verification checks + +The code performs +[these key checks](https://gitlab.com/gitlab-org/gitlab/-/blob/v14.1.0-ee/lib/gitlab/x509/signature.rb#L33), +which all must return `verified`: + +- `x509_certificate.nil?` should be false. +- `x509_certificate.revoked?` should be false. +- `verified_signature` should be true. +- `user.nil?` should be false. +- `user.verified_emails.include?(@email)` should be true. +- `certificate_email == @email` should be true. + +To investigate why a commit shows as `Unverified`: + +1. [Start a Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```shell + sudo gitlab-rails console + ``` + +1. Identify the project (either by path or ID) and full commit SHA that you're investigating. + Use this information to create `signature` to run other checks against: + + ```ruby + project = Project.find_by_full_path('group/subgroup/project') + project = Project.find_by_id('121') + commit = project.repository.commit_by(oid: '87fdbd0f9382781442053b0b76da729344e37653') + signedcommit=Gitlab::X509::Commit.new(commit) + signature=Gitlab::X509::Signature.new(signedcommit.signature_text, signedcommit.signed_text, commit.committer_email, commit.created_at) + ``` + + If you make changes to address issues identified running through the checks, restart the + Rails console and run though the checks again from the start. + +1. Check the certificate on the commit: + + ```ruby + signature.x509_certificate.nil? + signature.x509_certificate.revoked? + ``` + + Both checks should return `false`: + + ```ruby + > signature.x509_certificate.nil? + => false + > signature.x509_certificate.revoked? + => false + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332503) causes + these checks to fail with `Validation failed: Subject key identifier is invalid`. + +1. Run a cryptographic check on the signature. The code must return `true`: + + ```ruby + signature.verified_signature + ``` + + If it returns `false` then [investigate this check further](#cryptographic-verification-checks). + +1. Confirm the email addresses match on the commit and the signature: + + - The Rails console displays the email addresses being compared. + - The final command must return `true`: + + ```ruby + sigemail=signature.__send__:certificate_email + commitemail=commit.committer_email + sigemail == commitemail + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336677) exists: + only the first email in the `Subject Alternative Name` list is compared. To + display the `Subject Alternative Name` list, run: + + ```ruby + signature.__send__ :get_certificate_extension,'subjectAltName' + ``` + + If the developer's email address is not the first one in the list, this check + fails, and the commit is marked `unverified`. + +1. The email address on the commit must be associated with an account in GitLab. + This check should return `false`: + + ```ruby + signature.user.nil? + ``` + +1. Check the email address is associated with a user in GitLab. This check should + return a user, such as `#<User id:1234 @user_handle>`: + + ```ruby + User.find_by_any_email(commit.committer_email) + ``` + + If it returns `nil`, the email address is not associated with a user, and the check fails. + +1. Confirm the developer's email address is verified. This check must return true: + + ```ruby + signature.user.verified_emails.include?(commit.committer_email) + ``` + + If the previous check returned `nil`, this command displays an error: + + ```plaintext + NoMethodError (undefined method `verified_emails' for nil:NilClass) + ``` + +1. The verification status is stored in the database. To display the database record: + + ```ruby + pp CommitSignatures::X509CommitSignature.by_commit_sha(commit.sha);nil + ``` + + If all the previous checks returned the correct values: + + - `verification_status: "unverified"` indicates the database record needs + updating. [Use the Rake task](#re-verify-commits). + + - `[]` indicates the database doesn't have a record yet. Locate the commit + in GitLab to check the signature and store the result. + +#### Cryptographic verification checks + +If GitLab determines that `verified_signature` is `false`, investigate the reason +in the Rails console. These checks require `signature` to exist. Refer to the `signature` +step of the previous [main verification checks](#main-verification-checks). + +1. Check the signature, without checking the issuer, returns `true`: + + ```ruby + signature.__send__ :valid_signature? + ``` + +1. Check the signing time and date. This check must return `true`: + + ```ruby + signature.__send__ :valid_signing_time? + ``` + + - The code allows for code signing certificates to expire. + - A commit must be signed during the validity period of the certificate, + and at or after the commit's datestamp. Display the commit time and + certificate details including `not_before`, `not_after` with: + + ```ruby + commit.created_at + pp signature.__send__ :cert; nil + ``` + +1. Check the signature, including that TLS trust can be established. This check must return `true`: + + ```ruby + signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) + ``` + + 1. If this fails, add the missing certificates required to establish trust + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). + + 1. After adding more certificates, (if these troubleshooting steps then pass) + run the Rake task to [re-verify commits](#re-verify-commits). + + 1. Display the certificates, including in the signature: + + ```ruby + pp signature.__send__(:p7).certificates ; nil + ``` + +Ensure any additional intermediate certificates and the root certificate are added +to the certificate store. For consistency with how certificate chains are built on +web servers: + +- Git clients that are signing commits should include the certificate + and all intermediate certificates in the signature. +- The GitLab certificate store should only contain the root. + +If you remove a root certificate from the GitLab +trust store, such as when it expires, commit signatures which chain back to that +root display as `unverified`. diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index d8d798ac651..89e3d811dba 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -1,181 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../signed_commits/ssh.md' +remove_date: '2023-12-01' --- -# Sign commits with SSH keys **(FREE ALL)** +This document was moved to [another location](../signed_commits/ssh.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed. - -Use SSH keys to sign Git commits in the same manner as -[GPG signed commits](../gpg_signed_commits/index.md). When you sign commits -with SSH keys, GitLab uses the SSH public keys associated with your -GitLab account to cryptographically verify the commit signature. -If successful, GitLab displays a **Verified** label on the commit. - -You may use the same SSH keys for `git+ssh` authentication to GitLab -and signing commit signatures as long as their usage type is **Authentication & Signing**. -It can be verified on the page for [adding an SSH key to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account). - -For more information about managing the SSH keys associated with your GitLab account, see -[Use SSH keys to communicate with GitLab](../../../ssh.md). - -## Configure Git to sign commits with your SSH key - -After you [create an SSH key](../../../ssh.md#generate-an-ssh-key-pair) and -[add it to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) -or [generate it using a password manager](../../../ssh.md#generate-an-ssh-key-pair-with-a-password-manager), -configure Git to begin using the key. - -Prerequisites: - -- Git 2.34.0 or newer. -- OpenSSH 8.0 or newer. - - NOTE: - OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8. - -- A SSH key with the usage type of either **Authentication & Signing** or **Signing**. - The SSH key must be one of these types: - - [ED25519](../../../ssh.md#ed25519-ssh-keys) (recommended) - - [RSA](../../../ssh.md#rsa-ssh-keys) - -To configure Git to use your key: - -1. Configure Git to use SSH for commit signing: - - ```shell - git config --global gpg.format ssh - ``` - -1. Specify which SSH key should be used as the signing key, changing the filename - (here, `~/.ssh/examplekey`) to the location of your key. The filename may - differ, depending on how you generated your key: - - ```shell - git config --global user.signingkey ~/.ssh/examplekey - ``` - -## Sign commits with your SSH key - -Prerequisites: - -- You've [created an SSH key](../../../ssh.md#generate-an-ssh-key-pair). -- You've [added the key](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) to your GitLab account. -- You've [configured Git to sign commits](#configure-git-to-sign-commits-with-your-ssh-key) with your SSH key. - -To sign a commit: - -1. Use the `-S` flag when signing your commits: - - ```shell - git commit -S -m "My commit msg" - ``` - -1. Optional. If you don't want to type the `-S` flag every time you commit, tell - Git to sign your commits automatically: - - ```shell - git config --global commit.gpgsign true - ``` - -1. If your SSH key is protected, Git prompts you to enter your passphrase. -1. Push to GitLab. -1. Check that your commits [are verified](#verify-commits). - Signature verification uses the `allowed_signers` file to associate emails and SSH keys. - For help configuring this file, read [Verify commits locally](#verify-commits-locally). - -## Verify commits - -You can review commits for a merge request, or for an entire project, to confirm -they are signed: - -1. To review commits for a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Commits**. -1. To review commits for a merge request: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. On the left sidebar, select **Merge requests**, then select your merge request. - 1. Select **Commits**. -1. Identify the commit you want to review. Signed commits show either a **Verified** - or **Unverified** badge, depending on the verification status of the signature. - Unsigned commits do not display a badge. -1. To display the signature details for a commit, select **Verified**. GitLab shows - the SSH key's fingerprint. - -## Verify commits locally - -To verify commits locally, create an -[allowed signers file](https://man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) -for Git to associate SSH public keys with users: - -1. Create an allowed signers file: - - ```shell - touch allowed_signers - ``` - -1. Configure the `allowed_signers` file in Git: - - ```shell - git config gpg.ssh.allowedSignersFile "$(pwd)/allowed_signers" - ``` - -1. Add your entry to the allowed signers file. Use this command to add your - email address and public SSH key to the `allowed_signers` file. Replace `<MY_KEY>` - with the name of your key, and `~/.ssh/allowed_signers` - with the location of your project's `allowed_signers` file: - - ```shell - # Modify this line to meet your needs. - # Declaring the `git` namespace helps prevent cross-protocol attacks. - echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/<MY_KEY>.pub)" >> ~/.ssh/allowed_signers - ``` - - The resulting entry in the `allowed_signers` file contains your email address, key type, - and key contents, like this: - - ```plaintext - example@gitlab.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmaTS47vRmsKyLyK1jlIFJn/i8wdGQ3J49LYyIYJ2hv - ``` - -1. Repeat the previous step for each user who you want to verify signatures for. - Consider checking this file in to your Git repository if you want to locally - verify signatures for many different contributors. - -1. Use `git log --show-signature` to view the signature status for the commits: - - ```shell - $ git log --show-signature - - commit e2406b6cd8ebe146835ceab67ff4a5a116e09154 (HEAD -> main, origin/main, origin/HEAD) - Good "git" signature for johndoe@example.com with ED25519 key SHA256:Ar44iySGgxic+U6Dph4Z9Rp+KDaix5SFGFawovZLAcc - Author: John Doe <johndoe@example.com> - Date: Tue Nov 29 06:54:15 2022 -0600 - - SSH signed commit - ``` - -## Revoke an SSH key for signing commits - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9. - -If an SSH key becomes compromised, revoke it. Revoking a key changes both future and past commits: - -- Past commits signed by this key are marked as unverified. -- Future commits signed by this key are marked as unverified. - -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. Select **Revoke** next to the SSH key you want to delete. - -## Related topics - -- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) -- [Sign commits with GPG](../gpg_signed_commits/index.md) -- [Commits API](../../../../api/commits.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/tags/index.md b/doc/user/project/repository/tags/index.md index 5a01d6f2085..765f5539244 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -44,14 +44,14 @@ In the GitLab UI, each tag displays: To view all existing tags for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Tags**. ## View tagged commits in the commits list > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Commits**. 1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag. This example shows a commit tagged `v1.26.0`: @@ -88,7 +88,7 @@ To create either a lightweight or annotated tag from the command line, and push To create a tag from the GitLab UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Tags**. 1. Select **New tag**. 1. Provide a **Tag name**. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 121a7b41f54..3acc62186a3 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -25,7 +25,7 @@ for any change you commit through the Web Editor. To create a text file in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. @@ -35,7 +35,7 @@ To create a text file in the Web Editor: ### Create a file from a template -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Next to the project name, select the plus icon (**{plus}**) to display a dropdown list, then select **New file** from the list. @@ -56,7 +56,7 @@ To create a text file in the Web Editor: To edit a text file in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Go to your file. 1. In the upper right, select **Edit > Edit single file**. @@ -105,7 +105,7 @@ To upload a binary file in the Web Editor: <!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> <!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **Upload file**. 1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -115,7 +115,7 @@ To upload a binary file in the Web Editor: To create a directory in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New directory**. 1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -125,7 +125,7 @@ To create a directory in the Web Editor: To create a [branch](branches/index.md) in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New branch**. 1. Complete the fields. @@ -136,7 +136,7 @@ To create a [branch](branches/index.md) in the Web Editor: You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New tag**. 1. Complete the fields. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 20860718b43..ae418581820 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,366 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../signed_commits/x509.md' +remove_date: '2023-12-01' --- -# Sign commits and tags with X.509 certificates **(FREE ALL)** +This document was moved to [another location](../signed_commits/x509.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. - -[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key -certificates issued by a public or private Public Key Infrastructure (PKI). -Personal X.509 certificates are used for authentication or signing purposes -such as S/MIME (Secure/Multipurpose Internet Mail Extensions). -However, Git also supports signing of commits and tags with X.509 certificates in a -similar way as with [GPG (GnuPG, or GNU Privacy Guard)](../gpg_signed_commits/index.md). -The main difference is the way GitLab determines whether or not the developer's signature is trusted: - -- For X.509, a root certificate authority is added to the GitLab trust store. - (A trust store is a repository of trusted security certificates.) Combined with - any required intermediate certificates in the signature, the developer's certificate - can be chained back to a trusted root certificate. -- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#add-a-gpg-key-to-your-account) - to their account. - -GitLab uses its own certificate store and therefore defines the -[trust chain](https://www.ssl.com/faqs/what-is-a-certificate-authority/). -For a commit or tag to be *verified* by GitLab: - -- The signing certificate email must match a verified email address in GitLab. -- The GitLab instance must be able to establish a full trust chain - from the certificate in the signature to a trusted certificate in the GitLab certificate store. - This chain may include intermediate certificates supplied in the signature. You may - need to add certificates, such as Certificate Authority root certificates, - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). -- The signing time must be in the time range of the - [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), - which is usually up to three years. -- The signing time is equal to, or later than, the commit time. - -If a commit's status has already been determined and stored in the database, -use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md). -Refer to the [Troubleshooting section](#troubleshooting). -GitLab checks certificate revocation lists on a daily basis with a background worker. - -## Limitations - -- Self-signed certificates without `authorityKeyIdentifier`, - `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We - recommend using certificates from a PKI that are in line with - [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280). -- If you have more than one email in the Subject Alternative Name list in - your signing certificate, - [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). -- The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the - signing certificate - [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). - If your SKI is shorter, commits don't show as verified in GitLab, and - short subject key identifiers may also - [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), - such as 'An error occurred while loading commit signatures' and - `HTTP 422 Unprocessable Entity` errors. - -## Configure for signed commits - -To sign your commits, tags, or both, you must: - -1. [Obtain an X.509 key pair](#obtain-an-x509-key-pair). -1. [Associate your X.509 certificate with Git](#associate-your-x509-certificate-with-git). -1. [Sign and verify commits](#sign-and-verify-commits). -1. [Sign and verify tags](#sign-and-verify-tags). - -### Obtain an X.509 key pair - -If your organization has Public Key Infrastructure (PKI), that PKI provides -an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either -create your own self-signed pair, or purchase a pair. - -### Associate your X.509 certificate with Git - -To take advantage of X.509 signing, you need Git 2.19.0 or later. You can -check your Git version with the command `git --version`. - -If you have the correct version, you can proceed to configure Git. - -### Linux - -Configure Git to use your key for signing: - -```shell -signingkey=$( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' ) -git config --global user.signingkey $signingkey -git config --global gpg.format x509 -``` - -#### Windows and macOS - -To configure Windows or macOS: - -1. Install [S/MIME Sign](https://github.com/github/smimesign) by either: - - Downloading the installer. - - Running `brew install smimesign` on macOS. -1. Get the ID of your certificate by running `smimesign --list-keys`. -1. Set your signing key by running `git config --global user.signingkey <ID>`, replacing `<ID>` with the certificate ID. -1. Configure X.509 with this command: - - ```shell - git config --global gpg.x509.program smimesign - git config --global gpg.format x509 - ``` - -### Sign and verify commits - -After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you -can sign your commits: - -1. When you create a Git commit, add the `-S` flag: - - ```shell - git commit -S -m "feat: x509 signed commits" - ``` - -1. Push to GitLab, and check that your commits are verified with the `--show-signature` flag: - - ```shell - git log --show-signature - ``` - -1. *If you don't want to type the `-S` flag every time you commit,* run this command - for Git to sign your commits every time: - - ```shell - git config --global commit.gpgsign true - ``` - -### Sign and verify tags - -After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you -can start signing your tags: - -1. When you create a Git tag, add the `-s` flag: - - ```shell - git tag -s v1.1.1 -m "My signed tag" - ``` - -1. Push to GitLab and verify your tags are signed with this command: - - ```shell - git tag --verify v1.1.1 - ``` - -1. *If you don't want to type the `-s` flag every time you tag,* run this command - for Git to sign your tags each time: - - ```shell - git config --global tag.gpgsign true - ``` - -## Related topics - -- [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) -- [Sign commits with GPG](../gpg_signed_commits/index.md) -- [Sign commits with SSH keys](../ssh_signed_commits/index.md) - -## Troubleshooting - -For committers without administrator access, review the list of -[verification problems with signed commits](../gpg_signed_commits/index.md#fix-verification-problems-with-signed-commits) -for possible fixes. The other troubleshooting suggestions on this page require -administrator access. - -### Re-verify commits - -GitLab stores the status of any checked commits in the database. You can use a -Rake task to [check the status of any previously checked commits](../../../../raketasks/x509_signatures.md). - -After you make any changes, run this command: - -```shell -sudo gitlab-rake gitlab:x509:update_signatures -``` - -### Main verification checks - -The code performs -[these key checks](https://gitlab.com/gitlab-org/gitlab/-/blob/v14.1.0-ee/lib/gitlab/x509/signature.rb#L33), -which all must return `verified`: - -- `x509_certificate.nil?` should be false. -- `x509_certificate.revoked?` should be false. -- `verified_signature` should be true. -- `user.nil?` should be false. -- `user.verified_emails.include?(@email)` should be true. -- `certificate_email == @email` should be true. - -To investigate why a commit shows as `Unverified`: - -1. [Start a Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session): - - ```shell - sudo gitlab-rails console - ``` - -1. Identify the project (either by path or ID) and full commit SHA that you're investigating. - Use this information to create `signature` to run other checks against: - - ```ruby - project = Project.find_by_full_path('group/subgroup/project') - project = Project.find_by_id('121') - commit = project.repository.commit_by(oid: '87fdbd0f9382781442053b0b76da729344e37653') - signedcommit=Gitlab::X509::Commit.new(commit) - signature=Gitlab::X509::Signature.new(signedcommit.signature_text, signedcommit.signed_text, commit.committer_email, commit.created_at) - ``` - - If you make changes to address issues identified running through the checks, restart the - Rails console and run though the checks again from the start. - -1. Check the certificate on the commit: - - ```ruby - signature.x509_certificate.nil? - signature.x509_certificate.revoked? - ``` - - Both checks should return `false`: - - ```ruby - > signature.x509_certificate.nil? - => false - > signature.x509_certificate.revoked? - => false - ``` - - A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332503) causes - these checks to fail with `Validation failed: Subject key identifier is invalid`. - -1. Run a cryptographic check on the signature. The code must return `true`: - - ```ruby - signature.verified_signature - ``` - - If it returns `false` then [investigate this check further](#cryptographic-verification-checks). - -1. Confirm the email addresses match on the commit and the signature: - - - The Rails console displays the email addresses being compared. - - The final command must return `true`: - - ```ruby - sigemail=signature.__send__:certificate_email - commitemail=commit.committer_email - sigemail == commitemail - ``` - - A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336677) exists: - only the first email in the `Subject Alternative Name` list is compared. To - display the `Subject Alternative Name` list, run: - - ```ruby - signature.__send__ :get_certificate_extension,'subjectAltName' - ``` - - If the developer's email address is not the first one in the list, this check - fails, and the commit is marked `unverified`. - -1. The email address on the commit must be associated with an account in GitLab. - This check should return `false`: - - ```ruby - signature.user.nil? - ``` - -1. Check the email address is associated with a user in GitLab. This check should - return a user, such as `#<User id:1234 @user_handle>`: - - ```ruby - User.find_by_any_email(commit.committer_email) - ``` - - If it returns `nil`, the email address is not associated with a user, and the check fails. - -1. Confirm the developer's email address is verified. This check must return true: - - ```ruby - signature.user.verified_emails.include?(commit.committer_email) - ``` - - If the previous check returned `nil`, this command displays an error: - - ```plaintext - NoMethodError (undefined method `verified_emails' for nil:NilClass) - ``` - -1. The verification status is stored in the database. To display the database record: - - ```ruby - pp CommitSignatures::X509CommitSignature.by_commit_sha(commit.sha);nil - ``` - - If all the previous checks returned the correct values: - - - `verification_status: "unverified"` indicates the database record needs - updating. [Use the Rake task](#re-verify-commits). - - - `[]` indicates the database doesn't have a record yet. Locate the commit - in GitLab to check the signature and store the result. - -#### Cryptographic verification checks - -If GitLab determines that `verified_signature` is `false`, investigate the reason -in the Rails console. These checks require `signature` to exist. Refer to the `signature` -step of the previous [main verification checks](#main-verification-checks). - -1. Check the signature, without checking the issuer, returns `true`: - - ```ruby - signature.__send__ :valid_signature? - ``` - -1. Check the signing time and date. This check must return `true`: - - ```ruby - signature.__send__ :valid_signing_time? - ``` - - - The code allows for code signing certificates to expire. - - A commit must be signed during the validity period of the certificate, - and at or after the commit's datestamp. Display the commit time and - certificate details including `not_before`, `not_after` with: - - ```ruby - commit.created_at - pp signature.__send__ :cert; nil - ``` - -1. Check the signature, including that TLS trust can be established. This check must return `true`: - - ```ruby - signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) - ``` - - 1. If this fails, add the missing certificates required to establish trust - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). - - 1. After adding more certificates, (if these troubleshooting steps then pass) - run the Rake task to [re-verify commits](#re-verify-commits). - - 1. Display the certificates, including in the signature: - - ```ruby - pp signature.__send__(:p7).certificates ; nil - ``` - -Ensure any additional intermediate certificates and the root certificate are added -to the certificate store. For consistency with how certificate chains are built on -web servers: - -- Git clients that are signing commits should include the certificate - and all intermediate certificates in the signature. -- The GitLab certificate store should only contain the root. - -If you remove a root certificate from the GitLab -trust store, such as when it expires, commit signatures which chain back to that -root display as `unverified`. +<!-- 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 1f79982bb1f..d99729e3c1b 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -137,7 +137,7 @@ You can also sort the requirements list by: ## Allow requirements to be satisfied from a CI job > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in GitLab 13.2. +> - Ability to specify individual requirements and their statuses [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) in GitLab 13.2. GitLab supports [requirements test reports](../../../ci/yaml/artifacts_reports.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing diff --git a/doc/user/project/service_desk/configure.md b/doc/user/project/service_desk/configure.md new file mode 100644 index 00000000000..f8f4ab44e5a --- /dev/null +++ b/doc/user/project/service_desk/configure.md @@ -0,0 +1,873 @@ +--- +stage: Monitor +group: Respond +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Configure Service Desk **(FREE ALL)** + +By default, Service Desk is active in new projects. +If it's not active, you can do it in the project's settings. + +Prerequisites: + +- You must have at least the Maintainer role for the project. +- On GitLab self-managed, you must [set up incoming email](../../../administration/incoming_email.md#set-it-up) + for the GitLab instance. You should use + [email sub-addressing](../../../administration/incoming_email.md#email-sub-addressing), + but you can also use [catch-all mailboxes](../../../administration/incoming_email.md#catch-all-mailbox). + To do this, you must have administrator access. +- You must have enabled [issue](../settings/index.md#configure-project-features-and-permissions) + tracker for the project. + +To enable Service Desk in your project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Turn on the **Activate Service Desk** toggle. +1. Optional. Complete the fields. + - [Add a suffix](#configure-a-suffix-for-service-desk-alias-email) to your Service Desk email address. + - If the list below **Template to append to all Service Desk issues** is empty, create a + [description template](../description_templates.md) in your repository. +1. Select **Save changes**. + +Service Desk is now enabled for this project. +If anyone sends an email to the address available below **Email address to use for Service Desk**, +GitLab creates a confidential issue with the email's content. + +## Improve your project's security + +To improve your Service Desk project's security, you should: + +- Put the Service Desk email address behind an alias on your email system so you can change it later. +- [Enable Akismet](../../../integration/akismet.md) on your GitLab instance to add spam checking to this service. + Unblocked email spam can result in many spam issues being created. + +## Customize emails sent to the requester + +> - Moved from GitLab Premium to GitLab Free in 13.2. +> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. +> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. + +An email is sent to the requester when: + +- A requester submits a new ticket by emailing Service Desk. +- A new public comment is added on a Service Desk ticket. + - Editing a comment does not trigger a new email to be sent. + +You can customize the body of these email messages with Service Desk email templates. The templates +can include [GitLab Flavored Markdown](../../markdown.md) and [some HTML tags](../../markdown.md#inline-html). +For example, you can format the emails to include a header and footer in accordance with your +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. + +### Thank you email + +When a requester submits an issue through Service Desk, GitLab sends a **thank you email**. +Without additional configuration, GitLab sends the default thank you email. + +To create a custom thank you email template: + +1. In the `.gitlab/service_desk_templates/` directory of your repository, create a file named `thank_you.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), + [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the reply + to Service Desk requesters. + +### New note email + +When a Service Desk ticket has a new public comment, GitLab sends a **new note email**. +Without additional configuration, GitLab sends the content of the comment. + +To keep your emails on brand, you can create a custom new note email template. To do so: + +1. In the `.gitlab/service_desk_templates/` directory in your repository, create a file named `new_note.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), + [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the new note + email. Be sure to include the `%{NOTE_TEXT}` in the template to make sure the email recipient can + read the contents of the comment. + +### Instance-level email header, footer, and additional text **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. + +Instance administrators can add a header, footer or additional text to the GitLab instance and apply +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). + +## Use a custom template for Service Desk tickets + +You can select one [description template](../description_templates.md#create-an-issue-template) +**per project** to be appended to every new Service Desk ticket's description. + +You can set description templates at various levels: + +- The entire [instance](../description_templates.md#set-instance-level-description-templates). +- A specific [group or subgroup](../description_templates.md#set-group-level-description-templates). +- A specific [project](../description_templates.md#set-a-default-template-for-merge-requests-and-issues). + +The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. + +Prerequisite: + +- You must have [created a description template](../description_templates.md#create-an-issue-template). + +To use a custom description template with Service Desk: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. + +## Support Bot user + +Behind the scenes, Service Desk works by the special Support Bot user creating issues. +This user isn't a [billable user](../../../subscriptions/self_managed/index.md#billable-users), +so it does not count toward the license limit count. + +In GitLab 16.0 and earlier, comments generated from Service Desk emails show `GitLab Support Bot` +as the author. In [GitLab 16.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/226995), +these comments show the email of the user who sent the email. +This feature only applies to comments made in GitLab 16.1 and later. + +### Change the Support Bot's display name + +You can change the display name of the Support Bot user. Emails sent from Service Desk have +this name in the `From` header. The default display name is `GitLab Support Bot`. + +To edit the custom email display name: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email display name**, enter a new name. +1. Select **Save changes**. + +## Custom email address **(BETA)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329990) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `service_desk_custom_email`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) 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 `service_desk_custom_email`. On GitLab.com, this feature is available. + +Configure a custom email address to show as the sender of your support communication. +Maintain brand identity and instill confidence among support requesters with a domain they recognize. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [a short showcase video](https://youtu.be/_moD5U3xcQs). + +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). +A Beta feature is not production-ready, but is unlikely to change drastically +before it's released. We encourage users to try Beta features and provide feedback +in [the feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/416637). + +### Prerequisites + +You can use one custom email address for Service Desk per project and it must be unique across the instance. + +The custom email address you want to use must meet all of the following requirements: + +- You can set up email forwarding. +- Forwarded emails preserve the original `From` header. +- Your service provider must support sub-addressing. An email address consists of a local part (everything before `@`) and a + domain part. + + With email sub-addressing you can create unique variations of an email address by adding a `+` symbol followed + by any text to the local part. Given the email address `support@example.com`, check whether sub-addressing is supported by + sending an email to `support+1@example.com`. This email should appear in your mailbox. +- You have SMTP credentials (ideally, you should use an app password). +- You must have at least the Maintainer role for the project. +- Service Desk must be configured for the project. + +### Configure a custom email address + +Configure and verify a custom email address when you want to send Service Desk emails using your own email address. + +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. 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. **SMTP host** must be resolvable from the network of your GitLab instance (on GitLab self-managed) + or the public internet (on GitLab SaaS). +1. Select **Save & test settings**. + +The configuration has been saved and the verification of the custom email address is triggered. + +#### Verification + +1. After completing the configuration, all project owners and the administrator that saved the custom email configuration receive a notification email. +1. A verification email is sent using the provided SMTP credentials to the custom email address (with a sub-addressing part). + The email contains a verification token. When email forwarding is set up correctly and all prerequisites are met, + the email is forwarded to your Service Desk address and ingested by GitLab. GitLab checks the following conditions: + 1. GitLab can send an email using the SMTP credentials. + 1. Sub-addressing is supported (with the `+verify` sub-addressing part). + 1. `From` header is preserved after forwarding. + 1. Verification token is correct. + 1. Email is received in 30 minutes. + +Typically the process takes only a few minutes. + +To cancel verification at any time or if it fails, select **Reset custom email**. +The settings page updates accordingly and reflects the current state of the verification. +The SMTP credentials are deleted and you can start the configuration again. + +On failure and success all project owners and the user who triggered the verification process receive a +notification email with the verification result. +If the verification failed, the email also contains details of the reason. + +If the verification was successful, the custom email address is ready to be used. +You can now enable sending Service Desk emails via the custom email address. + +### Enable or disable the custom email address + +After the custom email address has been verified, administrators can enable or disable sending Service Desk emails via the custom email address. + +To **enable** the custom email address: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Turn on the **Enable custom email** toggle. + Service Desk emails to external participants are sent using the SMTP credentials. + +To **disable** the custom email address: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Turn off the **Enable custom email** toggle. + Because you set up email forwarding, emails to your custom email address continue to be processed and + appear as Service Desk Tickets in your project. + + Service Desk emails to external participants are now sent using the GitLab instance's default outgoing + email configuration. + +### Change or remove custom email configuration + +To change the custom email configuration you must reset and remove it and configure custom email again. + +To reset the configuration at any step in the process, select **Reset custom email**. +The credentials are then removed from the database. + +### Custom email reply address + +External participants can [reply by email](../../../administration/reply_by_email.md) to Service Desk tickets. +GitLab uses an email reply address with a 32-character reply key that corresponds to the ticket. +When a custom email is configured, GitLab generates the reply address from that email. + +### Known issues + +- Some service providers don't allow SMTP connections any more. + Often you can enable them on a per user basis and create an app password. +- Microsoft Exchange doesn't preserve the `From` header, so you cannot use a custom email from the same tenant. + As a workaround: + - On GitLab SaaS, use a transport rule to forward emails from the custom email address to the Service Desk email + from GitLab SaaS. Forwarding to an email address outside the current tenant preserves the original `From` header. + - On GitLab self-managed, use a subdomain or a different domain from another service provider for the + custom email address or the GitLab instance `incoming_email` or `service_desk_email`. + +## Use an additional Service Desk alias email **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. + +You can use an additional alias email address for Service Desk on an instance level. + +To do this, you must configure +a [`service_desk_email`](#configure-service-desk-alias-email) in the instance configuration. You can also configure a +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) that replaces the default `-issue-` portion on the sub-addressing part. + +### Configure Service Desk alias email + +NOTE: +On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. + +Service Desk uses the [incoming email](../../../administration/incoming_email.md) +configuration by default. However, to have a separate email address for Service Desk, +configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email) +in project settings. + +Prerequisites: + +- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, + before the `@`. The placeholder is used to identify the project where the issue should be created. +- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes + to make sure Service Desk emails are processed correctly. + +To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +NOTE: +In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. +To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file. +For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). +In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no +secret file configuration setting is needed. +For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). + +```ruby +gitlab_rails['service_desk_email_enabled'] = true +gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" +gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" +gitlab_rails['service_desk_email_password'] = "[REDACTED]" +gitlab_rails['service_desk_email_mailbox_name'] = "inbox" +gitlab_rails['service_desk_email_idle_timeout'] = 60 +gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" +gitlab_rails['service_desk_email_host'] = "imap.gmail.com" +gitlab_rails['service_desk_email_port'] = 993 +gitlab_rails['service_desk_email_ssl'] = true +gitlab_rails['service_desk_email_start_tls'] = false +``` + +:::TabTitle Self-compiled (source) + +```yaml +service_desk_email: + enabled: true + address: "project_contact+%{key}@example.com" + user: "project_contact@example.com" + password: "[REDACTED]" + host: "imap.gmail.com" + delivery_method: webhook + secret_file: .gitlab-mailroom-secret + port: 993 + ssl: true + start_tls: false + log_path: "log/mailroom.log" + mailbox: "inbox" + idle_timeout: 60 + expunge_deleted: true +``` + +::EndTabs + +The configuration options are the same as for configuring +[incoming email](../../../administration/incoming_email.md#set-it-up). + +#### Use encrypted credentials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the incoming email credentials. + +Prerequisites: + +- To use encrypted credentials, you must first enable the + [encrypted configuration](../../../administration/encrypted_configuration.md). + +The supported configuration items for the encrypted file are: + +- `user` +- `password` + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: + + ```ruby + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the Service Desk email secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +1. If initially your Service Desk configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: + + ```yaml + production: + service_desk_email: + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. +1. Save the file and restart GitLab and Mailroom + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +#### Microsoft Graph + +> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. +> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11. + +`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft +Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph +[the same way as for incoming email](../../../administration/incoming_email.md#microsoft-graph). + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting + the values you want: + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```ruby + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails): + + ```shell + kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET> + ``` + +1. Create the [Kubernetes Secret for the GitLab Service Desk email auth token](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-service-desk-email-auth-token). + Replace `<name>` with the name of the [Helm release name](https://helm.sh/docs/intro/using_helm/) for the GitLab installation: + + ```shell + kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64) + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + serviceDeskEmail: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: inbox + inboxMethod: microsoft_graph + azureAdEndpoint: https://login.microsoftonline.com + graphEndpoint: https://graph.microsoft.com + tenantId: "YOUR-TENANT-ID" + clientId: "YOUR-CLIENT-ID" + clientSecret: + secret: service-desk-email-client-secret + key: secret + deliveryMethod: webhook + authToken: + secret: <name>-service-desk-email-auth-token + key: authToken + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are case-sensitive: + + ```yaml + global: + appConfig: + serviceDeskEmail: + [..] + azureAdEndpoint: https://login.microsoftonline.us + graphEndpoint: https://graph.microsoft.us + [..] + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azure_ad_endpoint` and `graph_endpoint` settings: + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + azure_ad_endpoint: "https://login.microsoftonline.us" + graph_endpoint: "https://graph.microsoft.us" + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + +::EndTabs + +### Configure a suffix for Service Desk alias email + +You can set a custom suffix in your project's Service Desk settings. + +A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). + +When configured, the custom suffix creates a new Service Desk email address, consisting of the +`service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` + +Prerequisites: + +- You must have configured a [Service Desk alias email](#configure-service-desk-alias-email). + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email address suffix**, enter the suffix to use. +1. Select **Save changes**. + +For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: + +- Email address suffix is set to `support`. +- Service Desk email address is configured to `contact+%{key}@example.com`. + +The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. +The [incoming email](../../../administration/incoming_email.md) address still works. + +If you don't configure a custom suffix, the default project identification is used for identifying +the project. + +## Configure email ingestion in multi-node environments + +A multi-node environment is a setup where GitLab is run across multiple servers +for scalability, fault tolerance, and performance reasons. + +GitLab uses a separate process called `mail_room` to ingest new unread emails +from the `incoming_email` and `service_desk_email` mailboxes. + +### Helm chart (Kubernetes) + +The [GitLab Helm chart](https://docs.gitlab.com/charts/) is made up of multiple subcharts, and one of them is +the [Mailroom subchart](https://docs.gitlab.com/charts/charts/gitlab/mailroom/index.html). Configure the +[common settings for `incoming_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) +and the [common settings for `service_desk_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#service-desk-email-configuration). + +### Linux package (Omnibus) + +In multi-node Linux package installation environments, run `mail_room` only on one node. Run it either on a single +`rails` node (for example, `application_role`) +or completely separately. + +#### Set up all nodes + +1. Add basic configuration for `incoming_email` and `service_desk_email` on every node + to render email addresses in the web UI and in generated emails. + + Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`: + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_enabled'] = true + gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com" + ``` + + ::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: + 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 + token across all application nodes. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + + gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + ::EndTabs + + 1. [Deprecated in GitLab 16.0 and planned for removal in 17.0)](../../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated): + If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['incoming_email_delivery_method'] = "sidekiq" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['service_desk_email_delivery_method'] = "sidekiq" + ``` + + ::EndTabs + +1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = false + ``` + +1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) for the changes to take effect. + +#### Set up a single email ingestion node + +After setting up all nodes and disabling the `mail_room` process, enable `mail_room` on a single node. +This node polls the mailboxes for `incoming_email` and `service_desk_email` on a regular basis and +move new unread emails to GitLab. + +1. Choose an existing node that additionally handles email ingestion. +1. Add [full configuration and credentials](../../../administration/incoming_email.md#configuration-examples) + for `incoming_email` and `service_desk_email`. +1. Enable `mail_room` on this node. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = true + ``` + +1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) on this node for the changes to take effect. diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md index 208e798bd21..ab807553436 100644 --- a/doc/user/project/service_desk/index.md +++ b/doc/user/project/service_desk/index.md @@ -39,870 +39,21 @@ Meanwhile: - Your team saves time by not having to leave GitLab (or set up integrations) to follow up with your customer. -## Configure Service Desk - -By default, Service Desk is active in new projects. -If it's not active, you can do it in the project's settings. - -Prerequisites: - -- You must have at least the Maintainer role for the project. -- On GitLab self-managed, you must [set up incoming email](../../../administration/incoming_email.md#set-it-up) - for the GitLab instance. You should use - [email sub-addressing](../../../administration/incoming_email.md#email-sub-addressing), - but you can also use [catch-all mailboxes](../../../administration/incoming_email.md#catch-all-mailbox). - To do this, you must have administrator access. -- You must have enabled [issue](../settings/index.md#configure-project-visibility-features-and-permissions) - tracker for the project. - -To enable Service Desk in your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Turn on the **Activate Service Desk** toggle. -1. Optional. Complete the fields. - - [Add a suffix](#configure-a-suffix-for-service-desk-alias-email) to your Service Desk email address. - - If the list below **Template to append to all Service Desk issues** is empty, create a - [description template](../description_templates.md) in your repository. -1. Select **Save changes**. - -Service Desk is now enabled for this project. -If anyone sends an email to the address available below **Email address to use for Service Desk**, -GitLab creates a confidential issue with the email's content. - -### Improve your project's security - -To improve your Service Desk project's security, you should: - -- Put the Service Desk email address behind an alias on your email system so you can change it later. -- [Enable Akismet](../../../integration/akismet.md) on your GitLab instance to add spam checking to this service. - Unblocked email spam can result in many spam issues being created. - -### Customize emails sent to the requester - -> - Moved from GitLab Premium to GitLab Free in 13.2. -> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. -> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. -> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. - -An email is sent to the requester when: - -- A requester submits a new ticket by emailing Service Desk. -- A new public comment is added on a Service Desk ticket. - - Editing a comment does not trigger a new email to be sent. - -You can customize the body of these email messages with Service Desk email templates. The templates -can include [GitLab Flavored Markdown](../../markdown.md) and [some HTML tags](../../markdown.md#inline-html). -For example, you can format the emails to include a header and footer in accordance with your -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. - -#### Thank you email - -When a requester submits an issue through Service Desk, GitLab sends a **thank you email**. -Without additional configuration, GitLab sends the default thank you email. - -To create a custom thank you email template: - -1. In the `.gitlab/service_desk_templates/` directory of your repository, create a file named `thank_you.md`. -1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), - [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the reply - to Service Desk requesters. - -#### New note email - -When a Service Desk ticket has a new public comment, GitLab sends a **new note email**. -Without additional configuration, GitLab sends the content of the comment. - -To keep your emails on brand, you can create a custom new note email template. To do so: - -1. In the `.gitlab/service_desk_templates/` directory in your repository, create a file named `new_note.md`. -1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), - [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the new note - email. Be sure to include the `%{NOTE_TEXT}` in the template to make sure the email recipient can - read the contents of the comment. - -#### Instance-level email header, footer, and additional text **(FREE SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. - -Instance administrators can add a header, footer or additional text to the GitLab instance and apply -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). - -### Use a custom template for Service Desk tickets - -You can select one [description template](../description_templates.md#create-an-issue-template) -**per project** to be appended to every new Service Desk ticket's description. - -You can set description templates at various levels: - -- The entire [instance](../description_templates.md#set-instance-level-description-templates). -- A specific [group or subgroup](../description_templates.md#set-group-level-description-templates). -- A specific [project](../description_templates.md#set-a-default-template-for-merge-requests-and-issues). - -The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. - -Prerequisite: - -- You must have [created a description template](../description_templates.md#create-an-issue-template). - -To use a custom description template with Service Desk: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. - -### Support Bot user - -Behind the scenes, Service Desk works by the special Support Bot user creating issues. -This user isn't a [billable user](../../../subscriptions/self_managed/index.md#billable-users), -so it does not count toward the license limit count. - -In GitLab 16.0 and earlier, comments generated from Service Desk emails show `GitLab Support Bot` -as the author. In [GitLab 16.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/226995), -these comments show the email of the user who sent the email. -This feature only applies to comments made in GitLab 16.1 and later. - -#### Change the Support Bot's display name - -You can change the display name of the Support Bot user. Emails sent from Service Desk have -this name in the `From` header. The default display name is `GitLab Support Bot`. - -To edit the custom email display name: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Below **Email display name**, enter a new name. -1. Select **Save changes**. - -### Use an additional Service Desk alias email **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. - -You can use an additional alias email address for Service Desk on an instance level. - -To do this, you must configure -a [`service_desk_email`](#configure-service-desk-alias-email) in the instance configuration. You can also configure a -[custom suffix](#configure-a-suffix-for-service-desk-alias-email) that replaces the default `-issue-` portion on the sub-addressing part. - -#### Configure Service Desk alias email - -NOTE: -On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the -[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. - -Service Desk uses the [incoming email](../../../administration/incoming_email.md) -configuration by default. However, to have a separate email address for Service Desk, -configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email) -in project settings. - -Prerequisites: - -- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, - before the `@`. The placeholder is used to identify the project where the issue should be created. -- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes - to make sure Service Desk emails are processed correctly. - -To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -NOTE: -In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. -To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file. -For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). -In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no -secret file configuration setting is needed. -For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). - -```ruby -gitlab_rails['service_desk_email_enabled'] = true -gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" -gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" -gitlab_rails['service_desk_email_password'] = "[REDACTED]" -gitlab_rails['service_desk_email_mailbox_name'] = "inbox" -gitlab_rails['service_desk_email_idle_timeout'] = 60 -gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" -gitlab_rails['service_desk_email_host'] = "imap.gmail.com" -gitlab_rails['service_desk_email_port'] = 993 -gitlab_rails['service_desk_email_ssl'] = true -gitlab_rails['service_desk_email_start_tls'] = false -``` - -:::TabTitle Self-compiled (source) - -```yaml -service_desk_email: - enabled: true - address: "project_contact+%{key}@example.com" - user: "project_contact@example.com" - password: "[REDACTED]" - host: "imap.gmail.com" - delivery_method: webhook - secret_file: .gitlab-mailroom-secret - port: 993 - ssl: true - start_tls: false - log_path: "log/mailroom.log" - mailbox: "inbox" - idle_timeout: 60 - expunge_deleted: true -``` - -::EndTabs - -The configuration options are the same as for configuring -[incoming email](../../../administration/incoming_email.md#set-it-up). - -##### Use encrypted credentials - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. - -Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally -use an encrypted file for the incoming email credentials. - -Prerequisites: - -- To use encrypted credentials, you must first enable the - [encrypted configuration](../../../administration/encrypted_configuration.md). - -The supported configuration items for the encrypted file are: - -- `user` -- `password` - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: - - ```ruby - gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" - gitlab_rails['service_desk_email_password'] = "examplepassword" - ``` - -1. Edit the encrypted secret: - - ```shell - sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim - ``` - -1. Enter the unencrypted contents of the Service Desk email secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. -1. Save the file and reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -:::TabTitle Helm chart (Kubernetes) - -Use a Kubernetes secret to store the Service Desk email password. For more information, -read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). - -:::TabTitle Docker - -1. If initially your Service Desk configuration in `docker-compose.yml` looked like: - - ```yaml - version: "3.6" - services: - gitlab: - image: 'gitlab/gitlab-ee:latest' - restart: always - hostname: 'gitlab.example.com' - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" - gitlab_rails['service_desk_email_password'] = "examplepassword" - ``` - -1. Get inside the container, and edit the encrypted secret: - - ```shell - sudo docker exec -t <container_name> bash - gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor - ``` - -1. Enter the unencrypted contents of the Service Desk secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -:::TabTitle Self-compiled (source) - -1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: - - ```yaml - production: - service_desk_email: - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit the encrypted secret: - - ```shell - bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production - ``` - -1. Enter the unencrypted contents of the Service Desk secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. -1. Save the file and restart GitLab and Mailroom - - ```shell - # For systems running systemd - sudo systemctl restart gitlab.target - - # For systems running SysV init - sudo service gitlab restart - ``` - -::EndTabs - -##### Microsoft Graph - -> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. -> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11. - -`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph -[the same way as for incoming email](../../../administration/incoming_email.md#microsoft-graph). - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting - the values you want: - - ```ruby - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), - configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: - - ```ruby - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -:::TabTitle Helm chart (Kubernetes) - -1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails): - - ```shell - kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET> - ``` - -1. Create the [Kubernetes Secret for the GitLab Service Desk email auth token](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-service-desk-email-auth-token). - Replace `<name>` with the name of the [Helm release name](https://helm.sh/docs/intro/using_helm/) for the GitLab installation: - - ```shell - kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64) - ``` - -1. Export the Helm values: - - ```shell - helm get values gitlab > gitlab_values.yaml - ``` - -1. Edit `gitlab_values.yaml`: - - ```yaml - global: - appConfig: - serviceDeskEmail: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: inbox - inboxMethod: microsoft_graph - azureAdEndpoint: https://login.microsoftonline.com - graphEndpoint: https://graph.microsoft.com - tenantId: "YOUR-TENANT-ID" - clientId: "YOUR-CLIENT-ID" - clientSecret: - secret: service-desk-email-client-secret - key: secret - deliveryMethod: webhook - authToken: - secret: <name>-service-desk-email-auth-token - key: authToken - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), -configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are case-sensitive: - - ```yaml - global: - appConfig: - serviceDeskEmail: - [..] - azureAdEndpoint: https://login.microsoftonline.us - graphEndpoint: https://graph.microsoft.us - [..] - ``` - -1. Save the file and apply the new values: - - ```shell - helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab - ``` - -:::TabTitle Docker - -1. Edit `docker-compose.yml`: - - ```yaml - version: "3.6" - services: - gitlab: - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), -configure the `azure_ad_endpoint` and `graph_endpoint` settings: - -1. Edit `docker-compose.yml`: - - ```yaml - version: "3.6" - services: - gitlab: - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -:::TabTitle Self-compiled (source) - -1. Edit `/home/git/gitlab/config/gitlab.yml`: - - ```yaml - service_desk_email: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: "inbox" - delivery_method: webhook - log_path: "log/mailroom.log" - secret_file: .gitlab-mailroom-secret - inbox_method: "microsoft_graph" - inbox_options: - tenant_id: "<YOUR-TENANT-ID>" - client_id: "<YOUR-CLIENT-ID>" - client_secret: "<YOUR-CLIENT-SECRET>" - poll_interval: 60 # Optional - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), - configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: - - ```yaml - service_desk_email: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: "inbox" - delivery_method: webhook - log_path: "log/mailroom.log" - secret_file: .gitlab-mailroom-secret - inbox_method: "microsoft_graph" - inbox_options: - azure_ad_endpoint: "https://login.microsoftonline.us" - graph_endpoint: "https://graph.microsoft.us" - tenant_id: "<YOUR-TENANT-ID>" - client_id: "<YOUR-CLIENT-ID>" - client_secret: "<YOUR-CLIENT-SECRET>" - poll_interval: 60 # Optional - ``` - -::EndTabs - -#### Configure a suffix for Service Desk alias email - -You can set a custom suffix in your project's Service Desk settings. - -A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). - -When configured, the custom suffix creates a new Service Desk email address, consisting of the -`service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` - -Prerequisites: - -- You must have configured a [Service Desk alias email](#configure-service-desk-alias-email). - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Below **Email address suffix**, enter the suffix to use. -1. Select **Save changes**. - -For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: - -- Email address suffix is set to `support`. -- Service Desk email address is configured to `contact+%{key}@example.com`. - -The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. -The [incoming email](../../../administration/incoming_email.md) address still works. - -If you don't configure a custom suffix, the default project identification is used for identifying -the project. - -### Configure email ingestion in multi-node environments - -A multi-node environment is a setup where GitLab is run across multiple servers -for scalability, fault tolerance, and performance reasons. - -GitLab uses a separate process called `mail_room` to ingest new unread emails -from the `incoming_email` and `service_desk_email` mailboxes. - -#### Helm chart (Kubernetes) - -The [GitLab Helm chart](https://docs.gitlab.com/charts/) is made up of multiple subcharts, and one of them is -the [Mailroom subchart](https://docs.gitlab.com/charts/charts/gitlab/mailroom/index.html). Configure the -[common settings for `incoming_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) -and the [common settings for `service_desk_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#service-desk-email-configuration). - -#### Linux package (Omnibus) - -In multi-node Linux package installation environments, run `mail_room` only on one node. Run it either on a single -`rails` node (for example, `application_role`) -or completely separately. - -##### Set up all nodes - -1. Add basic configuration for `incoming_email` and `service_desk_email` on every node - to render email addresses in the web UI and in generated emails. - - Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`: - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - gitlab_rails['incoming_email_enabled'] = true - gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com" - ``` - - ::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: - 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 - token across all application nodes. - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - gitlab_rails['incoming_email_delivery_method'] = "webhook" - - # The URL that mail_room can contact. You can also use an internal URL or IP, - # just make sure mail_room can access the GitLab API via that address. - # Do not end with "/". - gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com" - - # The shared secret file that should contain a random token. Make sure it's the same on every node. - gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - gitlab_rails['service_desk_email_delivery_method'] = "webhook" - - # The URL that mail_room can contact. You can also use an internal URL or IP, - # just make sure mail_room can access the GitLab API via that address. - # Do not end with "/". - - gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com" - - # The shared secret file that should contain a random token. Make sure it's the same on every node. - gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret" - ``` - - ::EndTabs - - 1. [Deprecated in GitLab 16.0 and planned for removal in 17.0)](../../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated): - If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis. - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - # It uses the Redis configuration to directly add Sidekiq jobs - gitlab_rails['incoming_email_delivery_method'] = "sidekiq" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - # It uses the Redis configuration to directly add Sidekiq jobs - gitlab_rails['service_desk_email_delivery_method'] = "sidekiq" - ``` - - ::EndTabs - -1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`: - - ```ruby - mailroom['enabled'] = false - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) for the changes to take effect. - -##### Set up a single email ingestion node - -After setting up all nodes and disabling the `mail_room` process, enable `mail_room` on a single node. -This node polls the mailboxes for `incoming_email` and `service_desk_email` on a regular basis and -move new unread emails to GitLab. - -1. Choose an existing node that additionally handles email ingestion. -1. Add [full configuration and credentials](../../../administration/incoming_email.md#configuration-examples) - for `incoming_email` and `service_desk_email`. -1. Enable `mail_room` on this node. For example, in `/etc/gitlab/gitlab.rb`: - - ```ruby - mailroom['enabled'] = true - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) on this node for the changes to take effect. - -## Use Service Desk - -You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). -In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). - -### View Service Desk email address - -To check what the Service Desk email address is for your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Monitor > Service Desk**. - -The email address is available at the top of the issue list. - -### As an end user (issue creator) - -> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. - -To create a Service Desk issue, an end user does not need to know anything about -the GitLab instance. They just send an email to the address they are given, and -receive an email back confirming receipt: - - - -This also gives the end user an option to unsubscribe. - -If they don't choose to unsubscribe, then any new comments added to the issue -are sent as emails: - - - -Any responses they send via email are displayed in the issue itself. - -For information about headers used for treating email, see -[the incoming email documentation](../../../administration/incoming_email.md#accepted-headers). - -### As a responder to the issue - -For responders to the issue, everything works just like other GitLab issues. -GitLab displays a familiar-looking issue tracker where responders can see -issues created through customer support requests, and filter or interact with them. - - - -Messages from the end user are shown as coming from the special -[Support Bot user](../../../subscriptions/self_managed/index.md#billable-users). -You can read and write comments as you usually do in GitLab: - - - -- The project's visibility (private, internal, public) does not affect Service Desk. -- The path to the project, including its group or namespace, is shown in emails. - -#### View Service Desk issues - -Prerequisites: - -- You must have at least the Reporter role for the project. - -To view Service Desk issues: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Monitor > Service Desk**. - -### Email contents and formatting - -#### Special HTML formatting in HTML emails - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. - -HTML emails show HTML formatting, such as: - -- Tables -- Blockquotes -- Images -- Collapsible sections - -#### Files attached to comments - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. - -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 `service_desk_new_note_email_native_attachments`. -On GitLab.com, this feature is available. - -If a comment contains any attachments and their total size is less than or equal to 10 MB, these -attachments are sent as part of the email. In other cases, the email contains links to the attachments. - -In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. - -## Privacy considerations - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. - -Service Desk issues are [confidential](../issues/confidential_issues.md), so they are -only visible to project members. The project owner can -[make an issue public](../issues/confidential_issues.md#in-an-existing-issue). -When a Service Desk issue becomes public, the issue creator's and participants' email addresses are -visible to signed-in users with at least the Reporter role for the project. - -In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email -address is disclosed to everyone who can view the project. - -Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless -of their role** in the project. - -The unique internal email address is visible to project members at least -the Reporter role in your GitLab instance. -An external user (issue creator) cannot see the internal email address -displayed in the information note. - -### Moving a Service Desk issue - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. - -You can move a Service Desk issue the same way you -[move a regular issue](../issues/managing_issues.md#move-an-issue) in GitLab. - -If a Service Desk issue is moved to a different project with Service Desk enabled, -the customer who created the issue continues to receive email notifications. -Because a moved issue is first closed, then copied, the customer is considered to be a participant -in both issues. They continue to receive any notifications in the old issue and the new one. +## Related topics + +- [Configure Service Desk](configure.md) + - [Improve your project's security](configure.md#improve-your-projects-security) + - [Customize emails sent to the requester](configure.md#customize-emails-sent-to-the-requester) + - [Use a custom template for Service Desk tickets](configure.md#use-a-custom-template-for-service-desk-tickets) + - [Support Bot user](configure.md#support-bot-user) + - [Custom email address (Beta)](configure.md#custom-email-address) + - [Use an additional Service Desk alias email](configure.md#use-an-additional-service-desk-alias-email) + - [Configure email ingestion in multi-node environments](configure.md#configure-email-ingestion-in-multi-node-environments) +- [Use Service Desk](using_service_desk.md#use-service-desk) + - [As an end user (issue creator)](using_service_desk.md#as-an-end-user-issue-creator) + - [As a responder to the issue](using_service_desk.md#as-a-responder-to-the-issue) + - [Email contents and formatting](using_service_desk.md#email-contents-and-formatting) + - [Privacy considerations](using_service_desk.md#privacy-considerations) ## Troubleshooting Service Desk diff --git a/doc/user/project/service_desk/using_service_desk.md b/doc/user/project/service_desk/using_service_desk.md new file mode 100644 index 00000000000..73d85d418d9 --- /dev/null +++ b/doc/user/project/service_desk/using_service_desk.md @@ -0,0 +1,182 @@ +--- +stage: Monitor +group: Respond +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Use Service Desk **(FREE ALL)** + +You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). +In these issues, you can also see our friendly neighborhood [Support Bot](configure.md#support-bot-user). + +## View Service Desk email address + +To check what the Service Desk email address is for your project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. + +The email address is available at the top of the issue list. + +## As an end user (issue creator) + +> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. + +To create a Service Desk issue, an end user does not need to know anything about +the GitLab instance. They just send an email to the address they are given, and +receive an email back confirming receipt: + + + +This also gives the end user an option to unsubscribe. + +If they don't choose to unsubscribe, then any new comments added to the issue +are sent as emails: + + + +Any responses they send via email are displayed in the issue itself. + +For information about headers used for treating email, see +[the incoming email documentation](../../../administration/incoming_email.md#accepted-headers). + +## As a responder to the issue + +For responders to the issue, everything works just like other GitLab issues. +GitLab displays a familiar-looking issue tracker where responders can see +issues created through customer support requests, and filter or interact with them. + + + +Messages from the end user are shown as coming from the special +[Support Bot user](../../../subscriptions/self_managed/index.md#billable-users). +You can read and write comments as you usually do in GitLab: + + + +- The project's visibility (private, internal, public) does not affect Service Desk. +- The path to the project, including its group or namespace, is shown in emails. + +### View Service Desk issues + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To view Service Desk issues: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. + +#### Redesigned issue list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413092) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `service_desk_vue_list`. Disabled by default. + +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 `service_desk_vue_list`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +When this feature is enabled, the Service Desk issue list more closely matches the regular issue list. +Available features include: + +- The same sorting and ordering options [as on the issue list](../issues/sorting_issue_lists.md). +- The same filters, including [the OR operator](#filter-with-the-or-operator) and [filtering by issue ID](#filter-issues-by-id). + +There is no longer an option to create a new issue from the Service Desk issue list. +This decision better reflects the nature of Service Desk, where new issues are created by emailing +a dedicated email address. + +##### Filter the list of issues + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. +1. Above the list of issues, select **Search or filter results...**. +1. In the dropdown list that appears, select the attribute you want to filter by. +1. Select or type the operator to use for filtering the attribute. The following operators are + available: + - `=`: Is + - `!=`: Is not one of +1. Enter the text to filter the attribute by. + You can filter some attributes by **None** or **Any**. +1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical + `AND`. + +##### Filter with the OR operator + +When [filtering with the OR operator](../issues/managing_issues.md#filter-with-the-or-operator) is enabled, +you can use **is one of: `||`** +when you [filter the list of issues](#filter-the-list-of-issues) by: + +- Assignees +- Labels + +`is one of` represents an inclusive OR. For example, if you filter by `Assignee is one of Sidney Jones` and +`Assignee is one of Zhang Wei`, GitLab shows issues where either `Sidney`, `Zhang`, or both of them are assignees. + +##### Filter issues by ID + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. +1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. + +## Email contents and formatting + +### Special HTML formatting in HTML emails + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. + +HTML emails show HTML formatting, such as: + +- Tables +- Blockquotes +- Images +- Collapsible sections + +### Files attached to comments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. + +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 `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is available. + +If a comment contains any attachments and their total size is less than or equal to 10 MB, these +attachments are sent as part of the email. In other cases, the email contains links to the attachments. + +In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. + +## Privacy considerations + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. + +Service Desk issues are [confidential](../issues/confidential_issues.md), so they are +only visible to project members. The project owner can +[make an issue public](../issues/confidential_issues.md#in-an-existing-issue). +When a Service Desk issue becomes public, the issue creator's and participants' email addresses are +visible to signed-in users with at least the Reporter role for the project. + +In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email +address is disclosed to everyone who can view the project. + +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their role** in the project. + +The unique internal email address is visible to project members at least +the Reporter role in your GitLab instance. +An external user (issue creator) cannot see the internal email address +displayed in the information note. + +### Moving a Service Desk issue + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. + +You can move a Service Desk issue the same way you +[move a regular issue](../issues/managing_issues.md#move-an-issue) in GitLab. + +If a Service Desk issue is moved to a different project with Service Desk enabled, +the customer who created the issue continues to receive email notifications. +Because a moved issue is first closed, then copied, the customer is considered to be a participant +in both issues. They continue to receive any notifications in the old issue and the new one. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 087330431ad..22eb7c54d12 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -79,14 +79,14 @@ For example: Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: -1. [Enable file exports](../../../administration/settings/visibility_and_access_controls.md#enable-project-export) on the source +1. [Enable file exports](../../../administration/settings/import_and_export_settings.md#enable-project-export) on the source instance. 1. Enable file exports as an import source for the destination instance. On GitLab.com, file exports are already enabled as an import source. To enable file exports as an import source for the destination instance: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. @@ -113,7 +113,7 @@ Prerequisites: To export a project and its data, follow these steps: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Export project**. @@ -245,7 +245,7 @@ If you have a larger project, consider [using a Rake task](../../../administrati Administrators can set the maximum import file size one of two ways: - With the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings). -- In the [Admin Area UI](../../../administration/settings/account_and_limit_settings.md#max-import-size). +- In the [Admin Area UI](../../../administration/settings/import_and_export_settings.md#max-import-size). The default is `0` (unlimited). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 6c2140595d9..d9c114c0a59 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -11,9 +11,11 @@ Use the **Settings** page to manage the configuration options in your [project]( ## View project settings -You must have at least the Maintainer role to view project settings. +Prerequisite: + +- You must have at least the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. To display all settings in a section, select **Expand**. 1. Optional. Use the search box to find a setting. @@ -22,8 +24,11 @@ You must have at least the Maintainer role to view project settings. Use the project general settings to edit your project details. -1. Sign in to GitLab with at least the Maintainer role. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +Prerequisite: + +- You must have at least the Maintainer role for the project. + +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. 1. In the **Project description** text box, enter your project description. @@ -31,11 +36,11 @@ Use the project general settings to edit your project details. ## Assign topics to a project -Use topics to categorize projects and find similar new projects. +Use [topics](../working_with_projects.md#organizing-projects-with-topics) to categorize projects and find similar new projects. To assign topics to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings** > **General**. 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. @@ -46,50 +51,38 @@ If you're an instance administrator, you can administer all project topics from NOTE: The assigned topics are visible only to users with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. -## Add a compliance framework to a project **(PREMIUM ALL)** +## Rename a repository + +A project's repository name defines its URL and its place on the file disk +where GitLab is installed. + +Prerequisite: -You can -[add compliance frameworks to projects](../../group/compliance_frameworks.md#add-a-compliance-framework-to-a-project) -in a group that has a compliance framework. +- You must be an administrator or have the Maintainer or Owner role for the project. + +NOTE: +When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see +[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). + +To rename a repository: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Change path** text box, edit the path. +1. Select **Change path**. -## Configure project visibility, features, and permissions +## Configure project features and permissions -To configure visibility, features, and permissions for a project: +To configure features and permissions for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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 change the project visibility, select the dropdown list. If you select to **Public**, you limit access to some features to **Only Project Members**. 1. To allow users to request access to the project, select the **Users can request access** checkbox. -1. Use the [toggles](#project-feature-settings) to enable or disable features in the project. +1. To enable or disable features in the project, use the feature toggles. 1. Select **Save changes**. -### Project feature settings - -Use the toggles to enable or disable features in the project. - -| Option | More access limit options | Description -| :------------------------------- | :------------------------ | :---------- | -| **Issues** | **{check-circle}** Yes | Activates the GitLab issues tracker. -| **Repository** | **{check-circle}** Yes | Enables [repository](../repository/index.md) functionality. -| **Merge requests** | **{check-circle}** Yes | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). -| **Forks** | **{check-circle}** Yes | Enables [forking](../repository/forking_workflow.md) functionality. -| **Git Large File Storage (LFS)** | **{dotted-circle}** No | Enables the use of [large files](../../../topics/git/lfs/index.md). -| **Packages** | **{dotted-circle}** No | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. -| **CI/CD** | **{check-circle}** Yes | Enables [CI/CD](../../../ci/index.md) functionality. -| **Container Registry** | **{dotted-circle}** No | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. -| **Analytics** | **{check-circle}** Yes | Enables [analytics](../../analytics/index.md). -| **Requirements** | **{check-circle}** Yes | Control access to [Requirements Management](../requirements/index.md). -| **Security and Compliance** | **{check-circle}** Yes | Control access to [security features](../../application_security/index.md). -| **Wiki** | **{check-circle}** Yes | Enables a separate system for [documentation](../wiki/index.md). -| **Snippets** | **{check-circle}** Yes | Enables [sharing of code and text](../../snippets.md). -| **Pages** | **{check-circle}** Yes | Allows you to [publish static websites](../pages/index.md). -| **Releases** | **{check-circle}** Yes | Control access to [Releases](../releases/index.md). -| **Environments** | **{check-circle}** Yes | Control access to [Environments and Deployments](../../../ci/environments/index.md). -| **Feature flags** | **{check-circle}** Yes | Control access to [Feature flags](../../../operations/feature_flags.md). -| **Monitor** | **{check-circle}** Yes | Control access to [Monitor](../../../operations/index.md) features. -| **Infrastructure** | **{check-circle}** Yes | Control access to [Infrastructure](../../infrastructure/index.md) features. - When you disable a feature, the following additional features are also disabled: - If you disable the **Issues** feature, project users cannot use: @@ -111,164 +104,66 @@ When you disable a feature, the following additional features are also disabled: - **Git Large File Storage** - **Packages** -- Metrics dashboard access requires reading project environments and deployments. +- The metrics dashboard requires read access to project environments and deployments. Users with access to the metrics dashboard can also access environments and deployments. -### Manage project access through LDAP groups - -You can [use LDAP to manage group membership](../../group/access_and_permissions.md#manage-group-memberships-via-ldap). - -You cannot use LDAP groups to manage project access, but you can use the following -workaround. - -Prerequisites: - -- You must [integrate LDAP with GitLab](../../../administration/auth/ldap/index.md). -- You must be an administrator. - -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](../members/index.md#add-groups-to-a-project) - to the project. - -## Disable CVE identifier request in issues **(FREE SAAS)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. - -In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. - -To disable the CVE identifier request option in issues in your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. -1. Select **Save changes**. - -## Disable project email notifications - -Prerequisites: - -- You must be an Owner of the project to disable email notifications related to the project. - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Clear the **Disable email notifications** checkbox. - ## Configure merge request settings for a project Configure your project's merge request settings: - Set up the [merge request method](../merge_requests/methods/index.md) (merge commit, fast-forward merge). - Add merge request [description templates](../description_templates.md). -- Enable [merge request approvals](../merge_requests/approvals/index.md). -- Enable [status checks](../merge_requests/status_checks.md). -- Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). -- Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). -- Enable [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). -- Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -- Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). -- Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. -- Enable [Suggested Reviewers](../merge_requests/reviews/index.md#suggested-reviewers). - -## Service Desk - -Enable [Service Desk](../service_desk/index.md) for your project to offer customer support. - -## Export project - -Learn how to [export a project](import_export.md#import-a-project-and-its-data) in GitLab. - -## Advanced project settings - -Use the advanced settings to archive, rename, transfer, -[remove a fork relationship](../repository/forking_workflow.md#unlink-a-fork), or delete a project. - -### Archive a project - -When you archive a project, the repository, packages, issues, merge requests, and all -other features are read-only. Archived projects are also hidden from project listings. - -To archive a project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Archive project** section, select **Archive project**. -1. To confirm, select **OK**. - -### Unarchive a project - -When you unarchive a project, you remove the read-only restriction and make it -available in project lists. - -Prerequisites: - -- To unarchive a project, you must be an administrator or a project Owner. - -1. Find the archived project. - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **View all your projects**. - 1. Select **Explore projects**. - 1. In the **Sort projects** dropdown list, select **Show archived projects**. - 1. In the **Filter by name** field, enter the project name. - 1. Select the project link. -1. On the left sidebar, select **Settings > General**. -1. Under **Advanced**, select **Expand**. -1. In the **Unarchive project** section, select **Unarchive project**. -1. To confirm, select **OK**. - -### Rename a repository - -A project's repository name defines its URL and its place on the file disk -where GitLab is installed. - -Prerequisites: - -You must be a project maintainer, owner, or administrator to rename a repository. - -NOTE: -When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see -[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). - -To rename a repository: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Change path** text box, edit the path. -1. Select **Change path**. - -## Delete the source branch on merge by default +- Enable: + - [Merge request approvals](../merge_requests/approvals/index.md). + - [Status checks](../merge_requests/status_checks.md). + - [Merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). + - [Merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). + - [Required associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). + - [GitLab Duo Suggested Reviewers](../merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) + - [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). +- Configure: + - [Suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). + - [Merge and squash commit message templates](../merge_requests/commit_templates.md). + - [Default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. + +### Delete the source branch on merge by default In merge requests, you can change the default behavior so that the **Delete the source branch** checkbox is always selected. To set this default: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Select **Enable "Delete source branch" option by default**. 1. Select **Save changes**. +## Export project + +You can [export a project and its data](import_export.md#export-a-project-and-its-data). + ## Transfer a project to another namespace When you transfer a project to another namespace, you move the project to a different group. Prerequisites: -- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) to which you are transferring. +- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) you are transferring to. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). -- Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. -- If a security policy is assigned to the project, it is automatically unassigned during the transfer. +- The project must not have a security policy. + If a security policy is assigned to the project, it is automatically unassigned during the transfer. +- If the root namespace changes, you must remove npm packages that follow the [naming convention](../../../user/packages/npm_registry/index.md#naming-convention) from the project. + After you transfer the project you can either: + + - Update the package scope with the new root namespace path, and publish it again to the project. + - Republish the package to the project without updating the root namespace path, which causes the package to no longer follow the naming convention. + If you republish the package without updating the root namespace path, it will not be available at the [instance level endpoint](../../../user/packages/npm_registry/index.md#install-from-the-instance-level). To transfer a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. Under **Transfer project**, choose the namespace to transfer the project to. @@ -283,12 +178,46 @@ to move any project to any namespace. ### Transferring a GitLab SaaS project to a different subscription tier -When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free, the following paid feature data is deleted: +When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free: -- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked +- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked. - [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) and [test cases](../../../ci/test_cases/index.md) are deleted. +## Archive a project + +When you archive a project, the repository, packages, issues, merge requests, and all +other features become read-only. Archived projects are also hidden from project lists. + +To archive a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Archive project** section, select **Archive project**. +1. To confirm, select **OK**. + +## Unarchive a project + +When you unarchive a project, the read-only restriction is removed, +and the project becomes available in project lists. + +Prerequisite: + +- You must be an administrator or have the Owner role for the project. + +1. Find the archived project. + 1. On the left sidebar, select **Search or go to**. + 1. Select **View all my projects**. + 1. Select **Explore projects**. + 1. In the **Sort projects** dropdown list, select **Show archived projects**. + 1. In the **Filter by name** field, enter the project name. + 1. Select the project link. +1. On the left sidebar, select **Settings > General**. +1. Under **Advanced**, select **Expand**. +1. In the **Unarchive project** section, select **Unarchive project**. +1. To confirm, select **OK**. + ## Delete a project > - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. @@ -297,6 +226,10 @@ When you transfer a project from a namespace licensed for GitLab SaaS Premium or > - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [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. You can mark a project to be deleted. +After you delete a project: + +- Projects in personal namespaces are deleted immediately. +- Projects in groups are deleted after a retention period. Prerequisite: @@ -304,7 +237,7 @@ Prerequisite: To delete a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Delete this project** section, select **Delete project**. @@ -312,6 +245,8 @@ To delete a project: This action deletes the project and all associated resources (such as issues and merge requests). +You can also [delete projects using the Rails console](../working_with_projects.md#delete-a-project-using-console). + ### Delayed project deletion **(PREMIUM ALL)** > - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. @@ -323,6 +258,10 @@ Projects in a group (not a personal namespace) can be deleted after a delay peri On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. On SaaS, there is a non-adjustable default retention period of seven days. +You can [view projects that are pending deletion](../working_with_projects.md#view-projects-pending-deletion), +and use the Rails console to +[find projects that are pending deletion](../working_with_projects.md#find-projects-that-are-pending-deletion). + ### Delete a project immediately > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. @@ -340,7 +279,7 @@ Prerequisites: To immediately delete a project marked for deletion: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Delete this project** section, select **Delete project**. @@ -352,39 +291,55 @@ To immediately delete a project marked for deletion: To restore a project marked for deletion: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the Restore project section, select **Restore project**. -## Monitor settings +## Disable project analytics -### Alerts +By default, [analytics for a project](../../analytics/index.md#project-level-analytics) are displayed under the **Analyze** item in the left sidebar. +To disable this feature and remove the **Analyze** item from the left sidebar: -Configure [alert integrations](../../../operations/incident_management/integrations.md#configuration) to triage and manage critical problems in your application as [alerts](../../../operations/incident_management/alerts.md). +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. Turn off the **Analytics** toggle. +1. Select **Save changes**. -### Incidents +## Disable CVE identifier request in issues **(FREE SAAS)** -#### Alert integration +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. -Automatically [create](../../../operations/incident_management/alerts.md#trigger-actions-from-alerts), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. +In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. -#### PagerDuty integration +To disable the CVE identifier request option in issues in your project: -[Create incidents in GitLab for each PagerDuty incident](../../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook). +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. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. +1. Select **Save changes**. -#### Incident settings +## Disable project email notifications -[Manage Service Level Agreements for incidents](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) with an SLA countdown timer. +Prerequisite: -### Error Tracking +- You must have the Owner role for the project. -Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). +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. Clear the **Disable email notifications** checkbox. -### Status Page **(ULTIMATE ALL)** +## Related topics -[Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) -to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). +- [Alert integrations](../../../operations/incident_management/integrations.md#configuration) +- [PagerDuty incident management](../../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook) +- [SLA countdown timer](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) +- [Error tracking](../../../operations/error_tracking.md) +- [Incidents sync](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) +- [Service Desk](../service_desk/index.md) ## Troubleshooting diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 78620eb2ab3..29d57328532 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, howto @@ -55,7 +55,7 @@ all projects that have visibility level set to [Internal](../../public_access.md To create a project access token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Enter an expiry date for the token. @@ -73,12 +73,14 @@ A project access token is displayed. Save the project access token somewhere saf To revoke a project access token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. 1. Next to the project access token to revoke, select **Revoke**. ## Scopes for a project access token +> `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default. + The scope determines the actions you can perform when you authenticate with a project access token. NOTE: @@ -93,6 +95,8 @@ See the warning in [create a project access token](#create-a-project-access-toke | `read_repository` | Grants read access (pull) to the repository. | | `write_repository` | Grants read and write access (pull and push) to the repository. | | `create_runner` | Grants permission to create runners in the project. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project. | ## Enable or disable project access token creation @@ -100,7 +104,7 @@ See the warning in [create a project access token](#create-a-project-access-toke To enable or disable project access token creation for all projects in a top-level group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Allow project and group access token creation**. diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 84ff9efbd14..661f10290c6 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -31,7 +31,7 @@ The filtering options are: ### On an epic -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Epics**. 1. Identify your desired epic, and select its title. 1. Go to the **Activity** section. @@ -39,14 +39,14 @@ The filtering options are: ### On an issue -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues** and find your issue. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. ### On a merge request -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index ec8d886c68e..f9a11a51c98 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -185,7 +185,7 @@ The following time units are available: In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 994ed244832..fb2bd707c56 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -23,7 +23,7 @@ To pair the Web IDE with a remote development environment, see [remote developme To open the Web IDE from the GitLab UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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: @@ -81,6 +81,20 @@ To view a list of files you changed in the Web IDE: 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. +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. + +If your uncommitted changes are not available, you can restore the changes from local history. +To restore uncommitted changes in the Web IDE: + +1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd>. +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 To upload a new file in the Web IDE: @@ -203,7 +217,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 for the Web IDE **(BETA)** WARNING: This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md deleted file mode 100644 index a4c733be376..00000000000 --- a/doc/user/project/web_ide_beta/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../web_ide/index.md' -remove_date: '2023-08-22' ---- - -This document was moved to [another location](../web_ide/index.md). - -<!-- This redirect file can be deleted after <2023-08-22>. --> -<!-- 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/wiki/group.md b/doc/user/project/wiki/group.md index 916c8abf066..ae182f1f183 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -26,7 +26,7 @@ can edit group wikis. Group wiki repositories can be moved using the To access a group wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. To display the wiki, either: - On the left sidebar, select **Plan > Wiki**. - On any page in the group, use the <kbd>g</kbd> + <kbd>w</kbd> @@ -66,7 +66,7 @@ can enable or disable a group wiki through the group settings. To open group settings: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 71fc4dd20a3..4f3aa0d0d49 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -31,7 +31,7 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se To access a project wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. To display the wiki, either: - On the left sidebar, select **Plan > Wiki**. - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> @@ -61,7 +61,7 @@ When a wiki is created, it is empty. On your first visit, you can create the home page users see when viewing the wiki. This page requires a specific title to be used as your wiki's home page. To create it: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Select **Create your first page**. 1. GitLab requires this first page be titled `home`. The page with this @@ -77,7 +77,7 @@ to be used as your wiki's home page. To create it: Users with at least the Developer role can create new wiki pages: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. @@ -138,7 +138,7 @@ may not be able to check out the wiki locally afterward. You need at least the Developer role to edit a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to edit, and either: - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). @@ -157,7 +157,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the Developer role to delete a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to delete. 1. Select the edit icon (**{pencil}**). @@ -168,7 +168,7 @@ You need at least the Developer role to delete a wiki page: You need at least the Developer role to move a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). @@ -192,7 +192,7 @@ The history page shows: To view the changes for a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to view history for. 1. Select **Page history**. @@ -203,7 +203,7 @@ To view the changes for a wiki page: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. @@ -234,7 +234,7 @@ You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. In the upper-right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -257,7 +257,7 @@ A `_sidebar` example, formatted with Markdown: Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) can enable or disable a project wiki by following the instructions in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +[Sharing and permissions](../settings/index.md#configure-project-features-and-permissions). Administrators for self-managed GitLab installs can [configure additional wiki settings](../../../administration/wikis/index.md). @@ -268,7 +268,7 @@ You can disable group wikis from the [group settings](group.md#configure-group-w To add a link to an external wiki from a project's left sidebar: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. @@ -284,7 +284,7 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **External wiki**. 1. Under **Enable integration**, clear the **Active** checkbox. @@ -294,7 +294,7 @@ To hide the link to an external wiki: To disable a project's internal wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 8c050caed17..2a4f0b99246 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -13,7 +13,7 @@ code are saved in projects, and most features are in the scope of projects. To view all projects for the GitLab instance: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Explore**. On the left sidebar, **Projects** is selected. On the right, the list shows @@ -25,7 +25,7 @@ If you are not authenticated, then the list shows public projects only. To view projects you are a member of: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. On the left sidebar, **Projects** is selected. On the list, on the **Yours** tab, @@ -68,7 +68,7 @@ Do not include sensitive information in the name of a topic. To explore project topics: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Explore**. 1. On the left sidebar, select **Topics**. 1. To view projects associated with a topic, select a topic. @@ -110,7 +110,7 @@ To subscribe to a topic: - From a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to. 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). @@ -132,25 +132,9 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. In the upper-right corner of the page, select **Star**. -## Delete a project - -After you delete a project: - -- Projects in personal namespaces are deleted immediately. -- Projects in groups are [deleted after a retention period](../project/settings/index.md#delayed-project-deletion). - -To delete a project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand the **Advanced** section. -1. Scroll down to the **Delete project** section. -1. Select **Delete project**. -1. Confirm this action by completing the field. - ## View projects pending deletion **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. @@ -160,8 +144,8 @@ To delete a project: To view a list of all projects that are pending deletion: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. Based on your GitLab version: - GitLab 14.6 and later: select the **Pending deletion** tab. - GitLab 14.5 and earlier: select the **Deleted projects** tab. @@ -176,7 +160,7 @@ Each project in the list shows: To view the activity of a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Activity**. 1. Optional. To filter activity by contribution type, select a tab: @@ -190,8 +174,8 @@ To view the activity of a project: ## Search in projects -To search through your projects, on the left sidebar, at the top, select **Search GitLab** -(**{search}**). GitLab filters as you type. +To search through your projects, on the left sidebar, select **Search or go to**. +GitLab filters as you type. You can also look for the projects you [starred](#star-a-project) (**Starred projects**). @@ -214,7 +198,7 @@ You can also choose to hide or show archived projects. You can filter projects by the programming language they use. To do this: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select either: - **View all your projects**, to filter your projects. - **Explore**, to filter all projects you can access. @@ -230,7 +214,7 @@ Prerequisite: - You must have the Owner role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. Use the toggle by each feature you want to turn on or off, or change access for. @@ -274,7 +258,7 @@ When you leave a project: To leave a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Leave project**. The **Leave project** option only displays on the project dashboard when a project is part of a group under a [group namespace](../namespace/index.md). @@ -408,18 +392,44 @@ To access the Geo secondary server with HTTP: The `go get` request generates HTTP traffic to the primary Geo server. When the module download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. +## Add a compliance framework to a project **(PREMIUM)** + +You can add compliance frameworks to projects in a group that has a [compliance framework](../group/compliance_frameworks.md). + +## Manage project access through LDAP groups + +You can [use LDAP to manage group membership](../group/access_and_permissions.md#manage-group-memberships-via-ldap). + +You cannot use LDAP groups to manage project access, but you can use the following workaround. + +Prerequisites: + +- You must [integrate LDAP with GitLab](../../administration/auth/ldap/index.md). +- You must be an administrator. + +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. + ## Related topics - [Import a project](../../user/project/import/index.md). - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). - [Fork a project](repository/forking_workflow.md#create-a-fork). -- [Adjust project visibility and access levels](settings/index.md#configure-project-visibility-features-and-permissions). +- Adjust [project visibility](../../user/public_access.md#change-project-visibility) and [permissions](settings/index.md#configure-project-features-and-permissions). - [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) ## Troubleshooting When working with projects, you might encounter the following issues, or require alternate methods to complete specific tasks. +### `An error occurred while fetching commit data` + +When you visit a project, the message `An error occurred while fetching commit data` might be displayed +if you use an ad blocker in your browser. The solution is to disable your ad blocker +for the GitLab instance you are trying to access. + ### Find projects using an SQL query While in [a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session), you can find and store an array of projects based on a SQL query: diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 5f43f177e36..37b79c8f1a8 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -67,7 +67,7 @@ Prerequisite: - You must have the Owner role for a project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. @@ -86,7 +86,7 @@ Prerequisites: 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. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Naming, visibility**. 1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index bad62825ba5..45113562e87 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -1,5 +1,5 @@ --- -stage: Anti-Abuse +stage: Govern group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -24,10 +24,19 @@ You can report a user through their: ## Report abuse from the user's profile page +> - Report abuse from overflow menu [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `user_profile_overflow_menu_vue`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.4. + +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 `user_profile_overflow_menu_vue`. +On GitLab.com, this feature is available. + To report abuse from a user's profile page: 1. Anywhere in GitLab, select the name of the user. -1. In the upper-right corner of the user's profile, select **Report abuse to administrator** (**{information-o}**). +1. In the upper-right corner of the user's profile, if the `user_profile_overflow_menu_vue` feature flag is: + - Enabled, select the vertical ellipsis (**{ellipsis_v}**), then **Report abuse to administrator**. + - Disabled, select **Report abuse to administrator** (**{information-o}**). 1. Select a reason for reporting the user. 1. Complete an abuse report. 1. Select **Send report**. diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index c12d7889fb8..c1da3e9e2ba 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -39,8 +39,6 @@ You can use advanced search in: Advanced search uses [Elasticsearch syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html#simple-query-string-syntax). The syntax supports both exact and fuzzy search queries. -<!-- markdownlint-disable --> - | Syntax | Description | Example | |--------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | `"` | Exact search | [`"gem sidekiq"`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=%22gem+sidekiq%22) | @@ -53,11 +51,12 @@ Advanced search uses [Elasticsearch syntax](https://www.elastic.co/guide/en/elas | `#` | Issue ID | [`#23456`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) | | `!` | Merge request ID | [`!23456`](https://gitlab.com/search?snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) | -### Refining user search +### User search -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388409) in GitLab 15.10. +> Ability to refine user search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388409) in GitLab 15.10. -In user search, a [fuzzy query](https://www.elastic.co/guide/en/elasticsearch/reference/7.2/query-dsl-fuzzy-query.html) is used by default. You can refine your search with [Elasticsearch syntax](#syntax). +When you search for a user, a [fuzzy query](https://www.elastic.co/guide/en/elasticsearch/reference/7.2/query-dsl-fuzzy-query.html) is used by default. +You can refine user search with [Elasticsearch syntax](#syntax). ### Code search @@ -68,11 +67,13 @@ In user search, a [fuzzy query](https://www.elastic.co/guide/en/elasticsearch/re | `extension:` | File extension without `.` <sup>2</sup> | [`extension:js`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=extension%3Ajs&snippets=) | | `blob:` | Git object ID <sup>2</sup> | [`blob:998707*`](https://gitlab.com/search?snippets=false&scope=blobs&repository_ref=&search=blob%3A998707*&group_id=9970) | -1. `path:` returns matches for full paths or subpaths. +1. `path:` returns matches for full or partial paths. 1. `extension:` and `blob:` return exact matches only. ### Examples +<!-- markdownlint-disable MD044 --> + | Query | Description | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | [`rails -filename:gemfile.lock`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=rails+-filename%3Agemfile.lock&snippets=) | Returns `rails` in all files except the `gemfile.lock` file. | @@ -81,7 +82,6 @@ In user search, a [fuzzy query](https://www.elastic.co/guide/en/elasticsearch/re | [<code>helper -extension:yml -extension:js</code>](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=helper+-extension%3Ayml+-extension%3Ajs&snippets=) | Returns `helper` in all files except files with a `.yml` or `.js` extension. | | [<code>helper path:lib/git</code>](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=helper+path%3Alib%2Fgit) | Returns `helper` in all files with a `lib/git*` path (for example, `spec/lib/gitlab`). | - <!-- markdownlint-enable --> ## Known issues @@ -89,8 +89,8 @@ In user search, a [fuzzy query](https://www.elastic.co/guide/en/elasticsearch/re - You can only search files smaller than 1 MB. For more information, see [issue 195764](https://gitlab.com/gitlab-org/gitlab/-/issues/195764). For self-managed GitLab instances, an administrator can - [change this limit](../../integration/advanced_search/elasticsearch.md#advanced-search-configuration). -- You can only use advanced search on the default branch of a project. + [configure this setting](../../integration/advanced_search/elasticsearch.md#advanced-search-configuration). +- You can use advanced search on the default branch of a project only. For more information, see [issue 229966](https://gitlab.com/gitlab-org/gitlab/-/issues/229966). - The search query must not contain any of the following characters: diff --git a/doc/user/search/command_palette.md b/doc/user/search/command_palette.md index 671afe13ace..0f42e727eda 100644 --- a/doc/user/search/command_palette.md +++ b/doc/user/search/command_palette.md @@ -7,21 +7,17 @@ type: reference # Command palette **(FREE ALL)** -> Introduced in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `command_palette`. Enabled by default. +> - Introduced in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `command_palette`. Enabled by default. +> - Feature flag `command_palette` removed in GitLab 16.4. You can use command palette to narrow down the scope of your search or to find an object more quickly. -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 `command_palette`. -On GitLab.com, this feature is available. - ## Open the command palette To open the command palette: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) or use the <kbd>/</kbd> key to enable. +1. On the left sidebar, at the top, select **Search or go to** or use the <kbd>/</kbd> key to enable. 1. Type one of the special characters: - <kbd>></kbd> - Create a new object or find a menu item. diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md index 8a64dc9e70f..48445ccfc3c 100644 --- a/doc/user/search/exact_code_search.md +++ b/doc/user/search/exact_code_search.md @@ -28,5 +28,19 @@ searches. ## Syntax -To understand the possible filtering options, see the -[Zoekt query syntax](https://github.com/sourcegraph/zoekt/blob/main/doc/query_syntax.md). +This table shows some example queries for exact code search. + +| Query | Description | +| -------------------- |-------------------------------------------------------------------------------------- | +| `foo` | Returns files that contain `foo` | +| `"class foo"` | Returns files that contain the exact string `class foo` | +| `class foo` | Returns files that contain both `class` and `foo` | +| `foo or bar` | Returns files that contain either `foo` or `bar` | +| `class Foo` | Returns files that contain `class` (case insensitive) and `Foo` (case sensitive) | +| `class Foo case:yes` | Returns files that contain `class` and `Foo` (both case sensitive) | +| `foo -bar` | Returns files that contain `foo` but not `bar` | +| `foo file:js` | Searches for `foo` in files with names that contain `js` | +| `foo -file:test` | Searches for `foo` in files with names that do not contain `test` | +| `foo lang:ruby` | Searches for `foo` in Ruby source code | +| `foo f:\.js$` | Searches for `foo` in files with names that end with `.js` | +| `foo.*bar` | Searches for strings that match the regular expression `foo.*bar` | diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 5600f18c61c..8c7db5ca29e 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -17,23 +17,26 @@ Both types of search are the same, except when you are searching through code. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68640) in GitLab 14.3. -To improve the performance of your instance's global search, a GitLab administrator -can limit the search scope by disabling the following [`ops` feature flags](../../development/feature_flags/index.md#ops-type). - -| Scope | Feature flag | Description | -|--|--|--| -| Code | `global_search_code_tab` | When enabled, global search includes code. | -| Commits | `global_search_commits_tab` | When enabled, global search includes commits. | -| Issues | `global_search_issues_tab` | When enabled, global search includes issues. | -| Merge requests | `global_search_merge_requests_tab` | When enabled, global search includes merge requests. | -| Users | `global_search_users_tab` | When enabled, global search includes users. | -| Wiki | `global_search_wiki_tab` | When enabled, global search includes project and [group wikis](../project/wiki/group.md). | +To improve the performance of your instance's global search, an administrator can limit the search scope +by disabling one or more [`ops` feature flags](../../development/feature_flags/index.md#ops-type). + +| Scope | Feature flag | Description | +|----------------|------------------------------------|-------------------------------------------------------------------------------------------| +| Code | `global_search_code_tab` | When enabled, global search includes code. | +| Commits | `global_search_commits_tab` | When enabled, global search includes commits. | +| Issues | `global_search_issues_tab` | When enabled, global search includes issues. | +| Merge requests | `global_search_merge_requests_tab` | When enabled, global search includes merge requests. | +| Users | `global_search_users_tab` | When enabled, global search includes users. | +| Wiki | `global_search_wiki_tab` | When enabled, global search includes project and [group wikis](../project/wiki/group.md). | All global search scopes are enabled by default on self-managed instances. ## Global search validation -Global search ignores and logs as abusive any search with: +> - Support for partial matches in issue search [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71913) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `issues_full_text_search`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124703) in GitLab 16.2. Feature flag `issues_full_text_search` removed. + +Global search ignores and logs as abusive any search that includes: - Fewer than two characters - A term longer than 100 characters (URL search terms must not exceed 200 characters) @@ -47,11 +50,28 @@ Global search only flags with an error any search that includes more than: - 4096 characters - 64 terms +Partial matches are not supported in issue search. +For example, when you search issues for `play`, the query does not return issues that contain `display`. +However, the query matches all possible variations of the string (for example, `plays`). + +## Autocomplete suggestions + +As you type in the search box, autocomplete suggestions are displayed for: + +- [Projects](#search-for-a-project-by-full-path) and groups +- Users +- Help pages +- Project features (for example, milestones) +- Settings (for example, user settings) +- Recently viewed merge requests +- Recently viewed issues and epics +- [GitLab Flavored Markdown references](../markdown.md#gitlab-specific-references) for issues in a project + ## Search in all GitLab To search in all GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). +1. On the left sidebar, at the top, select **Search or go to**. 1. Type your search query. You must type at least two characters. 1. Press <kbd>Enter</kbd> to search, or select from the list. @@ -61,18 +81,56 @@ The results are displayed. To filter the results, on the left sidebar, select a To search in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Search GitLab** (**{search}**) again and type the string you want to search for. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Search or go to** again and type the string you want to search for. 1. Press <kbd>Enter</kbd> to search, or select from the list. The results are displayed. To filter the results, on the left sidebar, select a filter. +## Search for a project by full path + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. + +You can search for a project by entering its full path (including the namespace it belongs to) in the search box. +As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. + +For example: + +- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. +- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. + +## Include archived projects in search results + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121981) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `search_projects_hide_archived`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/413821) in GitLab 16.3. Feature flag `search_projects_hide_archived` removed. + +By default, archived projects are excluded from search results. +To include archived projects: + +1. On the project search page, on the left sidebar, select the **Include archived** checkbox. +1. On the left sidebar, select **Apply**. + +## Exclude issues in archived projects from search results + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124846) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `search_issues_hide_archived_projects`. 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 `search_issues_hide_archived_projects`. On GitLab.com, this feature is not available. + +By default, issues in archived projects are included in search results. +To exclude issues in archived projects, ensure the `search_issues_hide_archived_projects` flag is enabled. + +To include issues in archived projects with `search_issues_hide_archived_projects` enabled, +you must add the parameter `include_archived=true` to the URL. + ## Search for code To search for code in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Search GitLab** (**{search}**) again and type the code you want to search for. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Search or go to** again and type the code you want to search for. 1. Press <kbd>Enter</kbd> to search, or select from the list. Code search shows only the first result in the file. @@ -97,110 +155,26 @@ To filter code search results by one or more languages: 1. On the code search page, on the left sidebar, select one or more languages. 1. On the left sidebar, select **Apply**. -## Exclude search results - -### From archived projects - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121981) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `search_projects_hide_archived`. 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 `search_projects_hide_archived`. On GitLab.com, this feature is not available. - -Archived projects are included in search results by default. To exclude archived projects, ensure the `search_projects_hide_archived` flag is enabled. - -To include archived projects with `search_projects_hide_archived` enabled, you must add the parameter `include_archived=true` to the URL. - -### From issues in archived projects - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124846) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `search_issues_hide_archived_projects`. 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 `search_issues_hide_archived_projects`. On GitLab.com, this feature is not available. - -Issues in archived projects are included in search results by default. To exclude issues in archived projects, ensure the `search_issues_hide_archived_projects` flag is enabled. - -To include issues in archived projects with `search_issues_hide_archived_projects` enabled, you must add the parameter `include_archived=true` to the URL. - -## Search for a project by full path - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. - -You can search for a project by entering its full path (including the namespace it belongs to) in the search box. -As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. - -For example: - -- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. -- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. - ## Search for a commit SHA To search for a commit SHA: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Search GitLab** (**{search}**) again and type the commit SHA you want to search for. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Search or go to** again and type the commit SHA you want to search for. 1. Press <kbd>Enter</kbd> to search, or select from the list. If a single result is returned, GitLab redirects to the commit result and gives you the option to return to the search results page. -## Search for specific terms - -> - [Support for partial matches in issue search](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71913) removed in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `issues_full_text_search`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124703) in GitLab 16.2. Feature flag `issues_full_text_search` removed. - -You can filter issues and merge requests by specific terms included in titles or descriptions. - -- Syntax - - Searches look for all the words in a query, in any order. For example: searching - issues for `display bug` returns all issues matching both those words, in any order. - - To find the exact term, use double quotes: `"display bug"`. -- Limitation - - For performance reasons, terms shorter than three characters are ignored. For example: searching - issues for `included in titles` is same as `included titles` - - Search is limited to 4096 characters and 64 terms per query. - - When searching issues, partial matches are not allowed. For example: searching for `play` will - not return issues that have the word `display`. But variations of words match, so searching - for `displays` also returns issues that have the word `display`. - ## Run a search from history You can run a search from history for issues and merge requests. Search history is stored locally in your browser. To run a search from history: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. To view recent searches: - For issues, on the left sidebar, select **Plan > Issues**. Above the list, to the left of the search box, select (**{history}**). - For merge requests, on the left sidebar, select **Code > Merge requests**. Above the list, to the left of the search box, select **Recent searches**. 1. From the dropdown list, select a search. - -## Remove search filters - -Individual filters can be removed by selecting the filter's (x) button or backspacing. The entire search filter can be cleared by selecting the search box's (x) button or via <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd>. - -To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> keyboard combination can be used. - -## Autocomplete suggestions - -In the search box, you can view autocomplete suggestions for: - -- [Projects](#search-for-a-project-by-full-path) and groups -- Users -- Various help pages (try and type **API help**) -- Project feature pages (try and type **milestones**) -- Various settings pages (try and type **user settings**) -- Recently viewed issues (try and type some word from the title of a recently viewed issue) -- Recently viewed merge requests (try and type some word from the title of a recently viewed merge request) -- Recently viewed epics (try and type some word from the title of a recently viewed epic) -- [GitLab Flavored Markdown](../markdown.md#gitlab-specific-references) (GLFM) for issues in a project (try and type a GLFM reference for an issue) - -## Search settings - -You can search inside a Project, Group, Administrator, or User's settings by entering -a search term in the search box located at the top of the page. The search results -appear highlighted in the sections that match the search term. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index d8b4d147d24..b0ef1fcc99a 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -109,18 +109,19 @@ These shortcuts are available when viewing issues: These shortcuts are available when viewing [merge requests](project/merge_requests/index.md): -| macOS shortcut | Windows shortcut | Description | -|-----------------------------------|---------------------|-------------| -| <kbd>]</kbd> or <kbd>j</kbd> | | Move to next file. | -| <kbd>[</kbd> or <kbd>k</kbd> | | Move to previous file. | +| macOS shortcut | Windows shortcut | Description | +|-----------------------------------|-----------------------------------|-------------| +| <kbd>]</kbd> or <kbd>j</kbd> | | Move to next file. | +| <kbd>[</kbd> or <kbd>k</kbd> | | Move to previous file. | | <kbd>Command</kbd> + <kbd>p</kbd> | <kbd>Control</kbd> + <kbd>p</kbd> | Search for, and then jump to a file for review. | -| <kbd>n</kbd> | | Move to next unresolved discussion. | -| <kbd>p</kbd> | | Move to previous unresolved discussion. | -| <kbd>b</kbd> | | Copy source branch name. | -| <kbd>c</kbd> + <kbd>r</kbd> | | Copy merge request reference. | -| <kbd>r</kbd> | | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | -| <kbd>c</kbd> | | Move to next commit. | -| <kbd>x</kbd> | | Move to previous commit. | +| <kbd>n</kbd> | | Move to next unresolved discussion. | +| <kbd>p</kbd> | | Move to previous unresolved discussion. | +| <kbd>b</kbd> | | Copy source branch name. | +| <kbd>c</kbd> + <kbd>r</kbd> | | Copy merge request reference. | +| <kbd>r</kbd> | | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | +| <kbd>c</kbd> | | Move to next commit. | +| <kbd>x</kbd> | | Move to previous commit. | +| <kbd>f</kbd> | | Toggle file browser. | ### Project files @@ -324,20 +325,25 @@ These shortcuts are available when viewing [epics](group/epics/index.md): ## Disable keyboard shortcuts -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22113) in GitLab 12.8. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/202494) from the shortcuts page to user preferences in GitLab 16.4. To disable keyboard shortcuts: -1. While viewing a page that supports keyboard shortcuts, and outside a text box, -press <kbd>?</kbd> to display the list of shortcuts. -1. Select **Toggle shortcuts**. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Behavior** section, clear the **Enable keyboard shortcuts** checkbox. +1. Select **Save changes**. ## Enable keyboard shortcuts +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/202494) from the shortcuts page to user preferences in GitLab 16.4. + To enable keyboard shortcuts: -1. On the left sidebar, at the bottom, select **Help** (**{question}**), then **Keyboard shortcuts**. -1. Select **Toggle shortcuts**. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Behavior** section, select the **Enable keyboard shortcuts** checkbox. +1. Select **Save changes**. ## Troubleshooting diff --git a/doc/user/snippets.md b/doc/user/snippets.md index a5a547727d3..dbcc90c26df 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -63,17 +63,17 @@ In GitLab versions 13.0 and later, snippets are [versioned by default](#versione To discover all snippets visible to you in GitLab, you can: - **View a project's snippets**: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Snippets**. - **View all the snippets you created**: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Select **Snippets**. On GitLab.com, you can also visit your [snippets directly](https://gitlab.com/dashboard/snippets). - **Explore all public snippets**: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Explore**. 1. Select **Snippets**. @@ -110,11 +110,11 @@ content was saved as the initial commit to the snippets' repository. ## Filenames Snippets support syntax highlighting based on the filename and -extension provided for them. While you can submit a snippet -without a filename and extension, it needs a valid name so the -content can be created as a file in the snippet's repository. +extension provided for them. You can submit a snippet +without a filename and extension, but a valid name is required for +creating content as a file in the repository. -If you don't give a snippet a filename and extension, +If no filename and extension are provided for the snippet, GitLab adds a filename in the format `snippetfile<x>.txt` where `<x>` represents a number added to the file, starting with 1. This number increments if you add more unnamed snippets. @@ -138,7 +138,7 @@ A single snippet can support up to 10 files, which helps keep related files toge - A `gulpfile.js` file and a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. -If you need more than 10 files for your snippet, we recommend you create a +If you need more than 10 files for your snippet, you should create a [wiki](project/wiki/index.md) instead. Wikis are available for projects at all subscription levels, and [groups](project/wiki/group.md) for [GitLab Premium](https://about.gitlab.com/pricing/). @@ -167,9 +167,9 @@ To delete a file from your snippet through the GitLab UI: ## Clone snippets -Instead of copying a snippet to a local file, you may want to clone a snippet to -preserve its relationship with the repository, so you can receive or make updates -as needed. Select **Clone** on a snippet to display the URLs to clone with SSH or HTTPS: +To ensure you receive updates, clone the snippet instead of copying it locally. Cloning +maintains the snippet's connection with the repository. Select **Clone** on a snippet +to display the URLs to clone with SSH or HTTPS:  @@ -229,7 +229,7 @@ Prerequisites: To do this task: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Code > Snippets**. 1. Select the snippet you want to report as spam. 1. Select **Submit as spam**. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index f418cc5f6b7..0e10fea18ad 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -22,7 +22,7 @@ SSH uses two keys, a public key and a private key. It is not possible to reveal confidential data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. -You can use your private key to [sign commits](project/repository/ssh_signed_commits/index.md), +You can use your private key to [sign commits](project/repository/signed_commits/ssh.md), which makes your use of GitLab and your data even more secure. This signature then can be verified by anyone using your public key. @@ -74,11 +74,16 @@ must have [OpenSSH 8.2](https://www.openssh.com/releasenotes.html#8.2) or later ### RSA SSH keys +> Maximum RSA key length [changed](https://gitlab.com/groups/gitlab-org/-/epics/11186) in GitLab 16.3. + Available documentation suggests ED25519 is more secure than RSA. If you use an RSA key, the US National Institute of Standards and Technology in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) -recommends a key size of at least 2048 bits. The default key size depends on your version of `ssh-keygen`. +recommends a key size of at least 2048 bits. Due to limitations in Go, +RSA keys [cannot exceed 8192 bits](#tls-server-sent-certificate-containing-rsa-key-larger-than-8192-bits). + +The default key size depends on your version of `ssh-keygen`. Review the `man` page for your installed `ssh-keygen` command for details. ## See if you have an existing SSH key pair @@ -523,6 +528,17 @@ are **explicitly not supported** and may stop working at any time. ## Troubleshooting +### TLS: server sent certificate containing RSA key larger than 8192 bits + +In GitLab 16.3 and later, Go limits RSA keys to a maximum of 8192 bits. +To check the length of a key: + +```shell +openssl rsa -in <your-key-file> -text -noout | grep "Key:" +``` + +Replace any key longer than 8192 bits with a shorter key. + ### Password prompt with `git clone` When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`. diff --git a/doc/user/storage_management_automation.md b/doc/user/storage_management_automation.md index 210aca4ee35..9a505d23597 100644 --- a/doc/user/storage_management_automation.md +++ b/doc/user/storage_management_automation.md @@ -28,7 +28,7 @@ You must use the following scopes to [authenticate](../api/rest/index.md#authent - Full API access with the `api` scope. - At least the Maintainer role on all projects. -You can use command line tools or a programming language to interact with the REST API. +You can use command-line tools or a programming language to interact with the REST API. ### Command line @@ -71,7 +71,7 @@ see [Efficient DevSecOps workflows: Hands-on `python-gitlab` API automation](htt For more information about other API client libraries, see [Third-party clients](../api/rest/index.md#third-party-clients). NOTE: -Use [GitLab Duo Code Suggestions](project/repository/code_suggestions.md) to write code more efficiently. +Use [GitLab Duo Code Suggestions](project/repository/code_suggestions/index.md) to write code more efficiently. ## Strategies for storage analysis diff --git a/doc/user/tasks.md b/doc/user/tasks.md index c340bb736ef..f4fec01d42b 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Known limitation: -- [Tasks currently cannot be accessed via REST API.](https://gitlab.com/gitlab-org/gitlab/-/issues/368055) +- [Tasks cannot be accessed via REST API.](https://gitlab.com/gitlab-org/gitlab/-/issues/368055) For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitlab-org/-/epics/7103). @@ -41,7 +41,7 @@ View tasks in issues, in the **Tasks** section. You can also [filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = task`. -If you select a task from an issue, it opens in a modal window. +If you select a task from an issue, it opens in a dialog window. If you select a task to open in a new browser tab, or select it from the issue list, the task opens in a full-page view. @@ -107,7 +107,7 @@ To edit a task: ### Using the rich text editor -> - Rich text editing in the modal view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363007) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `work_items_mvc`. Disabled by default. +> - Rich text editing in the dialog view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363007) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `work_items_mvc`. Disabled by default. > - Rich text editing in the full page view [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104533) in GitLab 15.7. FLAG: @@ -336,7 +336,7 @@ To refer to a task elsewhere in GitLab, you can use its full URL or a short refe To copy the task reference to your clipboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your task to view it. 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. @@ -356,7 +356,7 @@ For more information about creating comments by sending an email and the necessa To copy the task's email address: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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**. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index ade99a5fef8..8c6840fae92 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -23,7 +23,7 @@ Prerequisites: - To view storage usage for a project, you must have at least the Maintainer role for the project or Owner role for the namespace. - To view storage usage for a namespace, you must have the Owner role for the namespace. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. Select the **Storage** tab. @@ -179,7 +179,11 @@ available decreases. All projects no longer have the read-only status because 40 ## Namespace storage limit Namespaces on GitLab SaaS have a storage limit. For more information, see our [pricing page](https://about.gitlab.com/pricing/). -This limit is not visible on the **Usage quotas** page, but is prior to the limit being [applied](#namespace-storage-limit-application-schedule). Self-managed deployments are not affected. + +After namespace storage limits are enforced, view them in the **Usage quotas** page. +For more information about the namespace storage limit enforcement, see the FAQ pages for the [Free](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier) and [Paid](https://about.gitlab.com/pricing/faq-paid-storage-transfer/) tiers. + +Namespace storage limits do not apply to self-managed deployments, but administrators can [manage the repository size](../administration/settings/account_and_limit_settings.md#repository-size-limit). Storage types that add to the total namespace storage are: @@ -196,17 +200,20 @@ If your total namespace storage exceeds the available namespace storage quota, a To notify you that you have nearly exceeded your namespace storage quota: -- In the command line interface, a notification displays after each `git push` action when you've reached 95% and 100% of your namespace storage quota. +- In the command-line interface, a notification displays after each `git push` action when you've reached 95% and 100% of your namespace storage quota. - In the GitLab UI, a notification displays when you've reached 75%, 95%, 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%. -To prevent exceeding the namespace storage quota, you can: +To prevent exceeding the namespace storage limit, you can: -- Reduce storage consumption by following the suggestions in the [Manage Your Storage Usage](#manage-your-storage-usage) section of this page. -- Apply for [GitLab for Education](https://about.gitlab.com/solutions/education/join/), [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/), or [GitLab for Startups](https://about.gitlab.com/solutions/startups/) if you meet the eligibility requirements. -- Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab which does not have these limits on the free tier. +- [Manage your storage usage](#manage-your-storage-usage). +- If you meet the eligibility requirements, you can apply for: + - [GitLab for Education](https://about.gitlab.com/solutions/education/join/) + - [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/) + - [GitLab for Startups](https://about.gitlab.com/solutions/startups/) +- Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab, which does not have these limits on the Free tier. - [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10 GB of storage. -- [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) which include higher limits and features that enable growing teams to ship faster without sacrificing on quality. +- [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), which include higher limits and features to enable growing teams to ship faster without sacrificing on quality. - [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. ### View project fork storage usage @@ -215,14 +222,10 @@ A cost factor is applied to the storage consumed by project forks so that forks To view the amount of namespace storage the fork has used: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. Select the **Storage** tab. The **Total** column displays the amount of namespace storage used by the fork as a portion of the actual size of the fork on disk. The cost factor applies to the project repository, LFS objects, job artifacts, packages, snippets, and the wiki. The cost factor does not apply to private forks in namespaces on the Free plan. - -### Namespace storage limit application schedule - -Information on when namespace-level storage limits are applied is available on these FAQ pages for the [Free](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier) and [Paid](https://about.gitlab.com/pricing/faq-paid-storage-transfer/) tier. diff --git a/doc/user/workspace/configuration.md b/doc/user/workspace/configuration.md index 3900c95e41a..3684845c2c7 100644 --- a/doc/user/workspace/configuration.md +++ b/doc/user/workspace/configuration.md @@ -4,7 +4,7 @@ group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspace configuration (Beta) **(PREMIUM ALL)** +# Workspace configuration **(PREMIUM ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. @@ -25,6 +25,8 @@ which you can customize to meet the specific needs of each project. ## Set up a workspace +> Support for private projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124273) in GitLab 16.4. + ### Prerequisites - Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. @@ -48,8 +50,8 @@ which you can customize to meet the specific needs of each project. You can use any agent defined under the root group of your project, provided that remote development is properly configured for that agent. - You must have at least the Developer role in the root group. -- In each public project you want to use this feature for, create a [devfile](index.md#devfile): - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +- In each project you want to use this feature for, create a [devfile](index.md#devfile): + 1. On the left sidebar, select **Search or go to** and find your project. 1. In the root directory of your project, create a file named `.devfile.yaml`. You can use one of the [example configurations](index.md#example-configurations). - Ensure the container images used in the devfile support [arbitrary user IDs](index.md#arbitrary-user-ids). @@ -58,12 +60,11 @@ which you can customize to meet the specific needs of each project. To create a workspace: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Select **Workspaces**. 1. Select **New workspace**. 1. From the **Select project** dropdown list, [select a project with a `.devfile.yaml` file](#prerequisites). - You can only create workspaces for public projects. 1. From the **Select cluster agent** dropdown list, select a cluster agent owned by the group the project belongs to. 1. In **Time before automatic termination**, enter the number of hours until the workspace automatically terminates. This timeout is a safety measure to prevent a workspace from consuming excessive resources or running indefinitely. @@ -75,6 +76,8 @@ You also have access to the terminal and can install any necessary dependencies. ## Connect to a workspace with SSH +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10478) in GitLab 16.3. + Prerequisites: - SSH must be enabled for the workspace. diff --git a/doc/user/workspace/create_image.md b/doc/user/workspace/create_image.md index 43140a622e0..df70ff31194 100644 --- a/doc/user/workspace/create_image.md +++ b/doc/user/workspace/create_image.md @@ -4,7 +4,7 @@ group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Create a custom workspace image that supports arbitrary user IDs (Beta) **(PREMIUM ALL)** +# Tutorial: Create a custom workspace image that supports arbitrary user IDs **(PREMIUM ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 51e3e905a92..1284067a391 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/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://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspaces (Beta) **(PREMIUM ALL)** +# Workspaces **(PREMIUM ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. @@ -35,7 +35,8 @@ When you [create a workspace](configuration.md#set-up-a-workspace), you must: - Assign the workspace to a specific project. - Select a project with a [`.devfile.yaml`](#devfile) file. -The workspace can then interact with the GitLab API based on the permissions granted to the current user. +The workspace can interact with the GitLab API, with the access level defined by current user permissions. +A running workspace remains accessible even if user permissions are later revoked. ### Open and manage workspaces from a project @@ -43,7 +44,7 @@ The workspace can then interact with the GitLab API based on the permissions gra To open a workspace from a file or the repository file list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. In the upper right, select **Edit**. 1. From the dropdown list, under **Your workspaces**, select the workspace. @@ -128,13 +129,15 @@ The Web IDE is the only code editor available for workspaces. The Web IDE is powered by the [GitLab VS Code fork](https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork). For more information, see [Web IDE](../project/web_ide/index.md). -## Private repositories +## Personal access token -You cannot [create a workspace](configuration.md#set-up-a-workspace) for a private repository -because GitLab does not inject any credentials into the workspace. -You can only create a workspace for public repositories that have a devfile. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129715) in GitLab 16.4. -From a workspace, you can clone any repository manually. +When you [create a workspace](configuration.md#set-up-a-workspace), you get a personal access token with `write_repository` permission. +This token is used to initially clone the project while starting the workspace. + +Any Git operation you perform in the workspace uses this token for authentication and authorization. +When you terminate the workspace, the token is revoked. ## Pod interaction in a cluster |
